Backend

laravel-migration

Handles version upgrades and legacy migrations

Overview

The laravel-migration agent handles Laravel version upgrades and legacy code migrations. It uses tools like Rector for automated refactoring, updates deprecated syntax, migrates configuration files, and ensures compatibility with newer Laravel versions.

Responsibilities

  • Version Upgrades - Laravel 9→10, 10→11, etc.
  • Syntax Updates - Replace deprecated patterns
  • Configuration Migration - Update config files to new formats
  • Service Provider Updates - Migrate boot/register methods
  • Route Migration - Update route syntax and middleware
  • Package Compatibility - Check and update dependencies

Tools Used

Tool Purpose
rector Automated PHP code refactoring
php-cs-fixer Code style fixing
phpstan Static analysis for issues
composer Dependency updates

Migration Process

┌─────────────────────────────────────────────────────────────┐
│               Laravel Version Migration Flow                 │
├─────────────────────────────────────────────────────────────┤
│  1. Analyze Current State                                    │
│     → Check Laravel version                                  │
│     → List installed packages                                │
│     → Identify deprecated patterns                           │
├─────────────────────────────────────────────────────────────┤
│  2. Update Dependencies                                      │
│     → Update composer.json                                   │
│     → Run composer update                                    │
│     → Resolve conflicts                                      │
├─────────────────────────────────────────────────────────────┤
│  3. Run Rector                                               │
│     → Apply Laravel upgrade rules                            │
│     → Fix deprecated syntax                                  │
│     → Update type hints                                      │
├─────────────────────────────────────────────────────────────┤
│  4. Update Configuration                                     │
│     → Merge new config options                               │
│     → Update env variables                                   │
│     → Fix middleware registration                            │
├─────────────────────────────────────────────────────────────┤
│  5. Verify & Test                                            │
│     → Run PHPStan                                            │
│     → Run test suite                                         │
│     → Manual verification                                    │
└─────────────────────────────────────────────────────────────┘

Common Migration Examples

// Laravel 10→11: Route model binding syntax
// BEFORE (L10)
Route::get('/users/{user}', [UserController::class, 'show']);

// AFTER (L11) - No change needed, but explicit binding:
Route::get('/users/{user}', [UserController::class, 'show'])
    ->whereNumber('user');

// Service Provider: boot() with type hints
// BEFORE
public function boot()
{
    //
}

// AFTER
public function boot(): void
{
    //
}

// Middleware registration (L11)
// BEFORE (kernel.php)
protected $middlewareGroups = ['web' => [...]];

// AFTER (bootstrap/app.php)
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        MyMiddleware::class,
    ]);
})

Rector Configuration

<?php

// rector.php
use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
use RectorLaravel\Set\LaravelSetList;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app',
        __DIR__ . '/config',
        __DIR__ . '/routes',
        __DIR__ . '/tests',
    ])
    ->withSets([
        LevelSetList::UP_TO_PHP_83,
        LaravelSetList::LARAVEL_110,
    ])
    ->withSkip([
        __DIR__ . '/bootstrap/cache',
    ]);

Package Compatibility Check

# Check for outdated packages
composer outdated

# Check Laravel compatibility
composer why-not laravel/framework:^11.0

# Update with dry-run
composer update --dry-run

# Update specific package
composer require laravel/framework:^11.0 -W

Post-Migration Checklist

  • Run php artisan optimize:clear
  • Run full test suite
  • Check error logs
  • Verify queue workers restart
  • Test scheduled commands
  • Verify API endpoints
  • Check for deprecation warnings

Invoked By Commands

Guardrails

The migration agent follows strict rules:

  • ALWAYS backup before version upgrades
  • ALWAYS run tests after each migration step
  • ALWAYS upgrade incrementally (not multiple versions)
  • NEVER skip deprecated warning review
  • NEVER modify vendor files directly

See Also