Laravel X Ray Laravel Package

Getting Started

laravel-x-ray is a dev-only upgrade scanner: you point it at your current Laravel constraint and a target constraint, and it reports code that is likely to break between them.

1. Install as a dev dependency and publish its config:

   composer require --dev laravel-x-ray/laravel-x-ray
   php artisan vendor:publish --tag="x-ray-config"
   

2. Look first at config/x-ray.php — the minimum_severity key is the single most important setting, because it gates both what is reported and (since v1.5.0) what causes a non-zero exit.
3. Run your first scan against the version pair you actually care about:

   php artisan laravel-x-ray 11.x 13.x
   

4. Treat the output as a triage list, not a to-do list. Start with error findings in app/ and routes/, then work outward to warning/info (typically deprecations and API-shape changes).

The canonical first use case is "I'm planning an 11.x → 13.x upgrade, what will bite me?" Run the scan on a clean branch, commit nothing, and use the findings to scope the upgrade.

Implementation Patterns

Local pre-upgrade triage. Run the bare command (table format, all severities) before opening the upgrade PR. Keep the output in the PR description so reviewers can see which findings were fixed versus deferred.

CI gate on pull requests. This is what v1.5.0 unlocks. Add a job that fails the build when the scan finds anything at or above your chosen threshold:

php artisan laravel-x-ray 11.x 13.x --fail-on=warning

Use --fail-on=error while you're mid-upgrade and the codebase still has known warnings, then ratchet down to --fail-on=warning once you're clean. The threshold is a ratchet, not a fixed setting.

Machine-readable reports for dashboards or PR annotations. Pair JSON output with a threshold:

php artisan laravel-x-ray 11.x 13.x --format=json --fail-on=error > x-ray.json

Because the exit code is still non-zero on failure, wrap it so the artifact is written before the step fails (|| true on the redirect step, or continue-on-error plus a separate assertion step). Otherwise your CI job aborts before the JSON is uploaded.

Gate only the upgrade window. Wire the job to run when composer.json's laravel/framework constraint changes, or on a scheduled weekly run against the next major. Running it on every push against an unchanged constraint just burns CI minutes and trains people to ignore the failure.

Align config with CI intent. Set minimum_severity in config to the lowest severity you care about at all, and let --fail-on decide what breaks the build. If you set minimum_severity: error, --fail-on=warning becomes a no-op — warnings are never reported, so they can never trip the threshold.

Gotchas and Tips

The default is a green build, always. Without --fail-on, findings never produce a non-zero exit. If you added this to CI before v1.5.0 expecting it to guard anything, it wasn't — check your pipeline history for scans that "passed" with findings in the log.

minimum_severity silently overrides --fail-on. This is the most likely source of confusion after upgrading: --fail-on=info with minimum_severity: warning will not fail on info findings, because they were never emitted. If a threshold "isn't working," check the config before you check the command.

Severity is ordered, not exact-match. --fail-on=info means info and worse, i.e. everything. --fail-on=error means only errors. Pick the strictest threshold you can sustain; loosening it later is easier to justify than tightening it.

JSON plus failure needs deliberate plumbing. The non-zero exit and the JSON payload are both produced by the same run, so a naive cmd > out.json inside a failing CI step can leave you with an empty or partial artifact depending on your shell and runner. Separate "produce the report" from "assert the threshold" if the artifact matters.

Pin the version in CI. The threshold semantics and severity vocabulary are exactly the kind of thing that shifts between minor releases. A ^1.5 constraint is fine for local work; pin the exact version in the CI image so a routine composer update can't change what fails your build.

Extension points are config-first. Custom severity mapping and path exclusions live in config/x-ray.php — prefer adjusting config over wrapping the command, since a wrapper won't carry through to future flags like --fail-on. If you need per-environment thresholds, drive --fail-on from an env var in the CI script rather than maintaining multiple config files.

Version arguments are constraints, not versions. 11.x and 13.x are the framework release lines to compare; passing a specific patch like 11.30 is not the intended form and the comparison may not behave as you expect.

Expect false positives on dynamic code. Anything resolved at runtime (container bindings by string, dynamic model relations, macro registrations) is hard to statically detect. A clean scan is evidence, not proof — still run the test suite against the target version.