diff --git a/.wordlist.txt b/.wordlist.txt index 15ed82fc1b..71a806a294 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1826,6 +1826,7 @@ precompile preconfigured prefetch prefixer +preflight preload preloaded preloading diff --git a/assets/project-upgrade-report.png b/assets/project-upgrade-report.png new file mode 100644 index 0000000000..24513c1116 Binary files /dev/null and b/assets/project-upgrade-report.png differ diff --git a/guides/hosting/installation-updates/performing-updates.md b/guides/hosting/installation-updates/performing-updates.md index ec76e2ca13..10aa9061a7 100644 --- a/guides/hosting/installation-updates/performing-updates.md +++ b/guides/hosting/installation-updates/performing-updates.md @@ -2,7 +2,6 @@ nav: title: Performing Shopware Updates position: 20 - --- # Performing Shopware Updates @@ -22,17 +21,28 @@ There are two Shopware update types: ## Preparations -### Check extension compatibility +### Check project and extension compatibility + +The recommended preflight is the Shopware CLI upgrade wizard in dry-run mode. It checks project readiness, Composer-managed extension compatibility, and whether Composer can resolve the selected target version without modifying project files: + +```bash +shopware-cli project upgrade \ + --no-interaction \ + --target latest-patch \ + --dry-run +``` + +If you're following older guides that mention `shopware-cli project upgrade-check`, use the dry-run command above instead. -Before any update, check if the installed extensions are compatible with the new version. Run the upgrade check command to analyze your project for compatibility issues: +For an interactive target picker and guided workflow, run: ```bash -shopware-cli project upgrade-check +shopware-cli project upgrade ``` -This command checks your installed extensions against the target Shopware version. If an extension is not compatible, check with the extension developer if an update is available. If you don't have the Shopware CLI installed, see the [installation guide](../../../products/tools/cli/index.md). +See [Upgrade a Shopware Project](../../../products/tools/cli/project-commands/upgrade.md) for the full workflow. If you don't have Shopware CLI installed, see the [installation guide](../../../products/tools/cli/index.md). -Managing all extensions through Composer is the best way to ensure compatibility. It simplifies the update process as Composer automatically resolves the correct versions of the extensions. +Managing extensions through Composer is required by the upgrade wizard and gives Composer the information it needs to resolve extension versions together with Shopware. If the readiness check finds locally managed plugins, the CLI points you to `shopware-cli project autofix composer-plugins` where migration is possible. ### Create backups @@ -44,29 +54,49 @@ If blue-green deployment is enabled, you can rollback to the previous version wi ### Enable maintenance mode -Before you start the update process, set the Sales Channels into maintenance mode. This can be done using the Administration or with the terminal: +Before you update a running production environment, set the Sales Channels into maintenance mode. This can be done using the Administration or with the terminal: ```bash bin/console sales-channel:maintenance:enable --all ``` +Do not enable maintenance mode merely to prepare and test the upgrade locally. Apply it according to your deployment procedure when the upgraded code is ready to move to the running environment. + ### Additional steps for major updates For major updates, consider the following additional preparations: - **Update PHP version**: Update the PHP version to the minimum required version for the new Shopware version *before* updating Shopware. Shopware versions always support an overlapping PHP version, so this is safe to do beforehand. You can find the minimum required PHP version in the [System Requirements guide](../../installation/system-requirements.md). - **Check upgrade changes**: Review the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown) for all breaking changes and migration instructions. -- **Update extensions first**: Update all extensions to their latest versions before updating Shopware to ensure a smooth transition. After updating Shopware, update all extensions again to get versions compatible with the new Shopware version. +- **Review extension updates**: Use the upgrade wizard's extension queue and report to identify compatible releases, updates, blockers, and items that still need manual or vendor review. + +## Prepare the update locally with Shopware CLI (recommended) + +The recommended workflow is to apply the upgrade to your local project first: + +```bash +shopware-cli project upgrade +``` + +The wizard performs read-only readiness and compatibility checks first, lets you review the planned project changes, then runs the Composer update, refreshes Symfony Flex recipes, runs Shopware Deployment Helper, and writes `.shopware-cli/upgrade/report.md`. + +If an essential execution step fails or the run is canceled, Shopware CLI restores `composer.json` and `composer.lock` and writes a failure report. Always start from a clean Git state, so you can review or restore any other changed files as well. + +After a successful local run: -## Performing the update via CLI (recommended) +1. Review `.shopware-cli/upgrade/report.md` and the Git diff. +2. Test the Administration, Storefront, integrations, and installed extensions. +3. Run your automated test suite. +4. Commit `composer.json`, `composer.lock`, and any reviewed configuration changes. +5. Deploy through your normal process. -The recommended way to update Shopware is via the command line. The update process consists of two phases: preparing the update locally and deploying it to the server. +The upgrade wizard does not deploy the project to production. -### Local development environment +## Manual local preparation -Perform the following steps in your local development environment: +If you cannot use the Shopware CLI upgrade wizard, prepare the Composer changes manually. -#### 1. Update the Shopware version constraint +### 1. Update the Shopware version constraint Edit your `composer.json` and update the `shopware/core` version constraint to the target version: @@ -78,7 +108,7 @@ Edit your `composer.json` and update the `shopware/core` version constraint to t } ``` -#### 2. Run Composer update +### 2. Run Composer update Run the update command with `--no-scripts` to prevent the automatic execution of scripts during the update: @@ -86,7 +116,7 @@ Run the update command with `--no-scripts` to prevent the automatic execution of composer update --no-scripts ``` -#### 3. Update Symfony Flex recipes +### 3. Update Symfony Flex recipes Update the Symfony Flex recipes to apply any configuration changes: @@ -94,9 +124,9 @@ Update the Symfony Flex recipes to apply any configuration changes: composer recipes:update ``` -This command shows available recipe updates and allows you to apply them interactively. Review the changes carefully before applying them. +Review the changes carefully before applying them. -#### 4. Commit and deploy +### 4. Commit and deploy Commit the changes to your Git repository: @@ -107,17 +137,17 @@ git commit -m "Update Shopware to 6.7.0" Review any other changed files (e.g., from recipe updates) and commit them as well. Then deploy the changes to your server using your deployment process. -### Production server +## Production server -After deploying the updated code to your server, run the following commands: +After deploying the updated code to your server, run the following commands according to your deployment process. -#### 1. Enable maintenance mode +### 1. Enable maintenance mode ```bash bin/console sales-channel:maintenance:enable --all ``` -#### 2. Prepare the update +### 2. Prepare the update ```bash bin/console system:update:prepare @@ -125,7 +155,7 @@ bin/console system:update:prepare This command triggers events that allow extensions to prepare for the update. -#### 3. Finish the update +### 3. Finish the update Run the Shopware update scripts to execute database migrations and other necessary update tasks: @@ -133,7 +163,7 @@ Run the Shopware update scripts to execute database migrations and other necessa bin/console system:update:finish ``` -#### 4. Disable maintenance mode +### 4. Disable maintenance mode ```bash bin/console sales-channel:maintenance:disable --all @@ -148,14 +178,14 @@ Only run these commands on the production server after the updated code has been Shopware also provides a web-based updater in the Administration panel. This method handles the entire update process through the browser. :::warning -The web updater is only recommended for small instances. Since the update runs in the browser, you may encounter timeout problems, memory limits, or other resource issues on larger shops. For production environments, use the CLI method described above. +The web updater is only recommended for small instances. Since the update runs in the browser, you may encounter timeout problems, memory limits, or other resource issues on larger shops. For production environments, use the local preparation and deployment workflow described above. ::: To use the web updater: -1. Log in to the Administration -2. Navigate to **Settings** > **System** > **Shopware Update** -3. Follow the on-screen instructions to complete the update +1. Log in to the Administration. +2. Navigate to **Settings** > **System** > **Shopware Update**. +3. Follow the on-screen instructions to complete the update. The web updater will automatically enable maintenance mode, download the update, run migrations, and disable maintenance mode when complete. @@ -163,16 +193,18 @@ The web updater will automatically enable maintenance mode, download the update, Before you remove the maintenance mode, verify the update was successful: -- **Check the Administration**: Make sure the administration is working correctly. +- **Check the Administration**: Make sure the Administration is working correctly. - **Check the Storefront**: Make sure your main processes are working correctly (e.g., adding products to the cart, checkout, etc.). - **Check the Extensions**: Make sure that all extensions are working correctly. -- **Check the Performance**: Make sure that there is no major performance degradation. +- **Check the Performance**: Make sure there is no major performance degradation. - **Check the Logs**: Check your error logs for any issues. +- **Review the upgrade report**: If you used Shopware CLI, keep the report with the upgrade context or attach a redacted copy when asking another developer, extension vendor, hosting provider, or Shopware support for help. ## Tools for extension developers If you maintain custom extensions, these tools can help with upgrades: +- **[Shopware CLI upgrade wizard](../../../products/tools/cli/project-commands/upgrade.md)**: Check a Composer-managed extension set against a target Shopware version and produce a shareable compatibility/Composer report from a representative test project. - **[Rector for Shopware](https://github.com/FriendsOfShopware/shopware-rector)**: Automatically upgrades PHP code for Shopware compatibility. - **[Codemods](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/code-mods.js)**: Helps upgrade Administration JavaScript code. - **[Twig Block Versioning](https://www.shopware.com/en/news/twig-block-versioning-in-shopware-phpstorm-plugin/)**: A [PHPStorm Plugin](https://plugins.jetbrains.com/plugin/17632-shopware-6-toolbox) feature that tracks which Twig blocks you've overwritten and alerts you when they may need updates. diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md index d9f2d12276..3deec6e3dd 100644 --- a/guides/upgrades-migrations/index.md +++ b/guides/upgrades-migrations/index.md @@ -8,6 +8,10 @@ nav: This section covers version-based upgrades and the required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements. +:::info +For a guided local upgrade, use [`shopware-cli project upgrade`](../../products/tools/cli/project-commands/upgrade.md). It checks project readiness and Composer-managed extensions, verifies the selected target with Composer before modifying project files, runs the upgrade locally, and writes a shareable report. +::: + ## Scope of this section Upgrades typically fall into one of these categories: @@ -27,13 +31,13 @@ Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce break When targeting a new Shopware version: -1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files -2. Check breaking changes per layer (Core / Admin / Storefront / API) -3. Validate extension compatibility -4. Apply required migrations -5. Rebuild Admin/Storefront assets if needed -6. Test critical flows -7. Update extension versions if required +1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files. +2. Check breaking changes per layer (Core / Admin / Storefront / API). +3. Run the [Shopware CLI upgrade preflight](../../products/tools/cli/project-commands/upgrade.md#run-a-non-interactive-preflight) or otherwise validate extension compatibility and Composer resolution. +4. Apply required migrations and project changes. +5. Rebuild Admin/Storefront assets if needed. +6. Test critical flows and extension behavior. +7. Commit the reviewed project changes and deploy through your normal process. :::info Upgrade impact in real projects Upgrade complexity depends on the installation: @@ -47,7 +51,7 @@ A consistent architecture, centralized CI, and controlled extension strategy hel ### Custom projects -* Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. +* Follow the [Performing updates guide](../hosting/installation-updates/performing-updates.md) to stage, test, and execute upgrades in order. * Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. * Use feature toggles to decouple risky changes from the deployment. @@ -55,11 +59,13 @@ A consistent architecture, centralized CI, and controlled extension strategy hel To reduce long-term upgrade cost: -* Avoid internal APIs and undocumented features -* Keep dependencies aligned with Shopware core -* Maintain automated test coverage -* Keep database migrations idempotent -* Track deprecations continuously—do not batch them +* Avoid internal APIs and undocumented features. +* Keep dependencies aligned with the Shopware core. +* Maintain automated test coverage. +* Keep database migrations idempotent. +* Track deprecations continuously—do not batch them. + +The Shopware CLI upgrade wizard can also be useful when you maintain extensions: assemble the extensions in a representative Composer-managed test project, select the target Shopware version, and use the extension queue and generated report to identify updates, blockers, and items that need manual review. This does not replace testing the extension itself against the target Shopware version. ### Custom plugins @@ -81,6 +87,8 @@ To reduce long-term upgrade cost: ## Next steps -For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md). +For the guided local workflow, continue with [Upgrade a Shopware Project](../../products/tools/cli/project-commands/upgrade.md). + +For the wider operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md) and [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md). For general development best practices that reduce upgrade friction, see the [Development guide](../development/index.md). diff --git a/guides/upgrades-migrations/upgrade-shopware.md b/guides/upgrades-migrations/upgrade-shopware.md index 2ac9778005..6513f0c05a 100644 --- a/guides/upgrades-migrations/upgrade-shopware.md +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -6,20 +6,45 @@ nav: # Upgrade Shopware -This guide explains how to update an existing Shopware installation using Composer. +This guide explains how to update an existing Shopware installation. For local project preparation, the recommended workflow is the [Shopware CLI upgrade wizard](../../products/tools/cli/project-commands/upgrade.md), which combines readiness checks, extension compatibility analysis, Composer resolution, the local upgrade, and a shareable report. For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-migrations/index.md) guide before performing updates. -## Standard update process +## Recommended: prepare the upgrade with Shopware CLI -Shopware updates can be executed via Composer or with the web-based updater in the Administration panel. +From a clean Git working tree in your local Shopware project, run: -### 1. Enable maintenance mode +```bash +shopware-cli project upgrade +``` + +The wizard checks project readiness, lets you choose the target Shopware version, checks Composer-managed extensions, and verifies the target dependency set with Composer before changing project files. You review the plan before the CLI applies the upgrade locally. + +After the local upgrade succeeds, test the shop and extensions, review the generated report and changed files, commit the project changes, and deploy them through your normal process. The wizard does not deploy to production for you. + +For CI or a read-only preflight, use the non-interactive mode with `--dry-run`: + +```bash +shopware-cli project upgrade \ + --no-interaction \ + --target latest-patch \ + --dry-run +``` + +See [Upgrade a Shopware Project](../../products/tools/cli/project-commands/upgrade.md) for prerequisites, extension handling, rollback behavior, reports, and all command options. + +## Manual Composer update + +If you cannot use the Shopware CLI upgrade wizard, you can prepare the project manually with Composer. + +### 1. Enable maintenance mode when updating a running environment ```bash bin/console sales-channel:maintenance:enable --all ``` +For the recommended local-first workflow, enable maintenance mode as part of your normal deployment procedure rather than while preparing the project locally. + ### 2. Update Composer dependencies Before running the update, adjust the required Shopware version in `composer.json` to the version to be installed. When using the Commercial plugin, update the `shopware/commercial` requirement to a compatible version as well. @@ -52,7 +77,7 @@ Complete the update by running: bin/console system:update:finish ``` -This command applies all required update routines for the newly installed Shopware version, including running database migrations, and recompiling themes with the latest code. +This command applies all required update routines for the newly installed Shopware version, including running database migrations and recompiling themes with the latest code. After the update process has finished successfully, disable maintenance mode separately: @@ -62,17 +87,22 @@ bin/console sales-channel:maintenance:disable --all ## Operational best practices -* Automate pre-upgrade checks (PHP/DB versions, extensions, disk space). -* Always test upgrades on staging with production-like data. -* Keep verified database backups and a recovery plan. -* Review changelogs and UPGRADE files before applying changes. -* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work. -* Avoid skipping major versions. -* Commit the `composer.lock` file. -* Run post-upgrade smoke tests. +* Start from a clean Git working tree and a recoverable database backup. +* Test upgrades locally or on staging with production-like data before production rollout. +* Review release notes, changelogs, and UPGRADE files for the target version. +* Check extension compatibility and investigate items that need vendor or manual review. +* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work. +* Avoid skipping major versions unless you have explicitly tested the full upgrade path. +* Commit `composer.json`, `composer.lock`, and review recipe/configuration changes. +* Run post-upgrade smoke tests and your automated test suite. ## After the update -* Clear caches if necessary -* Rebuild Administration and Storefront assets if required -* Test critical business flows (checkout, login, API integrations) +* Review the Shopware CLI upgrade report when you used the wizard. +* Clear caches if necessary. +* Rebuild Administration and Storefront assets if required. +* Test critical business flows such as checkout, login, and API integrations. +* Test installed extensions and custom project code. +* Review logs for new errors or deprecations. + +For production-oriented preparation, maintenance mode, deployment, and verification guidance, see [Performing Shopware Updates](../hosting/installation-updates/performing-updates.md). diff --git a/products/tools/cli/project-commands/upgrade.md b/products/tools/cli/project-commands/upgrade.md new file mode 100644 index 0000000000..f2348d82c8 --- /dev/null +++ b/products/tools/cli/project-commands/upgrade.md @@ -0,0 +1,155 @@ +--- +nav: + title: Upgrade a Shopware Project + position: 8 +--- + +# Upgrade a Shopware Project + +`shopware-cli project upgrade` guides a Shopware project through a local-first upgrade. It checks whether the project is ready, analyzes Composer-managed extensions, verifies the target dependency set with Composer, lets you review the plan before files change, runs the upgrade locally, and writes a shareable report. + +::: info +The upgrade wizard prepares and applies the upgrade to your local project. It does not deploy the upgraded project to production. Test the result, commit the changed files, and deploy through your normal process. +::: + +## Before you start + +Run the upgrade on a Git branch or a disposable copy of the project. The wizard checks these prerequisites before continuing: + +- `composer.lock` exists and contains the installed `shopware/core` version. +- The Git working tree is clean. If the directory is not a Git repository, the wizard warns instead of blocking. Use `--disable-git` to skip Git-related checks. +- All discovered extensions are managed through Composer. +- PHP and Composer are available through the project's configured environment. +- The Deployment Helper workflow is available. If `shopware/deployment-helper` is not required yet, the wizard can add it during the upgrade. + +For Docker and other configured environments, PHP and Composer are checked through the project executor rather than only on the host machine. + +### Migrate local extensions to Composer first + +The wizard resolves and pins extension versions with Composer. Extensions living outside `vendor/`, for example in `custom/plugins`, cannot participate in that resolution and therefore block the upgrade readiness check. + +Migrate eligible locally managed extensions with: + +```bash +shopware-cli project autofix composer-plugins +``` + +See [Migrate custom/plugins extensions to Composer](./autofix.md#migrate-customplugins-extensions-to-composer) for details. + +## Run the interactive upgrade + +From the Shopware project, run: + +```bash +shopware-cli project upgrade +``` + +The terminal wizard follows six phases: + +1. Check project readiness. +2. Choose a target Shopware version. +3. Analyze extension compatibility and run a Composer resolution check. +4. Review the planned project changes. +5. Apply the upgrade locally with live progress and logs. +6. Review the generated upgrade report and next steps. + +The readiness and preparation phases are read-only. Project files are not changed until you review the plan and start the upgrade. + +## Choose and verify the target version + +The version picker offers a recommended release, the latest patch in the current release line when available, and a searchable list of other supported versions. + +After you choose a target, the wizard combines two kinds of compatibility information: + +- Extension and repository metadata provide an early compatibility signal. +- A Composer dry run verifies whether the target dependency set can actually be resolved for this project. + +Composer resolution is the final gate for the dependency set. Repository or Store metadata can be missing or incomplete; when Composer successfully resolves a previously uncertain extension, the wizard reflects the resolved result instead of keeping a stale compatibility blocker. + +The extension queue distinguishes extensions that are ready, need an update, need manual review, or block the selected upgrade. Where available, extension details and the generated report link to the Shopware Store listing and include release changelogs for updates. + +If Composer cannot resolve the target dependency set, the wizard stops before modifying the project and includes the Composer conflict output in the report. + +## Review what will change + +Before execution, the wizard shows the planned project changes and a summary of the extension results. Starting the upgrade then performs the local workflow: + +1. Back up `composer.json` and `composer.lock`. +2. Rewrite the Shopware and resolved extension requirements in `composer.json`. +3. Run `composer update --with-all-dependencies`. +4. Refresh Symfony Flex recipes with `composer symfony:recipes:install --force --reset`. +5. Run `vendor/bin/shopware-deployment-helper run`. +6. Write the upgrade report. + +The Flex recipe refresh is best-effort: a recipe-refresh failure is reported as a warning, while failures in essential upgrade steps stop the run. + +If an essential step fails or you cancel the running upgrade, Shopware CLI restores `composer.json` and `composer.lock` and writes a failure report. Other files changed by tools during the workflow are not covered by that Composer-file rollback, which is another reason to start from a clean Git state. + +## Run a non-interactive preflight + +The same workflow can run without the interactive TUI. This is useful for CI, scripts, and agent-assisted workflows. + +To inspect a target without modifying the project: + +```bash +shopware-cli project upgrade \ + --no-interaction \ + --target latest-patch \ + --dry-run +``` + +In non-interactive mode, `--target` is required. It accepts: + +- an exact supported Shopware version, for example `6.7.13.0`; +- `recommended`; +- `latest-patch`. + +With `--dry-run`, Shopware CLI performs the readiness checks, extension analysis, and Composer resolution, prints the planned changes, writes a report, and stops before changing project files. + +Remove `--dry-run` to execute the upgrade non-interactively after a successful preflight. + +### Security advisory blocking + +Composer may refuse a dependency set because packages are affected by known security advisories. The `--no-audit` option allows the upgrade to continue by disabling that Composer audit block for the workflow. + +::: warning +Use `--no-audit` only when you understand and have accepted the reported security risk. Prefer a target and dependency set without known security advisories whenever possible. +::: + +## Read and share the upgrade report + +The wizard writes a Markdown report to: + +```text +.shopware-cli/upgrade/report.md +``` + +The report includes: + +- source and target Shopware versions; +- readiness and PHP requirement information; +- planned Composer changes; +- extension results grouped as blocked, needs review, needs update, or OK; +- extension update changelogs where available; +- the package changes predicted by Composer resolution; +- raw Composer conflict output when dependency resolution fails. + +The final wizard screen links to the report and execution log and summarizes the local-first outcome and next steps: + +![Shopware CLI project upgrade report and next steps](../../../../assets/project-upgrade-report.png) + +The upgrade also writes its execution log below `.shopware-cli/upgrade/`. The report and log can be shared with a colleague, agency, extension vendor, hosting provider, Shopware support, or a coding agent when investigating an upgrade problem. + +## What the wizard does not guarantee + +The wizard makes upgrade risk visible earlier, but a successful run is not a guarantee that every application behavior remains compatible. It does not: + +- rewrite incompatible custom extension code; +- create a missing compatible release from an extension vendor; +- remove hosting or infrastructure constraints; +- replace application, Storefront, Administration, integration, or business-flow testing; +- deploy the upgraded project to production. + +After a successful run, review the report and changed files, test the shop and extensions locally, run your automated test suite, commit the resulting project changes, and deploy through your normal process. + +For the wider operational upgrade procedure, see [Upgrade Shopware](../../../../guides/upgrades-migrations/upgrade-shopware.md) and [Performing Shopware Updates](../../../../guides/hosting/installation-updates/performing-updates.md).