From 4666406bcbb87bb084e892ac6511c1e8422d6014 Mon Sep 17 00:00:00 2001 From: Carlos Reynosa Date: Sat, 25 Oct 2025 10:54:03 -0700 Subject: [PATCH 1/3] Refactor upgrade detection and maintenance tasks There needs to be a process for detecting when a full upgrade is necessary versus only a db upgrade. 1. Update main tasks to run general upgrade process that runs either full upgrade or partial db upgrade 2. Update maintenance check to check for general upgrade needed status 3. Add full full_upgrade_needed variable will define if a full upgrade is necessary --- recipe/magento2.php | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/recipe/magento2.php b/recipe/magento2.php index d496dcd1c..4142d4200 100644 --- a/recipe/magento2.php +++ b/recipe/magento2.php @@ -130,7 +130,7 @@ }); set('database_upgrade_needed', function () { - // detect if setup:upgrade is needed + // detect if db upgrade is needed try { run('{{bin/php}} {{bin/magento}} setup:db:status'); } catch (RunException $e) { @@ -144,6 +144,21 @@ return false; }); +set('full_upgrade_needed', function(){ + //Some conditions, such as new RabittMQ services require a full upgrade and are not detecet by setup:db:status + //TODO: Add checks, once implemented, for detecting necessary full upgrade process. See future RabbitMQ Check: https://github.com/magento/magento2/pull/39698 + return false; +}); + +set('upgrade_needed', function(){ + // Detect necessary upgrade, partial db or full upgrade + try{ + return get('database_upgrade_needed') || get('full_upgrade_needed'); + }catch (RunException $e){ + throw $e; + } +}); + // Deploy without setting maintenance mode if possible set('enable_zerodowntime', true); @@ -274,7 +289,7 @@ function magentoDeployAssetsSplit(string $area) desc('Set maintenance mode if needed'); task('magento:maintenance:enable-if-needed', function () { - ! get('enable_zerodowntime') || get('database_upgrade_needed') || get('config_import_needed') ? + ! get('enable_zerodowntime') || get('upgrade_needed') || get('config_import_needed') ? invoke('magento:maintenance:enable') : writeln('Config and database up to date => no maintenance mode'); }); @@ -296,6 +311,15 @@ function magentoDeployAssetsSplit(string $area) } else { writeln('Database schema is up to date => upgrade skipped'); } +}); + +desc('Run upgrades if needed'); +task('magento:upgrade', function () { + if (get('full_upgrade_needed')) { + run("{{bin/php}} {{bin/magento}} setup:upgrade --keep-generated"); + } else if(get('database_upgrade_needed')) { + invoke('magento:upgrade:db'); + } })->once(); desc('Flushes Magento Cache'); @@ -308,7 +332,7 @@ function magentoDeployAssetsSplit(string $area) 'magento:build', 'magento:maintenance:enable-if-needed', 'magento:config:import', - 'magento:upgrade:db', + 'magento:upgrade', 'magento:maintenance:disable', ]); @@ -519,7 +543,7 @@ function magentoDeployAssetsSplit(string $area) * Install cron in crontab * To use this feature, add the following to your deployer scripts: * ```php - * after('magento:upgrade:db', 'magento:cron:install'); + * after('magento:upgrade', 'magento:cron:install'); * ``` */ desc('Install cron in crontab'); @@ -555,7 +579,7 @@ function magentoDeployAssetsSplit(string $area) 'artifact:prepare', 'magento:maintenance:enable-if-needed', 'magento:config:import', - 'magento:upgrade:db', + 'magento:upgrade', 'magento:maintenance:disable', 'deploy:symlink', 'artifact:finish', From e4f07c68f67c63c7458cd7d3e56aa8c1fce95318 Mon Sep 17 00:00:00 2001 From: Carlos Reynosa Date: Sat, 25 Oct 2025 13:31:59 -0700 Subject: [PATCH 2/3] Update magento 2 docs. --- docs/recipe/magento2.md | 117 +++++++++++++++++++++++++--------------- 1 file changed, 74 insertions(+), 43 deletions(-) diff --git a/docs/recipe/magento2.md b/docs/recipe/magento2.md index 54a820d21..296201eb0 100644 --- a/docs/recipe/magento2.md +++ b/docs/recipe/magento2.md @@ -45,7 +45,7 @@ The [deploy](#deploy) task of **Magento 2** consists of: * [magento:deploy:assets](/docs/recipe/magento2.md#magento-deploy-assets) – Deploys assets * [magento:maintenance:enable-if-needed](/docs/recipe/magento2.md#magento-maintenance-enable-if-needed) – Set maintenance mode if needed * [magento:config:import](/docs/recipe/magento2.md#magento-config-import) – Config Import - * [magento:upgrade:db](/docs/recipe/magento2.md#magento-upgrade-db) – Upgrades magento database + * [magento:upgrade](/docs/recipe/magento2.md#magento-upgrade) – Run upgrades if needed * [magento:maintenance:disable](/docs/recipe/magento2.md#magento-maintenance-disable) – Disables maintenance mode * [deploy:publish](/docs/recipe/common.md#deploy-publish) – Publishes the release * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploy-symlink) – Creates symlink to release @@ -101,7 +101,7 @@ The [artifact:build](#artifact:build) command of **Magento 2** consists of: * [b * [deploy:writable](/docs/recipe/deploy/writable.md#deploy-writable) – Makes writable dirs * [magento:maintenance:enable-if-needed](/docs/recipe/magento2.md#magento-maintenance-enable-if-needed) – Set maintenance mode if needed * [magento:config:import](/docs/recipe/magento2.md#magento-config-import) – Config Import -* [magento:upgrade:db](/docs/recipe/magento2.md#magento-upgrade-db) – Upgrades magento database +* [magento:upgrade](/docs/recipe/magento2.md#magento-upgrade) – Run upgrades if needed * [magento:maintenance:disable](/docs/recipe/magento2.md#magento-maintenance-disable) – Disables maintenance mode * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploy-symlink) – Creates symlink to release * [artifact:finish](/docs/recipe/magento2.md#artifact-finish) – Executes the tasks after artifact is released @@ -346,8 +346,31 @@ The value of this configuration is autogenerated on access. +### full_upgrade_needed +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L147) + + + +```php title="Default value" +//Some conditions, such as new RabittMQ services require a full upgrade and are not detecet by setup:db:status +//TODO: Add checks, once implemented, for detecting necessary full upgrade process. See future RabbitMQ Check: https://github.com/magento/magento2/pull/39698 +return false; +``` + + +### upgrade_needed +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L153) + + +:::info Autogenerated +The value of this configuration is autogenerated on access. +::: + + + + ### enable_zerodowntime -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L148) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L163) Deploy without setting maintenance mode if possible @@ -357,7 +380,7 @@ true ### artifact_file -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L337) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L361) Artifact deployment section The file the artifact is saved to @@ -368,7 +391,7 @@ The file the artifact is saved to ### artifact_dir -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L340) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L364) The directory the artifact is saved in @@ -378,7 +401,7 @@ The directory the artifact is saved in ### artifact_excludes_file -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L344) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L368) Points to a file with a list of files to exclude from packaging. The format is as with the `tar --exclude-from=[file]` option @@ -389,7 +412,7 @@ The format is as with the `tar --exclude-from=[file]` option ### build_from_repo -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L347) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L371) If set to true, the artifact is built from a clean copy of the project repository instead of the current working directory @@ -399,7 +422,7 @@ false ### repository -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L350) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L374) Overrides [repository](/docs/recipe/common.md#repository) from `recipe/common.php`. @@ -411,7 +434,7 @@ null ### artifact_path -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L353) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L377) The relative path to the artifact file. If the directory does not exist, it will be created @@ -424,7 +447,7 @@ return get('artifact_dir') . '/' . get('artifact_file'); ### bin/tar -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L361) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L385) The location of the tar command. On MacOS you should have installed gtar, as it supports the required settings :::info Autogenerated @@ -435,14 +458,14 @@ The value of this configuration is autogenerated on access. ### additional_shared_files -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L433) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L457) Array of shared files that will be added to the default shared_files without overriding ### additional_shared_dirs -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L435) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L459) Array of shared directories that will be added to the default shared_dirs without overriding @@ -452,7 +475,7 @@ Array of shared directories that will be added to the default shared_dirs withou ## Tasks ### magento\:compile {#magento-compile} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L158) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L173) Compiles magento di. @@ -465,7 +488,7 @@ e.g. ### magento\:deploy\:assets {#magento-deploy-assets} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L184) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L199) Deploys assets. @@ -492,7 +515,7 @@ in `app/etc/config.php`, e.g.: ### magento\:deploy\:assets\:adminhtml {#magento-deploy-assets-adminhtml} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L201) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L216) Deploys assets for backend only. @@ -500,7 +523,7 @@ Deploys assets for backend only. ### magento\:deploy\:assets\:frontend {#magento-deploy-assets-frontend} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L206) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L221) Deploys assets for frontend only. @@ -508,7 +531,7 @@ Deploys assets for frontend only. ### magento\:sync\:content_version {#magento-sync-content_version} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L254) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L269) Syncs content version. @@ -516,7 +539,7 @@ Syncs content version. ### magento\:maintenance\:enable {#magento-maintenance-enable} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L264) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L279) Enables maintenance mode. @@ -524,7 +547,7 @@ Enables maintenance mode. ### magento\:maintenance\:disable {#magento-maintenance-disable} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L270) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L285) Disables maintenance mode. @@ -532,7 +555,7 @@ Disables maintenance mode. ### magento\:maintenance\:enable-if-needed {#magento-maintenance-enable-if-needed} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L276) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L291) Set maintenance mode if needed. @@ -540,7 +563,7 @@ Set maintenance mode if needed. ### magento\:config\:import {#magento-config-import} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L283) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L298) Config Import. @@ -548,15 +571,23 @@ Config Import. ### magento\:upgrade\:db {#magento-upgrade-db} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L292) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L307) Upgrades magento database. +### magento\:upgrade {#magento-upgrade} +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L317) + +Run upgrades if needed. + + + + ### magento\:cache\:flush {#magento-cache-flush} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L302) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L326) Flushes Magento Cache. @@ -564,7 +595,7 @@ Flushes Magento Cache. ### deploy\:magento {#deploy-magento} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L307) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L331) Magento2 deployment operations. @@ -575,12 +606,12 @@ This task is group task which contains next tasks: * [magento:build](/docs/recipe/magento2.md#magento-build) * [magento:maintenance:enable-if-needed](/docs/recipe/magento2.md#magento-maintenance-enable-if-needed) * [magento:config:import](/docs/recipe/magento2.md#magento-config-import) -* [magento:upgrade:db](/docs/recipe/magento2.md#magento-upgrade-db) +* [magento:upgrade](/docs/recipe/magento2.md#magento-upgrade) * [magento:maintenance:disable](/docs/recipe/magento2.md#magento-maintenance-disable) ### magento\:build {#magento-build} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L316) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L340) Magento2 build operations. @@ -593,7 +624,7 @@ This task is group task which contains next tasks: ### deploy {#deploy} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L322) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L346) Deploys your project. @@ -609,7 +640,7 @@ This task is group task which contains next tasks: ### artifact\:package {#artifact-package} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L372) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L396) Packages all relevant files in an artifact. @@ -617,7 +648,7 @@ tasks section ### artifact\:upload {#artifact-upload} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L382) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L406) Uploads artifact in release folder for extraction. @@ -625,7 +656,7 @@ Uploads artifact in release folder for extraction. ### artifact\:extract {#artifact-extract} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L387) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L411) Extracts artifact in release path. @@ -633,7 +664,7 @@ Extracts artifact in release path. ### build\:remove-generated {#build-remove-generated} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L393) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L417) Clears generated files prior to building. @@ -641,7 +672,7 @@ Clears generated files prior to building. ### build\:prepare {#build-prepare} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L398) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L422) Prepare local artifact build. @@ -649,7 +680,7 @@ Prepare local artifact build. ### artifact\:build {#artifact-build} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L423) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L447) Builds an artifact. @@ -666,7 +697,7 @@ This task is group task which contains next tasks: ### deploy\:additional-shared {#deploy-additional-shared} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L439) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L463) Adds additional files and dirs to the list of shared files and dirs. @@ -674,7 +705,7 @@ Adds additional files and dirs to the list of shared files and dirs. ### magento\:set_cache_prefix {#magento-set_cache_prefix} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L454) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L478) Update cache id_prefix. @@ -688,7 +719,7 @@ after('deploy:magento', 'magento:cleanup_cache_prefix'); ### magento\:cleanup_cache_prefix {#magento-cleanup_cache_prefix} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L494) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L518) Cleanup cache id_prefix env files. @@ -696,7 +727,7 @@ After successful deployment, move the tmp_env.php file to env.php ready for next ### magento\:cron\:stop {#magento-cron-stop} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L510) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L534) Remove cron from crontab and kill running cron jobs. @@ -708,19 +739,19 @@ To use this feature, add the following to your deployer scripts: ### magento\:cron\:install {#magento-cron-install} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L526) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L550) Install cron in crontab. Install cron in crontab To use this feature, add the following to your deployer scripts: ```php - after('magento:upgrade:db', 'magento:cron:install'); + after('magento:upgrade', 'magento:cron:install'); ``` ### artifact\:prepare {#artifact-prepare} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L532) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L556) Prepares an artifact on the target server. @@ -740,7 +771,7 @@ This task is group task which contains next tasks: ### artifact\:finish {#artifact-finish} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L545) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L569) Executes the tasks after artifact is released. @@ -756,7 +787,7 @@ This task is group task which contains next tasks: ### artifact\:deploy {#artifact-deploy} -[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L554) +[Source](https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L578) Actually releases the artifact deployment. @@ -767,7 +798,7 @@ This task is group task which contains next tasks: * [artifact:prepare](/docs/recipe/magento2.md#artifact-prepare) * [magento:maintenance:enable-if-needed](/docs/recipe/magento2.md#magento-maintenance-enable-if-needed) * [magento:config:import](/docs/recipe/magento2.md#magento-config-import) -* [magento:upgrade:db](/docs/recipe/magento2.md#magento-upgrade-db) +* [magento:upgrade](/docs/recipe/magento2.md#magento-upgrade) * [magento:maintenance:disable](/docs/recipe/magento2.md#magento-maintenance-disable) * [deploy:symlink](/docs/recipe/deploy/symlink.md#deploy-symlink) * [artifact:finish](/docs/recipe/magento2.md#artifact-finish) From 09930f0ac282bb02cac838b19aab39b44939c4fb Mon Sep 17 00:00:00 2001 From: Carlos Reynosa Date: Sat, 25 Oct 2025 13:38:10 -0700 Subject: [PATCH 3/3] Cleanup code. --- recipe/magento2.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/recipe/magento2.php b/recipe/magento2.php index 4142d4200..5c593af24 100644 --- a/recipe/magento2.php +++ b/recipe/magento2.php @@ -144,17 +144,17 @@ return false; }); -set('full_upgrade_needed', function(){ +set('full_upgrade_needed', function () { //Some conditions, such as new RabittMQ services require a full upgrade and are not detecet by setup:db:status //TODO: Add checks, once implemented, for detecting necessary full upgrade process. See future RabbitMQ Check: https://github.com/magento/magento2/pull/39698 return false; }); -set('upgrade_needed', function(){ +set('upgrade_needed', function () { // Detect necessary upgrade, partial db or full upgrade - try{ + try { return get('database_upgrade_needed') || get('full_upgrade_needed'); - }catch (RunException $e){ + } catch (RunException $e) { throw $e; } }); @@ -317,8 +317,8 @@ function magentoDeployAssetsSplit(string $area) task('magento:upgrade', function () { if (get('full_upgrade_needed')) { run("{{bin/php}} {{bin/magento}} setup:upgrade --keep-generated"); - } else if(get('database_upgrade_needed')) { - invoke('magento:upgrade:db'); + } elseif (get('database_upgrade_needed')) { + invoke('magento:upgrade:db'); } })->once();