The Complete Enterprise Migration Guide: Upgrading Core PHP Infrastructure directly to Laravel 11

Assessing Legacy PHP Monoliths for Laravel 11 Replatforming

Migrating a mature, enterprise-grade PHP monolith to a modern framework like Laravel 11 is a significant undertaking. It’s not merely a version upgrade; it’s a strategic replatforming initiative. The first critical step is a thorough architectural assessment of the existing monolith. This involves identifying core functionalities, dependencies, data models, and critical business logic. We need to understand the “what” and “how” of the current system before we can plan the “to where” and “to what.”

Key areas to scrutinize include:

• Core Business Logic: Map out the primary workflows and business rules. These are the heart of the application and must be meticulously translated.
• Data Access Layer: Analyze how data is persisted and retrieved. Understand ORM usage (if any), direct SQL queries, stored procedures, and data validation mechanisms.
• Authentication and Authorization: Document the current security model. This includes user registration, login flows, session management, and role-based access control (RBAC).
• Third-Party Integrations: List all external services, APIs, and libraries the monolith interacts with.
• Background Jobs and Queues: Identify any asynchronous processing, scheduled tasks, or message queue implementations.
• Frontend/Backend Coupling: Assess the degree of tight coupling between the backend logic and the presentation layer.
• Configuration Management: How are environment-specific settings handled?
• Testing Strategy: What is the current state of unit, integration, and end-to-end tests?

A common pitfall is attempting a “big bang” rewrite. For enterprise systems, a phased, incremental migration is almost always the superior strategy. This minimizes risk, allows for continuous delivery of value, and provides opportunities to validate the new architecture with production traffic.

Strategic Phased Migration: The Strangler Fig Pattern

The Strangler Fig pattern is our architectural blueprint for this migration. We’ll gradually replace pieces of the monolith with new Laravel 11 services, routing traffic to the new services as they become ready. An API Gateway or a sophisticated reverse proxy (like Nginx or HAProxy) will be instrumental in directing traffic between the legacy system and the new Laravel 11 components.

The process typically looks like this:

• Identify a Candidate Module: Start with a relatively self-contained feature or domain.
• Build the New Service: Develop this module as a distinct Laravel 11 application (or a set of microservices if the complexity warrants).
• Introduce a Facade/Proxy: Implement a routing layer that intercepts requests for the target module. Initially, it forwards all requests to the legacy monolith.
• Redirect Traffic: Once the new service is ready and tested, configure the facade to route requests for that module to the new Laravel 11 service.
• Iterate: Repeat the process for other modules.
• Decommission: Eventually, the legacy monolith will be “strangled” as all its functionality is migrated.

Setting Up the Laravel 11 Development Environment

Laravel 11 introduces significant changes, including a streamlined directory structure and a focus on modern PHP features. Ensure your development environment meets the prerequisites.

Prerequisites:

• PHP 8.2+
• Composer 2.5+
• Database: MySQL 8.0+, PostgreSQL 14+, SQLite 3.38+, SQL Server 2019+
• Redis (for caching and queues)
• Docker (highly recommended for consistent environments)

Project Initialization:

Create a new Laravel 11 project. Note the absence of the `public/` directory in the root; the application’s entry point is now `public/index.php` within the project root, and the web server’s document root should point directly to the project root.

Using Composer:

composer create-project laravel/laravel my-laravel-app
cd my-laravel-app
php artisan serve

Alternatively, using Docker and Sail:

curl -s https://laravel.build/my-laravel-app | bash
cd my-laravel-app
./vendor/bin/sail up -d

Directory Structure (Laravel 11):

my-laravel-app/
├── artisan
├── bootstrap/
├── config/
├── database/
├── public/  <-- Web server document root should point here in older Laravel versions, but now it's the project root.
├── resources/
├── routes/
├── storage/
├── tests/
├── vendor/
├── .env
├── composer.json
├── package.json
└── vite.config.js

The key change is that the web server’s document root should now point to the project’s root directory, not `public/`. The `public/index.php` file remains the entry point.

Data Migration Strategy: From Legacy DB to Eloquent Models

This is often the most complex part. We need a robust strategy for migrating data without downtime or corruption. Depending on the size and complexity of the database, this could involve:

1. Schema Conversion:

If the legacy system uses a different database or a significantly different schema, you’ll need to map and transform it. Laravel’s migration system is ideal for defining and evolving the new schema.

// Example: database/migrations/YYYY_MM_DD_HHMMSS_create_users_table.php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamp('email_verified_at')->nullable();
            $table->string('password');
            $table->rememberToken();
            $table->timestamps(); // created_at, updated_at
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('users');
    }
};

2. Data Extraction, Transformation, Load (ETL):

