Phpstan Composer Analysis Laravel Package

Technical Evaluation

pb30/phpstan-composer-analysis is a thin adapter that surfaces shipmonk/composer-dependency-analyser findings through PHPStan. In practice it lets a team consolidate dependency-hygiene checks (unused, shadow, and misplaced Composer requirements) into the same static-analysis gate they already run, rather than maintaining a separate CI job.

Architecture fit. Strong conceptually for teams with a mature PHPStan pipeline. The wrapper adds a rule/adapter at the PHPStan layer; it does not replace Composer's own validation or the analyser's CLI. It fits best as a dev-only dependency consumed via phpstan/extension-installer or explicit includes: in phpstan.neon. Architecturally it is a convenience integration, not a platform component — treat it as a plug-in, not a dependency of your build system.

Integration feasibility. Low-effort to evaluate: composer require --dev plus a rule registration, then run PHPStan as usual. Main unknowns are version pinning across three moving parts (PHPStan, the analyser, and this wrapper) and whether the wrapper shells out to the analyser binary or re-implements findings as a PHPStan rule — the latter is more cache-friendly and CI-portable.

Technical risk. Elevated for a 17-star, unknown-repository package. Key risks: (1) bus factor and maintainer continuity; (2) coupling to PHPStan internals, which have historically churned across majors; (3) output-format dependence on shipmonk/composer-dependency-analyser; (4) potential duplication with an existing analyser CI step; (5) result-cache behavior — if the rule reads composer.json/composer.lock, PHPStan's cache may need invalidation hooks.

Key questions to resolve before adoption.

• Which PHPStan major/minor versions are supported, and is the analyser version range bounded?
• Does it execute the analyser as a subprocess or translate findings into native PHPStan errors? (affects caching, CI portability, and error suppression via ignoreErrors/baseline)
• Does it require vendor/ and a resolved composer.lock, and how does it behave in split/monorepo layouts?
• Can findings be baselined so existing debt doesn't block the pipeline on day one?
• License, maintainer responsiveness, and upstream release cadence (last release 2025-11-28 is recent, but one data point).
• Is there a documented fallback if PHPStan upgrades break the wrapper?

TPM verdict. Score (2.37/5) and low opportunity signal (0.39) argue for a contained pilot, not a mandated standard. Value is real but incremental — mostly CI consolidation and earlier feedback — and is fully achievable today with the upstream analyser's own CI invocation.

Integration Approach

Stack fit. Target profile: PHP 8.x, Composer 2, PHPStan 1.x or 2.x already enforced in CI, and either an existing composer-dependency-analyser job or a known desire to add dependency hygiene. Poor fit for teams without PHPStan, or for projects with heavy dynamic/conditional dependency loading where false positives are likely.

Migration path.

1. Pick one representative repository — ideally a library or a service with a clean composer.json.
2. Add the wrapper as a require-dev alongside existing tooling; do not remove the standalone analyser job yet.
3. Register the rule in a non-blocking PHPStan run and diff its findings against the analyser's CLI output. Agreement should be near-total; divergence is a red flag.
4. If findings align, baseline existing violations and promote to blocking.
5. Only then retire the redundant CI step.

Compatibility checks. Confirm PHPStan version against the wrapper's composer.json constraints; confirm the analyser's supported PHP/Composer range; verify phpstan/extension-installer behavior if used; validate on the oldest PHP version in your support matrix. Test with a stale composer.lock and with no lock at all to see failure behavior.

Sequencing. Dependency hygiene → PHPStan gate consolidation → CI simplification. Do not attempt to roll this out across many repositories until the pilot has survived at least one PHPStan minor upgrade; that upgrade is the real compatibility test.

Rollback. Because it is a dev-only Composer package plus a config stanza, rollback is a one-line config revert. This keeps the blast radius small and is the strongest argument for allowing a pilot.

Operational Impact

Maintenance. The wrapper itself should be near-zero-maintenance, but you inherit two upstreams. Pin exact versions and treat upgrades as deliberate changes, not floating ^ ranges. The realistic maintenance cost is watching — someone must track PHPStan releases and the analyser's changelog, or the rule silently stops running after a major bump.

Support. No vendor SLA, no commercial backing, unknown repository. A TPM should assume internal ownership: designate a maintainer, document the config, and be prepared to fork or drop the wrapper if upstream stalls. The fallback (running the analyser directly in CI) is trivial, which bounds the risk.

Scaling. Runtime is negligible relative to full PHPStan analysis; the rule runs once per analysis pass over project metadata, not per file. Scaling is organizational, not computational: distribute a shared CI template and phpstan.neon include across repositories. Watch memory ceilings on large monorepos and confirm the rule participates sensibly in PHPStan's result cache.

Failure modes.

• Silent no-op: rule registered but not executed due to namespace/extension-installer misconfiguration — worse than a failure because teams believe they are covered.
• False positives: dynamic requires, platform-conditional extensions, and polyfill packages flagged as unused.
• Hard failure on upgrade: PHPStan API drift breaking the wrapper.
• Missing/stale lock file: analyser may error or return incomplete results in fresh checkouts or monorepo subpackages.
• Duplicate gating: both the wrapper and a leftover analyser CI job running, doubling noise and cost.

Mitigate with a canary run in CI, explicit ignoreErrors entries for known false positives, and an alert if the rule reports zero findings across a large codebase (a likely signal it silently stopped running).

Ramp-up. Low for teams already fluent in PHPStan — a config stanza and a short note in the contributing guide. Moderate for teams new to composer-dependency-analyser: they must learn to interpret "shadow" and "misplaced" dependency findings and to distinguish a real composer.json defect from a static-analysis artifact. Budget a short internal write-up plus one pairing session; sparse external documentation should be assumed.