Rector Downgrade Php Laravel Package

Technical Evaluation

Architecture fit rector/rector-downgrade-php is build-time tooling, not a runtime dependency. It supplies Rector rule sets that rewrite code using newer PHP syntax and APIs (match, enums, readonly, nullsafe, named arguments, first-class callables, str_contains-style functions) into equivalent code targeting an older PHP floor. In a Laravel/PHP product this maps to one narrow scenario: we develop and test on a modern interpreter but must ship code that executes on an older one — most commonly a distributed CLI/phar, a Composer package consumed by downstream apps on mixed PHP versions, or a plugin targeting a legacy host. For a standard Laravel application deployed on a single, controlled PHP version, this package has effectively no role; a version-floor check in composer.json and CI is the correct, cheaper control.

Integration feasibility Feasible and low-ceremony if Rector is already in the toolchain. Integration is a config file plus a CI step:

• Add rector/rector and this package to require-dev.
• Register version-scoped downgrade sets (e.g. DowngradePhp80, DowngradePhp74) in a dedicated rector-downgrade.php config.
• Run against a separate staging/build directory (or with path exclusions) so the downgraded output never overwrites the authored source — the standard pattern is: source at PHP 8.3 → downgrade → build artifact → verify artifact on the floor version.
• If shipping a phar or a package that must not leak its own dependencies, pair with php-scoper and validate the scoped output after downgrading, since scoping rewrites and downgrading rewrites interact.

If Rector is not already adopted, this becomes the entry point to a full AST-refactoring toolchain — a much larger decision than this package implies.

Technical risk The dominant risk is silent semantic drift, not breakage. Syntax downgrades are largely faithful; API and idiom downgrades are approximations. Concrete exposures:

• str_contains/array_is_list-style polyfills alter edge-case behavior (type juggling, empty-needle handling).
• Nullsafe and match rewrites can change evaluation order or short-circuit behavior.
• Named arguments and first-class callables downgrade to positional/closure forms that do not preserve reflection-visible signatures.
• readonly and enum downgrades lose invariants the runtime enforced.
• Attributes are stripped or converted to docblocks, silently disabling downstream metadata consumers.

Second risk: coverage confidence. With 44 stars and zero dependents, there is no observable population of users exercising edge cases. RectorPHP org backing gives it credibility and a maintenance path (it is reportedly used to produce Rector's own downgraded distribution), but the blast radius of a missed rule is a fatal error on the oldest supported PHP — discovered by end users, not by us.

Key questions

1. What is the exact PHP floor we must support, and is it contractual (customer environments, host CMS, marketplace rules) or assumed?
2. Are we shipping downgraded code to third parties, or only running the test suite against older interpreters? Only the former justifies this package.
3. Is Rector already approved in our stack, and who owns its version pin?
4. Do any consumers of the output rely on reflection, attributes, or exact method signatures — i.e., where is lossy downgrade unacceptable?
5. What is the verification story: a CI matrix executing the downgraded artifact on the floor version, not just rector --dry-run?
6. Is the package's maintenance cadence tracking new PHP releases, and what is our exit if it stalls?

Integration Approach

Stack fit Best fit: an internal Composer package or artisan-distributed CLI shared across applications with heterogeneous PHP versions; a WordPress/legacy-host plugin; a phar-distributed developer tool. Poor fit: a first-party Laravel app on a pinned runtime, where composer.json platform constraints plus a CI matrix solve the problem with zero new tooling.

Migration path Greenfield adoption, not a migration. Treat the downgraded artifact as a derived build output: authored source stays modern, the downgrade step is a build stage, and nothing downstream ever edits the generated tree. Encode this as composer build:downgrade so it is reproducible and never run manually.

Compatibility Pin the package in lockstep with rector/rector — rule sets are coupled to Rector's core and to nikic/php-parser syntax support. Expect a required bump on each Rector major release. Verify the package supports our authored PHP version (the newest syntax we actually use) as well as our floor; new-syntax support often lands after a PHP GA.

Sequencing

1. Spike (1 week): run the downgrade sets against one representative package; execute the output on the floor version in Docker; diff behavior.
2. Establish the harness: CI matrix running the downgraded artifact plus a golden-file diff so rule regressions are visible in review.
3. Pilot one package in production distribution; instrument install/activation failures.
4. Codify: config ownership, version pin policy, upgrade checklist tied to Rector releases.
5. Expand only after two clean release cycles.

Do not attempt org-wide rollout before the floor-version execution matrix exists — a passing downgrade run is not evidence of a working artifact.

Operational Impact

Maintenance Low ongoing effort but non-zero: version pins, periodic re-runs as authored code adopts new syntax, and review of generated diffs. The real cost is the rule gap: every new PHP feature we use requires a corresponding rule to exist before we can adopt it in downgraded code paths. Budget a few hours per PHP minor release and a defined owner.

Support Community-only. Issues route to the RectorPHP org repository; no SLA, no vendor. Internal support burden depends entirely on our own floor-version test matrix — this package cannot be our safety net, our tests must be.

Scaling Technically trivial — per-file AST transforms, runs in seconds to low minutes, parallelizable, cacheable in CI. Organizational scaling is the constraint: every team whose code feeds the downgraded artifact must understand the constraints (no reflection-dependent behavior, no attribute-driven metadata on the floor version). That is a documentation and code-review problem, not an infrastructure one.

Failure modes

• Silent semantic change — output passes syntax checks, behaves differently. Mitigation: floor-version execution tests, not just --dry-run.
• Incomplete downgrade — unhandled construct emits output that fatals on the floor PHP. Mitigation: CI matrix running the artifact; fail the build.
• Rule/config drift — a Rector bump changes output without a visible code change. Mitigation: commit generated output or golden-file diffs to review.
• Scoping interaction — php-scoper and downgrade rewriting collide on the same tree. Mitigation: fixed pipeline order, integration test on the final artifact.
• Abandonment — 44 stars and 0 dependents means low external pressure for the maintainers to keep pace. Mitigation: internal fork readiness, and a documented fallback of pinning our authored PHP version if the tool lags.
• Overwrite of source — misconfigured paths downgrade the working tree. Mitigation: mandatory output directory, CI guard.

Ramp-up One engineer, roughly 1–2 days to become productive: Rector config semantics, the version-set mapping, and the build-artifact discipline. Team-wide awareness is the larger lift — a short design note stating "we author on PHP 8.3, we ship to 7.4, therefore these constructs are off-limits" prevents most incidents.

TPM recommendation: narrow, justified only by a concrete legacy-floor obligation and preferably only where Rector is already present. The opportunity score signals real latent utility for package/tool maintainers; the 1.16 overall score and zero dependents signal that this is not a foundation to build broadly on. Approve as a scoped build-stage utility with a floor-version execution matrix as a hard prerequisite; reject as a general-purpose compatibility strategy for the application portfolio.