For large datasets or complex transformations, custom ETL scripts are necessary. These can be written in PHP, Python, or using specialized ETL tools. The goal is to extract data from the legacy database, transform it to match the new schema and data types, and load it into the new database.

// Example: A simple PHP script for data migration (run via CLI)
// This is a simplified example. Real-world scenarios require robust error handling, batching, and validation.

require __DIR__.'/vendor/autoload.php';

use App\Models\LegacyUser; // Assume this model points to the old DB connection
use App\Models\User;       // This is the new Laravel 11 User model

// Configure database connections in config/database.php
// 'legacy' => [ ... ],
// 'mysql'  => [ ... ],

$legacyUsers = LegacyUser::on('legacy')->get();

foreach ($legacyUsers as $legacyUser) {
    try {
        User::on('mysql')->create([
            'id' => $legacyUser->id, // Be cautious with ID mapping if not 1:1
            'name' => $legacyUser->full_name, // Example transformation
            'email' => $legacyUser->email_address, // Example transformation
            'password' => Hash::make($legacyUser->plain_password), // Example transformation
            'created_at' => $legacyUser->creation_date,
            'updated_at' => $legacyUser->last_modified_date,
        ]);
        echo "Migrated user: {$legacyUser->id}\n";
    } catch (\Exception $e) {
        echo "Error migrating user {$legacyUser->id}: " . $e->getMessage() . "\n";
        // Implement retry logic or logging
    }
}

echo "Data migration complete.\n";

3. Incremental Synchronization (for zero downtime):

For critical systems requiring zero downtime, a multi-stage approach is needed:

• Perform an initial bulk data load.
• Implement a mechanism (e.g., database triggers, change data capture (CDC) tools like Debezium, or application-level logging) to capture changes made to the legacy database *after* the initial load.
• Apply these changes to the new database in near real-time.
• Once the new system is stable and validated, perform a final cutover.

Rebuilding Core Functionality with Laravel 11 Components

This is where the Strangler Fig pattern truly comes into play. We’ll break down the monolith’s features into manageable services, each developed as a distinct Laravel 11 application or module.

Example: Migrating User Authentication

The `User` model and authentication logic are fundamental. Laravel 11’s built-in authentication scaffolding (using Jetstream or Breeze) provides a solid starting point. If your legacy system has a custom authentication mechanism, you’ll need to replicate its logic.

// Example: app/Http/Controllers/Auth/LoginController.php (simplified)
namespace App\Http\Controllers\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Validation\ValidationException;

class LoginController extends Controller
{
    public function showLoginForm()
    {
        return view('auth.login');
    }

    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        // Attempt to authenticate using the 'web' guard
        if (Auth::attempt($request->only('email', 'password'), $request->filled('remember'))) {
            // Authentication passed...
            $request->session()->regenerate();
            return redirect()->intended('/dashboard'); // Redirect to intended page
        }

        // Authentication failed...
        throw ValidationException::withMessages([
            'email' => [trans('auth.failed')],
        ]);
    }

    public function logout(Request $request)
    {
        Auth::logout();
        $request->session()->invalidate();
        $request->session()->regenerateToken();
        return redirect('/login');
    }
}

Example: Migrating a Core Business Service (e.g., Order Processing)

This service might involve:

• New Eloquent Models for `Order`, `OrderItem`, `Product`.
• Service classes to encapsulate business logic (e.g., `OrderService`).
• API routes for external systems or the facade to interact with.
• Event listeners for order status changes.
• Queue jobs for asynchronous tasks like sending notifications or processing payments.

// Example: app/Services/OrderService.php
namespace App\Services;

use App\Models\Order;
use App\Models\User;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use App\Events\OrderPlaced;

class OrderService
{
    public function placeOrder(User $user, array $items): Order
    {
        DB::beginTransaction();
        try {
            $order = Order::create([
                'user_id' => $user->id,
                'status' => 'pending',
                // ... other order details
            ]);

            foreach ($items as $item) {
                $order->items()->create([
                    'product_id' => $item['product_id'],
                    'quantity' => $item['quantity'],
                    'price' => $item['price'],
                ]);
                // Potentially decrease product stock here
            }

            event(new OrderPlaced($order)); // Dispatch an event

            DB::commit();
            return $order;
        } catch (\Exception $e) {
            DB::rollBack();
            Log::error("Failed to place order for user {$user->id}: " . $e->getMessage());
            throw $e; // Re-throw to be handled by the controller or caller
        }
    }

    // ... other methods like updateOrderStatus, cancelOrder, etc.
}

// Example: routes/api.php
use App\Http\Controllers\Api\OrderController;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->prefix('orders')->group(function () {
    Route::post('/', [OrderController::class, 'store']);
    Route::get('/{order}', [OrderController::class, 'show']);
    // ... other order routes
});

