PHP Upgrade Preflight
Public beta Latest release v0.3.3 · schema 0.8 PHP ^8.0 v0.3.3 packages · MIT

PHP Upgrade Preflight

Plan your upgrade — with evidence.

A deterministic, read-only preflight analyzer for Composer-based PHP and Laravel upgrades. It runs real Composer scenarios in disposable workspaces and reports blockers, package changes, staged upgrade paths, source impact, risk, effort, and uncertainty — every finding linked to evidence. During analysis, the target project is immutable input; installing the tool is a separate Composer operation in whichever tools directory or application you choose below.

Run your first preflight View on GitHub

Safest first install: use a separate tools directory. These commands change only that new directory, not the application you later analyze. The latest published v0.3.3 packages are MIT licensed. Releases up to and including v0.3.1 remain under PolyForm Noncommercial 1.0.0. 

$ mkdir php-upgrade-tools
$ cd php-upgrade-tools
$ composer require php-upgrade-preflight/cli:^0.3 php-upgrade-preflight/laravel:^0.3
Alternative: install as application development dependencies

This intentionally changes that application's composer.json, lock file, and development dependencies. It is not part of the analyzer's read-only execution guarantee.

composer require --dev php-upgrade-preflight/cli:^0.3 php-upgrade-preflight/laravel:^0.3

Run your first preflight

Start interactively with the wizard; keep explicit options for repeatable scripts and CI.

Before you run it

  • The analyzer host needs PHP 8.0 or newer and Composer 2.
  • The target path must contain a valid composer.json; a lock file provides stronger evidence.
  • Create the report directory outside the target project. Its parent directory must already exist.
  • Install the CLI and Laravel adapter in the separate tools directory shown above.
Check prerequisites Installation details

Start with the interactive wizard

Run this from the external tools directory in a terminal. The wizard detects the Composer project, collects PHP and package targets, requires an explicit Composer execution policy, and reviews the plan before analysis:

vendor/bin/upgrade-intel wizard

The wizard is for local, terminal-attached runs. It prints the equivalent shell-copyable upgrade-intel analyze command before analysis. A valid report may still describe a blocked or unknown upgrade; review its blockers, evidence, and uncertainties before deciding what to change.

Scripts and CI: explicit, non-interactive command

Use analyze with explicit options; it never prompts:

vendor/bin/upgrade-intel analyze \
  --path=/work/legacy-app \
  --from-php=7.4 \
  --target-php=8.2 \
  --format=json \
  --output=/work/upgrade-reports/php-82.json

Automation should treat a produced report separately from upgrade feasibility and read resolution.status.

Guided wizard details CI-ready commands Troubleshooting Read the report

What you get

Decision-support evidence for the upgrade you haven't started yet.

Read-only, provably

The analyzed project is immutable input. Composer runs only in disposable workspaces with scripts and plugins disabled, and recursive digests prove the target stayed byte-for-byte unchanged.

Real Composer resolutions

No solver guesswork: the analyzer runs actual Composer scenarios and preserves each exact command, version, duration, exit status, output excerpt, and candidate-lock fingerprint.

Staged Laravel 7 → 13

Sequential analysis across adjacent Laravel hops, each with its own Composer evidence. Only the selected candidate state feeds the next stage; the direct final-target result stays independent.

Canonical JSON + Markdown

JSON (schema 0.8) is the canonical report; Markdown is a faithful projection of the same data with no independent analysis logic. Automation reads statuses from the report, not exit codes.

Risk, effort, uncertainty

Risk drivers, effort as ranges with assumptions and confidence — never precise promises. Missing or weak evidence is reported as explicit uncertainty, and every finding links evidence IDs.

Secret redaction

Composer output passes through a deterministic secret boundary: credential-bearing URLs, tokens, and auth values become stable redaction markers, and local paths become portable placeholders.

How it works

One deterministic pipeline from project state to evidence-linked report.

Project statecomposer.json + lock Composer scenariosisolated workspaces Lock diffroot + transitive Blockerspaths + options Source scannikic/php-parser Framework rulesLaravel adapter ReportJSON + Markdown

The core is framework-neutral; Laravel is the first adapter, and third-party adapters register through Composer metadata. Composer remains the dependency solver — the analyzer explains its results instead of re-implementing them.

See it under the hood

Real recordings of the analyzer working against the repository's deterministic offline demo — local Composer path repositories, real solver runs, no network. Recordings never autoplay.

Staged Laravel 10 → 13 preflight, end to end. Direct and staged resolution both come back blocked: the 10→11 hop retains two simultaneous blockers with different lifecycles, 11→12 is Composer-feasible, and 12→13 stops on a missing platform extension plus an original-source finding. Before/after target digests match.
A blocker, up close. After the analysis, jq walks the canonical JSON: resolution.status, the blocker's dependency path and resolution options, then its evidence IDs — straight to the exact Composer command and the solver's own output excerpt.
Immutability, proven. A recursive SHA-256 digest over every file of the analyzed project before the run, a full analysis with real Composer scenarios in temporary workspaces, and the same digest afterwards. Byte-for-byte identical.
The Markdown projection. The same analysis rendered as Markdown — a faithful projection of the canonical JSON: the report's sections, the staged actions for the blocked 12→13 stage, and risk plus effort ranges with assumptions and confidence.

Choose Play to load a recording. Choose Stop to remove it immediately. No motion starts without your action, including when your system requests reduced motion.

What it is — and what it is not

PHP Upgrade Preflight is in public beta. It provides decision-support evidence: it does not perform the upgrade, does not modify or execute the analyzed application, does not prove runtime compatibility, and does not guarantee a successful deployment. Effort figures are ranges with stated assumptions, not promises.

Review every report and validate the resulting upgrade with the application's own test and deployment process. Secret redaction is a publication safeguard, not an execution sandbox.