PHPackages                             vocweb/laravel-upgrade-pilot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. vocweb/laravel-upgrade-pilot

ActiveLibrary[Database & ORM](/categories/database)

vocweb/laravel-upgrade-pilot
============================

Pre-upgrade analysis, risk assessment, and automated upgrade assistance for Laravel applications

v1.1.8(1mo ago)016—0%MITPHPPHP ^8.1

Since Mar 20Pushed 1mo agoCompare

[ Source](https://github.com/vocweb/laravel-upgrade-pilot)[ Packagist](https://packagist.org/packages/vocweb/laravel-upgrade-pilot)[ RSS](/packages/vocweb-laravel-upgrade-pilot/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelogDependencies (9)Versions (14)Used By (0)

Laravel Upgrade Pilot
=====================

[](#laravel-upgrade-pilot)

**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
--------

[](#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
------------

[](#requirements)

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

Installation
------------

[](#installation)

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

Quick Start
-----------

[](#quick-start)

### 1. Analyze your project

[](#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

[](#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

[](#3-check-package-compatibility)

```
php artisan upgrade:packages --target=12
```

### 4. Generate detailed report

[](#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
------------------

[](#commands-reference)

CommandDescription`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
---------------------------------

[](#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
------------------------

[](#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
------------------

[](#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
----------------------------

[](#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
-----------------------

[](#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
-----------------------------

[](#comparison-with-laravel-shift)

FeatureLaravel ShiftUpgrade PilotPrice$9-39/shift**Free (MIT)**Runs locallyNo (cloud)**Yes**Pre-upgrade analysisNo**Yes**Risk scoringNo**Yes**AI-ready promptsNo**Yes**Package checkBasic**Detailed + alternatives**Open sourceNo**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
------------

[](#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
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

12

Last Release

52d ago

PHP version history (2 changes)v1.0.0PHP ^8.2

v1.0.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/30e3379e8d19b8dfc60d98859c909d9f83845b445558b103cb52286c293070e6?d=identicon)[tien](/maintainers/tien)

---

Top Contributors

[![vocweb](https://avatars.githubusercontent.com/u/285232?v=4)](https://github.com/vocweb "vocweb (1 commits)")

---

Tags

compatibilitylaravelmigrationanalysisupgraderisk-assessment

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/vocweb-laravel-upgrade-pilot/health.svg)

```
[![Health](https://phpackages.com/badges/vocweb-laravel-upgrade-pilot/health.svg)](https://phpackages.com/packages/vocweb-laravel-upgrade-pilot)
```

###  Alternatives

[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[cybercog/laravel-clickhouse

ClickHouse migrations for Laravel

163166.8k](/packages/cybercog-laravel-clickhouse)[laravel/vapor-cli

The Laravel Vapor CLI

31310.7M8](/packages/laravel-vapor-cli)[erag/laravel-disposable-email

A Laravel package to detect and block disposable email addresses.

226102.4k](/packages/erag-laravel-disposable-email)[toponepercent/baum

Baum is an implementation of the Nested Set pattern for Eloquent models.

3154.7k](/packages/toponepercent-baum)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)