README

The fastest way to find every breaking change before you upgrade Laravel.

One Artisan command scans your entire codebase and reports only the upgrade issues that actually exist in your project — across PHP files, composer.json, config files, and .env. Supports upgrading from Laravel 8 through 13 with 70+ checks covering every major breaking change.

Why Laravel Preflight?

The official Laravel upgrade guide lists every possible breaking change — but most of them won't affect your app. Reading through the full guide, manually searching your code, and checking config keys wastes hours.

This tool does it in seconds:

• Zero false positives — only flags issues found in your actual code
• Multi-version support — checking Laravel 8 → 13 covers all 5 intermediate upgrade paths in one run
• Actionable fixes — every issue includes the exact fix command or change needed
• No code modifications — read-only scan, safe to run any time
• CI/CD ready — exits with code 1 when blocking issues exist, 0 when clean

Installation

composer require jaydeep/laravel-preflight

Auto-discovered. No service provider registration needed.

Quick Start

# Scan for breaking changes before upgrading to Laravel 13
php artisan upgrade:check 13

# Scan for a specific target version
php artisan upgrade:check 11

# Generate a full HTML + Markdown report
php artisan upgrade:check 13 --report

The command auto-detects your current Laravel version from composer.json. Multi-version upgrades are fully supported — scanning from Laravel 8 to 13 covers all intermediate breaking changes in a single run.

Screenshots

Console Output

HTML Report

How It Works

1. Detect — Reads your composer.json to determine the current Laravel version and the target you specify.

2. Scan — Runs four analyzers across your codebase:

3. Report — Prints a grouped, colour-coded console report. Use --report to also write storage/upgrade-report.md and storage/upgrade-report.html.

Supported Upgrade Paths

Example Output

  Laravel Preflight  by Jaydeep
  ─────────────────────────────────────────

  Current Laravel: v8
  Target  Laravel: v13

  Scanning codebase...

  ┌─────────────────────────────────────────────┐
  │          UPGRADE COMPATIBILITY REPORT        │
  └─────────────────────────────────────────────┘

   CRITICAL  7   WARNING 8   INFO 5   Passed 54

  ── COMPOSER

  [CRITICAL] fruitcake/laravel-cors deprecated
         The fruitcake/laravel-cors package is superseded by Laravel's built-in CORS support.
           → composer.json
         Fix: Remove fruitcake/laravel-cors. Use the built-in config/cors.php.

  ── CODE

  [WARNING] Model $dates property deprecated
         The $dates property on Eloquent models is deprecated in L9, removed in L10.
           → app/Models/Post.php
         Fix: Replace protected $dates = [...] with protected $casts = ['field' => 'datetime'].

  ── MIDDLEWARE

  [CRITICAL] VerifyCsrfToken renamed to PreventRequestForgery
         The CSRF middleware class was renamed and now includes request-origin verification.
           → app/Http/Kernel.php
         Fix: Replace VerifyCsrfToken::class with PreventRequestForgery::class.

  54 check(s) passed (no issues found for those).

  Run with --report to save a full Markdown + HTML report:
  php artisan upgrade:check --report

Report Files

Add --report to generate both a Markdown and a self-contained HTML report:

php artisan upgrade:check 13 --report

Severity Levels

CI / CD Integration

The command exits with code 1 when any issues are detected, and 0 when the codebase is clean — making it easy to gate deployments or upgrade PRs in any CI pipeline.

# GitHub Actions example
- name: Check Laravel upgrade compatibility
  run: php artisan upgrade:check 13

# Fail a build if not ready to upgrade
php artisan upgrade:check 13 || exit 1

Extending: Adding a New Laravel Version

1. Create src/VersionRegistry/Laravel{N}Upgrade.php extending BaseUpgrade
2. Implement getBreakingChanges() returning an array of BreakingChange objects
3. Register it in VersionRegistry::$upgrades and bump $latestVersion

Each breaking change supports four detection strategies:

// Example: adding a breaking change
$this->change(
    'VerifyCsrfToken renamed to PreventRequestForgery',    // title
    'The CSRF middleware class was renamed in Laravel 13.', // description
    'critical',                                             // severity
    'middleware',                                           // category
    'Replace VerifyCsrfToken::class with PreventRequestForgery::class.', // fix
    '/VerifyCsrfToken/'                                     // searchPattern
);

Architecture

src/
├── UpgradeAssistantServiceProvider.php   Auto-discovered service provider
├── Commands/
│   └── UpgradeCheckCommand.php           php artisan upgrade:check
├── Analyzers/
│   ├── BaseAnalyzer.php
│   ├── ComposerAnalyzer.php              Scans composer.json
│   ├── CodeAnalyzer.php                  Regex scans PHP files
│   ├── ConfigAnalyzer.php                Checks config/ keys
│   └── EnvAnalyzer.php                   Checks .env.example keys
├── Data/
│   └── BreakingChange.php                Value object for a single issue
├── VersionRegistry/
│   ├── VersionRegistry.php               Maps version numbers to upgrade classes
│   ├── BaseUpgrade.php
│   ├── Laravel9Upgrade.php               L8 → L9 breaking changes
│   ├── Laravel10Upgrade.php              L9 → L10 breaking changes
│   ├── Laravel11Upgrade.php              L10 → L11 breaking changes
│   ├── Laravel12Upgrade.php              L11 → L12 breaking changes
│   └── Laravel13Upgrade.php              L12 → L13 breaking changes
└── Report/
    └── ReportGenerator.php               Console + Markdown + HTML report

Requirements

FAQ

Does it modify any files? No. The scan is entirely read-only. Nothing in your project is changed.

Can I run it on a project that is already on a newer version? Yes — the command detects your current version and skips checks that don't apply. If you're already on the target version it exits immediately.

How is it different from Rector or Laravel Shift? Rector and Shift modify your code. This tool only reports — it tells you what needs to change and where, so you can make the changes yourself with full control.

Can I use it in a pre-upgrade CI check? Yes. It returns exit code 1 when issues are found. Add it to your CI pipeline to block merges until the codebase is compatible with the target version.

What if a check fires but doesn't apply to my app? The results are informational. Review the listed file paths and decide whether the fix applies to your specific usage.

Contributing

Contributions are welcome — especially new breaking change definitions for existing or future Laravel versions.

1. Fork the repository
2. Add your breaking changes to the relevant Laravel{N}Upgrade.php file
3. Test by running php artisan upgrade:check against a project that uses the pattern
4. Open a pull request with a brief description of the breaking change and a link to the official Laravel upgrade guide

Related Packages

• jaydeep/laravel-guarddog — Laravel security scanner
• jaydeep/laravel-xray — Architecture visualization and dead code detection

License

MIT — Jaydeep Gadhiya