Shopware Rector Laravel Package

Product Decisions This Supports

• Shopware version support roadmap. Decides which Shopware 6.x majors/minors our extensions officially support and when we can credibly announce compatibility. Automated upgrade rules turn "we'll support the new version next quarter" into a scoped, estimable piece of work rather than an open-ended research spike. Release 0.6.0 extends rule coverage into Shopware's newer deprecation surface (CartBehavior recalculation checks), which is exactly the kind of coverage gap that previously forced manual work — evidence the tool is tracking upstream changes rather than stagnating at an older baseline.
• Build vs. buy on migration tooling. The alternative is writing our own codemods or paying engineers for manual migration passes on every Shopware release. This package is the "buy/borrow" option: MIT-licensed, Composer-installable, and maintained by the FriendsOfShopware community. Use it to set the baseline cost of a migration; if in-house rules only exist for a handful of patterns, adopting the upstream set is usually cheaper than rebuilding it.
• Support-policy and pricing packaging. If upgrades get cheaper, we can widen the supported-version matrix (e.g., support N and N-1 concurrently) or productize "migration assistance" as a paid onboarding/upgrade service for customers on legacy Shopware versions. Conversely, if automation coverage is thin, that's a signal to price migration work explicitly rather than bundling it.
• Maintenance economics for the extension portfolio. The value scales with the number of extensions/themes we maintain: one ruleset, run repeatedly across every repo, amortizes fast. This is a portfolio-level decision, not a single-repo one.
• CI and quality-gate investment. Running automated refactors in CI implies a policy decision: are upgrade fixes generated and reviewed, or hand-written? That affects review capacity, test coverage requirements, and release cadence. The addition of PHPStan to the project's own pipeline in 0.6.0 is a modest quality signal in favour of trusting its output as a reviewable diff rather than unreviewed commits.
• Toolchain baseline decisions (new in 0.6.0). The package now requires PHP 8.2 and is pinned to Rector 2.6.2 compatibility. That makes this a decision about our own minimum PHP version and Rector pinning policy across the extension portfolio, not just about Shopware versions — worth deciding deliberately rather than discovering mid-pilot.
• Tech-debt prioritization. Gives a concrete, measurable way to burn down deprecated-API usage (a recurring Shopware tax) alongside feature work, and produces diffable evidence for stakeholders that the debt is shrinking.

When to Consider This Package

Adopt (or pilot) when:

• You maintain one or more Shopware 6 plugins, themes, or apps and repeatedly absorb Shopware minor/major upgrade work.
• You need to remove deprecated APIs or adapt to Shopware architectural changes (e.g., storefront/administration changes, service decoration, DAL/entity changes, CartBehavior recalculation logic) across many files.
• Your portfolio is already on PHP 8.2+, or you are willing to raise it. 0.6.0 dropped support for older PHP; on a portfolio still shipping PHP 8.1 you will need to pin to the 0.5.x line for those repos and run two tool versions until the baseline moves.
• Your team already uses Rector (or PHPStan/PHP-CS-Fixer), can align on a pinned Rector version (2.6.2 for this release), and has a review culture that tolerates automated diffs.
• You want repeatable, version-pinned upgrade runs in CI rather than one-off manual migrations.
• You have tests good enough to validate generated changes — this is a prerequisite, not a nice-to-have.

Look elsewhere or deprioritize when:

• You're not on Shopware, or you're on Shopware 5 and migrating to 6 — that's a different, larger problem this ruleset only partially addresses.
• You need fully automatic, zero-review upgrades. Rector rules cover known patterns, not business logic; every run needs human review. 0.6.0's rules are partly authored with AI assistance (Copilot co-authorship on the CartBehavior rule) — reviewed and merged by the maintainer, but a further reason to read the diff rather than trust it.
• Upgrade work is a one-off (single small plugin, no further Shopware versions planned) — the setup and validation cost likely exceeds the savings.
• Your codebase diverges heavily from community conventions (heavy custom abstractions, nonstandard service wiring), where rule coverage will be sparse.
• You require vendor SLAs or long-term commercial support — this is a small, community-maintained project.
• You depend on the project's developer convenience tooling for contributing rules. 0.6.0 removes the devenv setup and rule scaffold script, so writing and testing a new rule upstream is slightly more work than before; budget for that if "contribute the gaps back" is part of your mitigation plan.
• Adoption signal is thin (48 stars, zero dependents at time of review). For a build-vs-buy decision, that argues for a time-boxed pilot, not a mandate. Mitigate by pinning the version, forking if abandoned, and keeping a manual migration checklist as the fallback. Active releases (0.5.x → 0.6.0) are a positive maintenance signal but do not change the concentration risk of a single primary maintainer.

How to Pitch It (Stakeholders)

To executives (one paragraph): Every Shopware release creates mandatory rework across our extension portfolio, and that rework is currently paid in senior engineer hours each cycle. frosh/shopware-rector is a free, MIT-licensed tool that automates the mechanical part of those upgrades, so we can support new Shopware versions faster and at lower cost — and optionally sell migration help to customers stuck on older versions. The project is actively maintained and its latest release adds coverage for newer Shopware deprecations, which is the direction we want. It is a low-cost accelerator, not a critical-path dependency: it is community-maintained and small, so we should pilot it on one extension, measure hours saved, and keep a manual fallback.

To engineering: Composer dev-dependency, no runtime footprint, no production risk. It's a Rector ruleset — you run it, get a deterministic diff, review it, and commit. Two things changed in 0.6.0 that touch us: it now requires PHP 8.2 and restores/targets Rector 2.6.2 compatibility, so pin both the package and Rector per repo and expect to run 0.5.x on any repo still on PHP 8.1. Also new: a rule for deprecated CartBehavior recalculation checks. Fit it into the existing CI/release flow and gate it behind tests. Expect it to handle the common deprecated-API patterns and to miss the long tail; budget review time accordingly. Good first target: the extension with the biggest delta to the newest Shopware version.

The ask: A one-sprint pilot — pick one representative extension on PHP 8.2, pin the tool and Rector version, run the ruleset against the next Shopware target, and report (a) percentage of upgrade changes automated, (b) engineer hours saved vs. the prior manual upgrade, (c) rule gaps worth contributing upstream. Decision at the end: adopt across the portfolio, contribute rules and fork-maintain, or revert to manual migrations.

Risk to state plainly: small contributor base and low visible adoption mean abandonment is a real scenario, and the PHP 8.2 / Rector 2.6.2 coupling means an upstream version bump can force a toolchain change on us. Mitigations are cheap — version pinning per repo, a fork we control, and a written manual fallback procedure — so the downside is bounded to the pilot cost.