README

Pre-upgrade analysis, risk assessment, and AI-ready upgrade prompts for Laravel applications.

An open-source alternative to paid upgrade services. Analyze your project locally, get a detailed upgrade plan, and generate prompts for AI agents to execute the upgrade — no need to push code to external services.

Features

• Risk Assessment — Get a risk score (0-10) before upgrading
• Breaking Change Detection — Scans your codebase for known breaking changes with file-by-file impact
• Package Compatibility — Checks all Composer packages against Packagist for target version support
• PHP Compatibility — Validates PHP version and required extensions
• AI-Ready Prompts — Generate detailed upgrade prompts for Claude Code, Codex, Cursor, or any AI agent
• Beautiful Reports — HTML, JSON, and Markdown report generation
• CI/CD Integration — JSON output with configurable exit codes for pipelines
• 100% Local — Everything runs on your machine. No code leaves your project.
• Community-Driven Rules — Breaking changes defined in YAML, easy to contribute

Requirements

• PHP 8.1+
• Laravel 8, 9, 10, 11, or 12

Installation

composer require vocweb/laravel-upgrade-pilot --dev

Quick Start

1. Analyze your project

# Analyze upgrade to the next major version
php artisan upgrade:analyze

# Analyze upgrade to a specific version
php artisan upgrade:analyze --target=12

2. Generate an AI upgrade prompt

This is the key feature. Generate a detailed prompt and pass it to your AI agent:

# Output prompt to terminal
php artisan upgrade:prompt --target=12

# Copy to clipboard (macOS)
php artisan upgrade:prompt --target=12 | pbcopy

# Copy to clipboard (Linux)
php artisan upgrade:prompt --target=12 | xclip -selection clipboard

# Save to file
php artisan upgrade:prompt --target=12 --output=upgrade-prompt.md

Then paste the prompt into Claude Code, Codex, Cursor, or any AI coding agent. The prompt contains everything the agent needs:

• Current and target versions
• Exact composer commands to run
• Breaking changes with file paths and line numbers
• Search/replace patterns for code fixes
• Package compatibility issues
• Manual review checklist
• Verification steps

3. Check package compatibility

php artisan upgrade:packages --target=12

4. Generate detailed report

# HTML report (recommended)
php artisan upgrade:report --format=html

# Markdown or JSON
php artisan upgrade:report --format=markdown
php artisan upgrade:report --format=json

Commands Reference

Example: AI Upgrade Prompt Output

# Laravel Upgrade Task

## Context
- **Current**: Laravel 11.34.2 (PHP 8.3.14)
- **Target**: Laravel 12.x (requires PHP 8.2+)
- **Risk Score**: 4.2/10 (MEDIUM)
- **Estimated Effort**: 2-5 hours
- **Auto-fixable**: 62%

## Step 1: Update Composer Dependencies

Run these commands in order:

  composer require laravel/framework:^12.0
  composer require nesbot/carbon:^3.0

## Step 2: Fix Breaking Changes

### [HIGH] Carbon 2.x support removed (12 occurrences)

All Laravel 12 applications now require Carbon 3.x.

**Files affected:**
- `app/Services/DateService.php`:42,58
- `app/Models/Order.php`:118

Docs: https://laravel.com/docs/12.x/upgrade#carbon

### [MEDIUM] HasUuids trait now uses UUIDv7 (3 occurrences)

**Find and replace:**
- Search: `use Illuminate\Database\Eloquent\Concerns\HasUuids;`
- Replace: `use Illuminate\Database\Eloquent\Concerns\HasVersion4Uuids as HasUuids;`

## Package Compatibility Issues

- **[NEEDS_UPGRADE]** `barryvdh/laravel-ide-helper` (current: 2.15): Needs upgrade to 3.1

## Verification

After completing all changes:

1. Run `composer update` to resolve all dependencies
2. Run `php artisan optimize:clear` to clear caches
3. Run `php artisan test` to verify all tests pass

Example: Analysis Output

Laravel Upgrade Pilot — Analyzing your project...

Current Laravel version: 11.34.2 => Target Laravel version: 12.x

  Summary

  Risk Score ············ 4.2/10 (MEDIUM)
  Estimated Effort ······ 2-5 hours
  Auto-fixable ·········· 62%

  Breaking Changes — 5 found
    HIGH (1)
      - Carbon 2.x support removed (12 occurrences) [auto-fixable]
    MEDIUM (2)
      - HasUuids trait now uses UUIDv7 (3 occurrences) [auto-fixable]
      - mergeIfMissing() dot notation change (1 occurrence)
    LOW (2)
      - Schema getTableListing() qualified names
      - Blueprint constructor signature

Programmatic Usage

use vocweb\UpgradePilot\Facades\Upgrade;

$result = Upgrade::analyze(target: 12);

$result->riskScore;          // 4.2
$result->riskLevel;          // 'medium'
$result->breakingChanges;    // Collection
$result->packageIssues;      // Collection
$result->autoFixablePercent; // 62.0
$result->estimatedEffort;    // '2-5 hours'

Custom Breaking Change Rules

Publish and customize the rules:

php artisan vendor:publish --tag=upgrade-pilot-rules

Rules are defined in YAML:

breaking_changes:
  - id: my-custom-check
    severity: high
    title: "Custom check for our codebase"
    description: "We use a pattern that breaks in L13"
    detection:
      type: code_pattern
      pattern: "OurLegacyClass::method("
    auto_fix:
      type: code_replace
      search: "OurLegacyClass::method("
      replace: "OurNewClass::method("
    manual_steps:
      - "Review all usages after replacement"

Supported Upgrade Paths

• Laravel 8 → 9
• Laravel 9 → 10
• Laravel 10 → 11
• Laravel 11 → 12
• Multi-version jumps (e.g., 10 → 12)

Comparison with Laravel Shift

Tip: Use Upgrade Pilot to generate a prompt, then let an AI agent handle the actual code changes. This combines Pilot's deep analysis with AI's code editing capabilities.

Contributing

Contributions are welcome! The most impactful ways to contribute:

1. Add breaking change rules for new Laravel versions in resources/breaking-changes/
2. Report false positives/negatives in detection patterns
3. Improve package compatibility checking logic

License

MIT License. See LICENSE for details.