Implementing the Facade/API Gateway Layer

This layer is crucial for routing traffic. It can be implemented using:

• Nginx/HAProxy: Configure reverse proxy rules to direct specific URL paths or hostnames to either the legacy application or the new Laravel 11 services.
• Dedicated API Gateway: Solutions like Kong, Tyk, or AWS API Gateway can manage routing, authentication, rate limiting, and more.
• A Simple Laravel Application: A dedicated Laravel application can act as a facade, orchestrating calls to both the legacy system (via HTTP requests) and the new microservices.

Nginx Example Configuration:

# Assuming legacy app is on port 8000 and new Laravel app is on port 8080
# And the new 'orders' service is running as a separate Laravel app on port 8081

server {
    listen 80;
    server_name yourdomain.com;

    # Route /api/v1/orders requests to the new Laravel Orders service
    location /api/v1/orders {
        proxy_pass http://localhost:8081; # Assuming Orders service runs here
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Add any other necessary headers
    }

    # Route all other requests to the legacy application
    location / {
        proxy_pass http://localhost:8000; # Assuming legacy app runs here
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Add any other necessary headers
    }

    # If the new Laravel app is served directly on a subdomain
    # server {
    #     listen 80;
    #     server_name api.yourdomain.com;
    #     root /path/to/your/laravel/app/public; # Or project root for L11
    #     index index.php;
    #
    #     location / {
    #         try_files $uri $uri/ /index.php?$query_string;
    #     }
    #
    #     location ~ \.php$ {
    #         include snippets/fastcgi-php.conf;
    #         fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; # Adjust PHP version and path
    #     }
    # }
}

Testing and Deployment Strategy

A robust testing strategy is non-negotiable. For a phased migration:

• Unit Tests: Write comprehensive unit tests for all new Laravel 11 components (Models, Services, Controllers, Jobs, etc.).
• Integration Tests: Test the interaction between different Laravel components and external services.
• Contract Tests: If migrating to microservices, ensure that the APIs between services adhere to defined contracts.
• End-to-End (E2E) Tests: Use tools like Cypress or Playwright to simulate user flows, ensuring that traffic routed to new services behaves as expected.
• Performance Testing: Benchmark the new services under load to ensure they meet or exceed the performance of the legacy system.

Deployment:

Leverage CI/CD pipelines for automated testing and deployment. For the Strangler Fig pattern, the deployment process needs to be carefully orchestrated:

• Deploy the new Laravel 11 service to a staging environment.
• Run E2E tests against the staging environment, with the facade directing a small percentage of traffic to the new service.
• Gradually increase traffic to the new service in production.
• Monitor performance and error logs closely.
• Rollback mechanisms must be in place for immediate recovery if issues arise.

Consider blue-green deployments or canary releases for zero-downtime rollouts of new services.

Post-Migration: Optimization and Cloud Replatforming

Once core functionalities are migrated to Laravel 11, the focus shifts to optimization and leveraging cloud-native capabilities. This is the “replatforming” aspect.

Containerization: Package each Laravel 11 service (or the entire application if not microservices) into Docker containers. This ensures consistency across environments and simplifies deployment.

# Example Dockerfile for a Laravel 11 application
FROM php:8.2-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    acl \
    supervisor \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd pdo pdo_mysql zip exif pcntl bcmath opcache \
    && pecl install redis \
    && docker-php-ext-enable redis

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www/html

# Copy application files
COPY . .

# Install Composer dependencies
RUN composer install --no-dev --optimize-autoloader --no-interaction

# Copy Nginx configuration
COPY docker/nginx/default.conf /etc/nginx/sites-available/default

# Copy Supervisor configuration
COPY docker/supervisor/supervisord.conf /etc/supervisor/conf.d/supervisord.conf

# Expose port
EXPOSE 80

# Start services
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"]

Orchestration: Deploy containers using Kubernetes, AWS ECS, or similar orchestration platforms. This provides scalability, self-healing, and efficient resource management.

Managed Services: Migrate databases to managed services (e.g., AWS RDS, Google Cloud SQL). Leverage managed caching (Redis/Memcached) and message queues (SQS, RabbitMQ). This offloads operational burden.

Serverless Components: For specific, event-driven tasks, consider AWS Lambda or Google Cloud Functions. Laravel Vapor is an excellent platform for deploying Laravel applications to serverless environments.

Monitoring and Logging: Implement robust monitoring (Prometheus, Grafana, Datadog) and centralized logging (ELK stack, Splunk) to gain visibility into the distributed system’s health and performance.

This comprehensive approach ensures that the migration to Laravel 11 is not just a technology upgrade but a strategic move towards a more scalable, maintainable, and cloud-native architecture.