Laravel Code Analyse Laravel Package

Technical Evaluation

Architecture fit. Larastan is a development-time static analysis extension for PHPStan, not a runtime library. It contributes no routes, service providers, container bindings, migrations, or production code paths. Adoption is a require-dev line, a phpstan.neon (or the wrapper's defaults), and a CI invocation — removable by reverting a single lockfile entry. For a TPM this is the cheapest defensible risk class available: no deployment window, no data migration, no on-call rotation impact, and no customer-visible behaviour change.

The one architectural decision that must be made explicitly is which layer we standardize on, because the supplied metadata conflates two:

Standardizing on the wrapper and then discovering we need custom rules, targeted suppressions, stubs, or coexistence with other extensions pushes us into raw PHPStan configuration anyway. The wrapper's defaults must therefore be reconcilable with team policy, not a black box we inherit. Recommendation: adopt the engine as the durable dependency and treat the wrapper as an optional onboarding convenience for repos with no analysis today. Mixing the two across repositories creates two divergent profiles and two upgrade cadences — a governance problem disguised as a tooling choice.

Integration feasibility. High. v3.13.0 is purely additive and fix-oriented — no removals, no deprecations, no config-breaking changes, and unchanged PHP/Laravel requirements versus 3.12.x. The only hard constraint is inherited from the engine: PHPStan ≥ 2.3.0 within the 2.x line. That makes this a coupled dependency bump, not a routine patch, and it should be scheduled as such rather than opportunistically merged.

Relevant capability deltas to budget review time for:

• relation-of<Model, Relationship> custom type plus inferred relationship types inside with(), withOnly(), load(), loadMissing() — improves safety of eager-loading-heavy code, which is exactly the layer unit tests under-cover.
• Corrected collection key types for concat(), merge(), shift(), splice() — may surface previously silent key-collision and renumbering assumptions.
• New diagnostic for invalid eager-loading column selection combined with callbacks (e.g. with(['posts:id' => $callback])) — a genuine correctness and performance pitfall, and the strongest single argument for making analysis a blocking gate rather than advisory.
• toBase() forwarded builder call resolution — directly relevant to any repo with custom Eloquent query builders, which is common in mature Laravel codebases.
• Null package-manifest path fix during bootstrap — removes a class of stripped-CI bootstrap failures.

Technical risk.

Key questions (these should be answered before the rollout decision, not after):

1. Identity: What is the canonical composer package and who publishes it? Why is the dependents count zero and the release date in the future?
2. Layer: Do we standardize on the engine, the wrapper, or the engine with a thin internal defaults package we own? Who owns each in eighteen months?
3. Scope: Which repositories are in scope, and which are excluded because they are prototypes, non-Laravel, or on a legacy Laravel version outside the 3.x support matrix? Exclusions must be recorded, not silently skipped.
4. Gate posture: Is analysis blocking or advisory at each rollout stage, and what is the promotion criterion from advisory to blocking?
5. Ownership: Who is the named owner of the shared config and the baseline? What is the triage SLA for a new failure introduced by a feature PR?
6. Coupled deps: Can PHPStan 2.3 land in the same change window as Larastan 3.13, and are all co-installed extensions 2.3-compatible today?
7. Value measure: What defect class or escape-rate metric are we trying to move, so we can tell in two quarters whether this worked?

Integration Approach

Stack fit. Strong fit for any actively developed Laravel application or shared Laravel package where Eloquent relationships, query builders, facades, and collections carry business logic — that is, the layer that tests routinely under-cover and where refactoring is perceived as risky. Poor fit, and should be declined, for prototypes, throwaway spikes, short-lived internal tools (setup plus triage exceeds value returned) and any non-Laravel PHP project (generic PHPStan already covers it; the entire value is framework-aware inference).

Positioning constraints to communicate widely, because mis-selling this creates the wrong expectations: it is not a security scanner, a performance profiler, a replacement for tests, or a runtime safeguard. It changes nothing about production behaviour, so it is not an input to availability, scaling, or incident-response planning.

Migration path. A three-stage rollout, each with an explicit exit criterion:

1. Pilot (one repo, 1–2 weeks). Pick the repo with the highest Eloquent density and a maintainer who will own the outcome. Install Larastan 3.13 + PHPStan 2.3 in one PR. Run in advisory mode. Produce a three-bucket triage: genuine bugs surfaced, false positives (baseline with a written reason), pre-existing debt (file to backlog, do not fix in the upgrade PR). Exit criterion: a baseline that records decisions, plus a measured error-delta report.
2. Template (1 sprint). Extract a shared phpstan.neon with the agreed level, ignore paths, and extension set. Publish a short adoption runbook covering install, upgrade, triage, and baseline rules. Validate the runbook by applying it to a second repo without the pilot owner driving.
3. Rollout (per-repo, batched). Apply the template repo by repo, promote to blocking in CI only after that repo's baseline is clean and owned. Repos that cannot move PHPStan in lockstep stay on 2.x + Larastan 2.x and are recorded as an explicit divergence with a scheduled catch-up date.

Compatibility. The compatibility surface is small but strictly coupled:

Sequencing. Frame this as a maintenance-window item, not a background chore:

1. Resolve identity/provenance (key question 1) and confirm the canonical package and publisher.
2. Audit co-installed PHPStan extensions for 2.3 compatibility.
3. Confirm the owner and triage capacity for the pilot.
4. Ship the coupled bump (PHPStan ^2.3 + Larastan ^3.13) in a single PR; inspect the lockfile diff for transitive changes.
5. Capture the analysis delta against a pre-upgrade run; triage into the three buckets; regenerate the baseline after triage.
6. Keep the PHPStan 2.3 bleeding-edge inference flag (empty collections, closures) out of the blocking gate; evaluate it in a separate non-blocking job.
7. Promote to blocking, then extract the template, then roll out.
8. Only afterwards, start using the new capability: apply relation-of to the highest-value signatures — query-builder returns, repository methods, and model scopes.

Rationale for the ordering: steps 1–3 are cheap and prevent an expensive rollback; step 4 is atomic by necessity; steps 5–6 are where the actual product value is either captured or lost; step 8 is where the investment compounds.

Operational Impact

Maintenance. Recurring cost is modest but not zero: roughly one engineer-day per repository per upgrade cycle plus baseline review. Three recurring obligations must be resourced, not assumed:

• Version tracking. Larastan moves fast (3.13.0 alone carries four fix areas and two feature areas, with first-time contributors). Assign a named owner to watch releases and schedule a standing quarterly upgrade slot.
• Baseline governance. Every baseline entry needs a one-line reason and a link to the underlying ticket. Regenerate the baseline only after triage, never as a way to get CI green — a baseline regenerated under delivery pressure is the failure mode, not the mitigation.
• Shared config stewardship. A single versioned phpstan.neon plus a documented policy for suppressions. Without this, per-repo configs drift into inconsistent gates within two quarters and the org-wide comparison loses meaning.

Support. Support burden is deliberately low because there is no production surface. Model it as:

• Tier 1 — repo maintainer: runs the command, triages new failures in their own PRs.
• Tier 2 — analysis owner (one named engineer, part-time): adjudicates false positives, owns the shared config and baseline policy, and is the point of contact for extension coexistence problems.
• Tier 3 — upstream: GitHub issues against Larastan/PHPStan. Realistic expectation: upstream fixes land on upstream cadence, so a blocking false positive needs a documented suppression as the escape hatch, not a wait for a patch.

There is no on-call implication. Escalation is a delivery-velocity concern (a blocked PR), never an availability concern.

Scaling. Scaling is a function of repository count, not traffic, and it behaves well:

• Config and runbook scale by templating; per-repo tuning is the anti-pattern to actively resist.
• Runtime cost scales with codebase size and analysis level. On large monorepos, expect CI minutes to grow and consider path-scoped analysis (analyse changed modules) plus result caching before raising the level further.
• The wrapper-vs-engine split is the principal scaling hazard: wrapper defaults are an adoption asset at one repo and a liability at twenty, because the first repo that needs a custom rule or targeted suppression lands in raw PHPStan config, and its opinions must be reconciled with team policy rather than quietly overriding it.
• Shared Laravel packages are a force multiplier: fixing return types and toBase() resolution once improves analysis accuracy for every consumer.

Failure modes.

Ramp-up. Realistic enablement estimates:

• Pilot repo, first run: 1–2 days including triage — the first run will produce a delta even with zero application changes, because new relationship and collection inference legitimately surfaces previously silent issues. Budgeting zero here is the most common planning error.
• Second repo via runbook: half a day, which is the real proof that the template works.
• Steady state per repo: ~1 engineer-day per upgrade cycle plus ongoing review attention measured in minutes per PR.
• Team enablement: a single 30–45 minute session plus the runbook. Developers need to interpret output and distinguish "my bug" from "baseline candidate," not to author PHPStan extensions.

Success measures to commit to now, so the investment is falsifiable in two quarters: (a) number of genuine defects surfaced during the pilot and first three rollouts; (b) share of PRs failing analysis before merge, tracked as an early-warning lead indicator; (c) baseline entry count trending flat or down per repo; (d) refactor throughput on Eloquent-heavy modules — the number of modernization PRs greenlit that would previously have been judged too risky. If (a) is zero and (d) does not move, the tool is a green checkmark and should be re-scoped or dropped rather than maintained out of inertia.