/laravel-agent:migrate:from-legacy

Overview

The /migrate:from-legacy command helps you migrate from legacy systems, other frameworks, or upgrade Laravel and PHP versions. It analyzes your current state, identifies breaking changes, and performs the necessary updates to modernize your codebase while ensuring compatibility.

Usage

/laravel-agent:migrate:from-legacy <source> [target]

Examples

# Upgrade to latest Laravel version
/laravel-agent:migrate:from-legacy laravel-10

# Specific Laravel version upgrade
/laravel-agent:migrate:from-legacy laravel-11 laravel-12

# Migrate from other frameworks
/laravel-agent:migrate:from-legacy symfony
/laravel-agent:migrate:from-legacy codeigniter

# PHP version upgrade
/laravel-agent:migrate:from-legacy php-8.1 php-8.3

# Database migration
/laravel-agent:migrate:from-legacy database mysql postgres

Migration Process

The command follows a systematic approach to ensure safe and complete migration:

1. Analyze Current State

First, the command analyzes your current environment:

php -v
php artisan --version
composer show laravel/framework

2. Identify Migration Type

Based on your input, it determines the appropriate migration strategy:

Laravel version upgrade - Updates framework and dependencies
PHP version upgrade - Adopts new language features and fixes deprecations
Framework migration - Converts from another PHP framework
Database migration - Migrates between database systems

3. Invoke Migration Agent

The specialized migration agent performs the actual migration work:

Perform migration:

Action: <upgrade|migrate-framework|migrate-database>
From: <source>
To: <target>
Focus: <specific areas>

4. Report Results

After completion, you receive a comprehensive migration report:

## Migration: <Source> → <Target>

### Analysis
- Current state: ...
- Breaking changes: ...
- Estimated effort: ...

### Steps Completed
- [x] Dependencies updated
- [x] Config migrated
- [x] Code modernized
- [x] Tests passing

### Manual Steps Required
1. ...
2. ...

### Validation
```bash
vendor/bin/pest
vendor/bin/phpstan analyse
```

Migration Types

Laravel Version Upgrade

Usage: /laravel-agent:migrate:from-legacy laravel-10

Upgrades your Laravel application to a newer version with the following automated steps:

Updates composer.json with new version requirements
Applies configuration file changes
Fixes deprecated methods and APIs
Updates service providers and middleware
Runs automated fixes using Rector
Updates test suites for compatibility

PHP Version Upgrade

Usage: /laravel-agent:migrate:from-legacy php-8.1 php-8.3

Modernizes your codebase to use newer PHP features:

Updates composer.json PHP version requirement
Adopts new language features (enums, attributes, etc.)
Fixes deprecated functions and syntax
Adds modern type declarations (union types, mixed, etc.)
Updates code style to leverage new syntax

Framework Migration

Usage: /laravel-agent:migrate:from-legacy symfony

Converts applications from other PHP frameworks to Laravel:

Maps framework concepts (routing, middleware, ORM)
Converts controllers and request handlers
Migrates models/entities to Eloquent
Converts views/templates to Blade
Migrates services and dependency injection
Adapts authentication and authorization

Database Migration

Usage: /laravel-agent:migrate:from-legacy database mysql postgres

Safely migrates between different database systems:

Analyzes schema differences and compatibility
Creates migration scripts with proper data types
Handles data type conversions (JSON, arrays, enums)
Migrates data safely with validation
Updates Eloquent models and queries
Tests data integrity after migration

Example: Laravel Version Upgrade

Upgrading from Laravel 10 to Laravel 11:

/laravel-agent:migrate:from-legacy laravel-10 laravel-11

The command will:

Analyze your current Laravel 10 installation
Review breaking changes in Laravel 11
Update composer dependencies
Migrate configuration files
Update deprecated method calls
Run automated code fixes
Execute test suite to verify compatibility
Provide a report with any manual steps needed

Example: Framework Migration

Migrating a Symfony application to Laravel:

/laravel-agent:migrate:from-legacy symfony

The migration includes:

Routes: Converts Symfony routes to Laravel routes
Controllers: Adapts controllers to use Laravel's base controller
ORM: Migrates Doctrine entities to Eloquent models
Templates: Converts Twig templates to Blade
Services: Maps Symfony services to Laravel service providers
Forms: Converts Symfony forms to Laravel validation

Validation and Testing

After migration, the command automatically validates the changes:

# Run test suite
vendor/bin/pest

# Static analysis
vendor/bin/phpstan analyse

# Code style check
vendor/bin/pint --test

Best Practices

Commit before migrating - Ensure a clean git state before starting
Review breaking changes - Check upgrade guides for your target version
Test thoroughly - Run your full test suite after migration
Update dependencies - Check third-party packages for compatibility
Review manual steps - Some changes require manual intervention
Test in staging first - Never migrate production directly

Common Issues and Solutions

Issue	Solution
Deprecated method calls	The command automatically updates to current APIs
Incompatible packages	Reports packages needing manual updates or alternatives
Configuration changes	Merges new config while preserving custom values
Breaking API changes	Identifies affected code and suggests fixes
Database schema changes	Creates migration files for required changes

Output Example

After running the migration command, you'll receive a detailed report:

## Migration: Laravel 10 → Laravel 11

### Analysis
- Current state: Laravel 10.48.0, PHP 8.2
- Breaking changes: 12 identified
- Estimated effort: 2-3 hours
- Compatibility: All packages compatible

### Steps Completed
- [x] Dependencies updated in composer.json
- [x] Config files migrated to new structure
- [x] Deprecated methods fixed (18 occurrences)
- [x] Service providers updated
- [x] Tests passing (145/145)

### Manual Steps Required
1. Review new rate limiting changes in routes/api.php
2. Update custom middleware to use new signature
3. Test email sending with updated mail config

### Validation
All automated tests passed. Run the following for additional checks:
```bash
vendor/bin/pest
vendor/bin/phpstan analyse
vendor/bin/pint
```

### Next Steps
1. Test application functionality in development
2. Review the Laravel 11 upgrade guide for additional changes
3. Deploy to staging for integration testing