Laravel X Ray Laravel Package

Product Decisions This Supports

• Upgrade roadmap and release sequencing: The command's core job is to report what breaks when moving a codebase from one Laravel major version to another (e.g. 11.x → 13.x). That output is the input to deciding whether an upgrade lands this quarter, and which workstreams (framework upgrade, dependency bumps, refactors) must be sequenced around it.
• Build vs buy on internal upgrade tooling: Teams frequently hand-roll compatibility scripts or rely on tribal knowledge. A package that produces structured, severity-ranked findings replaces that ad-hoc tooling — a "buy/adopt" decision with a low adoption cost.
• CI gating as a product-quality lever (new in v1.5.0): --fail-on=error|warning|info turns the scanner from an advisory report into an enforceable gate. This shifts a product decision from "should we scan?" to "what severity do we block merges on?" — a policy choice with direct consequences for developer velocity versus regression risk.
• Severity policy per surface: Because the threshold is configurable and respects the existing minimum_severity setting, the same tool can run strict in a pre-release branch and lenient on legacy maintenance branches. This supports differentiated quality bars across a product portfolio rather than one blanket rule.
• Machine-readable reporting for dashboards: --format=json combined with threshold-based exit codes lets findings flow into existing observability or release-readiness dashboards without bespoke parsing.
• Use cases: pre-upgrade feasibility spikes, PR gates on active branches, scheduled drift detection as dependencies release, and go/no-go evidence in upgrade RFCs.

When to Consider This Package

Adopt when:

• You maintain one or more Laravel applications with a known or planned major-version upgrade on the roadmap — the value is highest when the upgrade is imminent or recurring.
• You already run CI on pull requests and want upgrade-readiness enforced without writing custom scripts; --fail-on plus --format=json covers the common pipeline shapes out of the box.
• You need severity-tiered findings rather than a binary pass/fail, so teams can triage blockers (errors) separately from cleanup (info).
• Multiple teams or repos must apply a consistent, configurable quality bar — the minimum_severity setting gives you a single knob to standardize.

Look elsewhere or defer when:

• The application is not on Laravel, or is pinned to a version with no planned movement — the scanner has little to report and the gate becomes noise.
• You need runtime or behavioural verification (load tests, integration suites, browser-level checks). This is a static/analysis tool; treat it as a complement to, not a replacement for, a real test suite.
• Your pipeline needs SARIF or a specific vendor's native format — JSON plus table is the current surface, so plan for a small adapter.
• Your organization has no appetite for failing builds on warnings; adopting the package is still worthwhile, but leave --fail-on unset (the default is non-failing) until the team has agreed a threshold.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk addition that de-risks our Laravel upgrade work. It gives us a repeatable, evidence-based answer to "what breaks if we upgrade, and when can we ship it?" instead of relying on estimates. With the new release, the same check can run automatically on every pull request and block changes that introduce upgrade blockers — so upgrade cost gets paid down continuously rather than as a single disruptive project. Investment is limited to pipeline configuration; there is no new infrastructure or licensing to manage.

For engineering leadership: It's a single Artisan command producing severity-ranked findings in human-readable or JSON form. v1.5.0 adds --fail-on (error/warning/info) with matching exit codes, and honours the existing minimum_severity configuration, so we can gate CI without custom glue or wrapper scripts. Default behaviour is unchanged and non-failing — findings are advisory until we explicitly choose a threshold — which means we can pilot it on one repository, measure the false-positive rate, then promote it to a required check. Recommended next steps: run it once against the current codebase to size the findings, agree a threshold per branch (strict on main, lenient on maintenance branches), then wire it into CI and pipe the JSON output into our existing reporting.