Automatic refactoring
Shopware CLI includes a built-in automatic refactoring tool with pre-configured rules for Shopware projects. Instead of manually configuring and managing multiple linters and fixers, this tool automatically handles breaking changes and code modernization when you upgrade Shopware versions.
Use this tool to:
- Automatically fix breaking changes between Shopware versions
- Apply Shopware-idiomatic code fixes
- Modernize your codebase without manual linter configuration
The tool uses:
The refactoring command runs PHP and Node.js tooling under the hood. The Docker examples are recommended because the image already contains the required runtime dependencies. If PHP and Node.js are available locally, you can run the shopware-cli commands directly instead.
Refactoring an extension
WARNING
Before you start, make sure you work on a copy or Git-versioned branch, because this command will modify your files in place!
Refactoring an entire project
You can also refactor a full Shopware project instead of a single extension.
The CLI runs Rector and ESLint automatically. After completion, review all changes and commit or revert them as needed.
Make sure the shopware/core requirement in your composer.json file reflects the version you're targeting. Shopware CLI determines which upgrade rules to apply based on that version constraint.
Project fix options
Run only specific tools:
shopware-cli project fix /path/to/your/project --only phpstan
shopware-cli project fix /path/to/your/project --only "phpstan,eslint"Allow running on non-Git repositories:
shopware-cli project fix /path/to/your/project --allow-non-gitBy default, project fix requires a Git repository to safely track changes.
Administration migration rules
The fixer also includes deterministic rules for known Administration migration patterns, including Administration Twig component migrations and component property or event changes. These rules apply when running project fix or extension fix as described above.
The rules only cover cases where the old pattern and its replacement can be identified without ambiguity. They are not a general-purpose Administration migration engine and do not guarantee full compatibility with a target Shopware version. Manual review is still required for changes that are not covered by a deterministic rule.
For manual migration guidance, see the Administration migration guide.
After running refactoring
Use Git or your diff tool to review the changes.
Test your extension or project thoroughly.
Commit the accepted changes and discard any unwanted ones.
You can combine automatic refactoring with other Shopware CLI commands (e.g., project build or extension validate) as part of your upgrade workflow.
