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

Command	Description
`upgrade:analyze`	Analyze project for upgrade readiness with risk score
`upgrade:prompt`	Generate AI-ready upgrade prompt with all details
`upgrade:packages`	Check package compatibility against target version
`upgrade:report`	Generate HTML/JSON/Markdown upgrade report
`upgrade:fix`	Preview or apply simple auto-fixes for breaking changes
`upgrade:ci`	CI/CD integration with configurable risk threshold
`upgrade:wizard`	Interactive guided wizard (requires Laravel 10+)

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

Feature	Laravel Shift	Upgrade Pilot
Price	$9-39/shift	Free (MIT)
Runs locally	No (cloud)	Yes
Pre-upgrade analysis	No	Yes
Risk scoring	No	Yes
AI-ready prompts	No	Yes
Package check	Basic	Detailed + alternatives
Open source	No	Yes

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:

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

License

MIT License. See LICENSE for details.

vocweb / laravel-upgrade-pilot

Maintainers

Package info

Statistics

Security