Vengala Vinay

Having 9+ Years of Experience in Software Development

Home » Migrating from Core PHP to Laravel 11: A Zero-Downtime Technical Playbook

Migrating from Core PHP to Laravel 11: A Zero-Downtime Technical Playbook

Phase 1: Pre-Migration Assessment and Environment Setup

Before embarking on a zero-downtime migration from a legacy Core PHP application to Laravel 11, a rigorous assessment of the existing codebase and infrastructure is paramount. This phase focuses on understanding the current architecture, identifying critical components, and establishing a parallel development and testing environment for Laravel.

1. Codebase Analysis and Dependency Mapping

The first step is a deep dive into the Core PHP application. This involves:

  • Functionality Inventory: Document every significant feature, user flow, and business logic implemented in the Core PHP app. Tools like static analysis (e.g., PHPStan, Psalm) can help identify dead code and complex areas.
  • Database Schema Review: Analyze the existing database schema. Identify tables, relationships, stored procedures, and triggers. Understand data types and potential migration challenges (e.g., legacy data formats).
  • External Integrations: Catalog all third-party APIs, services, and libraries the application interacts with. Note their endpoints, authentication methods, and data formats.
  • Configuration Management: Document all configuration files, environment variables, and hardcoded settings.
  • Session Management: Understand how user sessions are managed (e.g., file-based, database, Redis). This is crucial for maintaining user state during the transition.

2. Establishing the Laravel 11 Development Environment

Set up a dedicated environment for the new Laravel application. This should mirror the production environment as closely as possible in terms of PHP version, web server, database, and caching mechanisms.

Ensure you are using a compatible PHP version for Laravel 11. As of its release, PHP 8.2 or higher is recommended.

2.1. Composer Dependencies

Initialize a new Laravel 11 project and begin adding necessary packages. Prioritize packages that directly replace or abstract Core PHP functionalities.

composer create-project laravel/laravel core-php-migration-laravel
cd core-php-migration-laravel
composer require --dev phpstan/phpstan laravel/pint
# Add other essential packages based on your analysis
# e.g., for authentication, API interaction, etc.

2.2. Database Setup and Schema Migration

Laravel’s Eloquent ORM and Migrations are key. You’ll need to translate your existing database schema into Laravel migration files. This is often an iterative process.

php artisan make:migration create_users_table --create=users
php artisan make:migration create_products_table --create=products
# ... and so on for all your tables

Manually translate the SQL DDL from your Core PHP application into the schema builder syntax within these migration files. For complex data types or constraints, consult the Laravel Migrations documentation.

3. Version Control Strategy

Implement a robust branching strategy. A common approach for this type of migration is to use a dedicated `migration` branch or feature branches for specific modules being refactored.

git checkout -b migration-phase-1
# ... commit your initial Laravel setup and migration files

Phase 2: Incremental Refactoring and Parallel Execution

The core of a zero-downtime migration lies in an incremental approach. Instead of a big bang rewrite, we refactor modules one by one, allowing both the old and new systems to coexist and serve traffic.

1. Module-by-Module Refactoring

Identify independent modules or features in the Core PHP application that can be refactored into Laravel components. Start with less critical or simpler modules to build confidence and refine the process.

1.1. Routing and Controller Logic

For a given module, replicate its routing and controller logic in Laravel. This involves mapping old URLs to new Laravel routes and translating the PHP logic into controllers.

// routes/web.php (Laravel)
use App\Http\Controllers\LegacyModuleController;

Route::get('/legacy/users', [LegacyModuleController::class, 'listUsers']);
Route::post('/legacy/users', [LegacyModuleController::class, 'createUser']);

// app/Http/Controllers/LegacyModuleController.php (Laravel)
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User; // Assuming User model is created

class LegacyModuleController extends Controller
{
    public function listUsers()
    {
        // Translate Core PHP logic to fetch users
        // Example: $users = DB::connection('legacy_db')->table('old_users')->get();
        $users = User::all(); // Using Eloquent for the new schema
        return view('legacy.users.list', ['users' => $users]);
    }

    public function createUser(Request $request)
    {
        // Translate Core PHP logic to create a user
        $user = User::create($request->all());
        return redirect()->route('legacy.users.list');
    }
}

1.2. Data Access Layer Abstraction

If the Core PHP app uses direct SQL queries or a custom data access layer, abstract this into Laravel’s Eloquent ORM or Query Builder. For modules that still need to interact with the legacy database directly during the transition, configure a secondary database connection.

// config/database.php
'connections' => [
    // ... default connection
    'legacy_db' => [
        'driver' => 'mysql',
        'host' => env('LEGACY_DB_HOST', '127.0.0.1'),
        'port' => env('LEGACY_DB_PORT', '3306'),
        'database' => env('LEGACY_DB_DATABASE', 'forge'),
        'username' => env('LEGACY_DB_USERNAME', 'forge'),
        'password' => env('LEGACY_DB_PASSWORD', ''),
        'unix_socket' => env('LEGACY_DB_SOCKET', ''),
        'charset' => 'utf8mb4',
        'prefix' => '',
        'prefix_indexes' => true,
        'strict' => true,
        'engine' => null,
    ],
],

// app/Http/Controllers/LegacyModuleController.php (continued)
use Illuminate\Support\Facades\DB;

public function listLegacyUsers()
{
    $users = DB::connection('legacy_db')->table('old_users')->get();
    return view('legacy.users.list_legacy', ['users' => $users]);
}

2. Implementing a Proxy or API Gateway

To serve traffic to both applications concurrently and seamlessly switch over, a reverse proxy is essential. Nginx is a common and performant choice.

2.1. Nginx Configuration for Dual Application Serving

Configure Nginx to route traffic based on URL paths or headers. Initially, all traffic might go to the Core PHP app. As modules are refactored, specific paths will be routed to the Laravel application.

# /etc/nginx/sites-available/your_app.conf

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/core-php-app/public; # Default to Core PHP

    # Route specific paths to Laravel
    location /legacy/users {
        alias /var/www/core-php-migration-laravel/public;
        try_files $uri $uri/ /index.php?$query_string;

        # Proxy to Laravel's PHP-FPM
        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; # Adjust PHP version
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
        }
    }

    # Other Core PHP locations or general proxying
    location / {
        # Default to Core PHP index.php or similar
        try_files $uri $uri/ /index.php?$query_string;
        # ... Core PHP specific fastcgi_pass if needed
    }

    # ... other configurations (SSL, logs, etc.)
}

After modifying Nginx configuration, test and reload:

sudo nginx -t
sudo systemctl reload nginx

3. Data Synchronization Strategy

During the parallel execution phase, data written to the legacy database by the Core PHP app must be reflected in the new Laravel database (or vice-versa, depending on the migration direction). This is the most complex part of zero-downtime migration.

3.1. Dual Writes (Application Level)

For critical write operations, modify the Core PHP application (or the refactored Laravel module) to write to *both* databases. This requires careful transaction management.

// Example: In a refactored Laravel controller handling user creation
use Illuminate\Support\Facades\DB;
use App\Models\User;

// ... inside createUser method

// Start transaction for Laravel DB
DB::beginTransaction();
try {
    $newUser = User::create($request->all()); // Write to new DB

    // Write to legacy DB using the secondary connection
    DB::connection('legacy_db')->table('old_users')->insert([
        'username' => $request->input('username'),
        'email' => $request->input('email'),
        // ... other fields
    ]);

    DB::commit(); // Commit both if successful
    return redirect()->route('legacy.users.list');

} catch (\Exception $e) {
    DB::rollBack(); // Rollback both if any error occurs
    // Log error, return error response
    return back()->withError('Failed to create user.');
}

3.2. Database Replication (Recommended for Large Scale)

For more robust data synchronization, especially with high write volumes, leverage database replication. Set up the legacy database as a master and the new Laravel database as a replica. This is a one-way sync from legacy to new.

Caveats:

  • Replication latency can be an issue.
  • Schema differences must be managed carefully.
  • Writes to the new database during the transition period (before cutover) need to be handled via dual writes or other mechanisms.

4. Session Management and Authentication

This is a critical point for zero-downtime. Users must remain logged in as traffic is routed to Laravel. Options include:

  • Shared Session Storage: If both applications can access a common session store (e.g., Redis, Memcached, database), this simplifies the transition.
  • Token-Based Authentication: Migrate to JWT or OAuth. The proxy can validate tokens issued by either system, or the Laravel app can validate tokens issued by the legacy system.
  • Phased Authentication Migration: Initially, the Laravel app might rely on the legacy session mechanism (e.g., by reading session files or querying the legacy session table). Once a module is fully migrated, update the authentication logic to use Laravel’s native system.

Phase 3: Cutover and Post-Migration Optimization

This phase involves the final switch and ensuring the new Laravel application is stable and performant.

1. Final Data Synchronization and Verification

Before the cutover, ensure all data is synchronized. Perform a final data diff between the legacy and new databases for critical tables. Run automated scripts to verify data integrity.

2. Traffic Shifting (Blue/Green or Canary Deployment)

Use the Nginx proxy to gradually shift traffic. This can be done by:

  • Canary Release: Route a small percentage of traffic (e.g., 1%, 5%) to the Laravel application. Monitor for errors and performance issues. Gradually increase the percentage.
  • Blue/Green Deployment: Have two identical production environments. Route all traffic to the “blue” (legacy) environment. Deploy the fully migrated Laravel app to the “green” environment. Perform final tests on “green.” When ready, switch the load balancer/proxy to direct all traffic to “green.” This allows for an instant rollback if issues arise.

Nginx can be configured to route based on headers or cookies for more granular control during canary releases.

# Example Nginx for Canary Release (simplified)
http {
    # ... other settings

    map $http_x_canary $canary_backend {
        default "core_php_backend";
        "true" "laravel_backend";
    }

    upstream core_php_backend {
        server 127.0.0.1:8080; # Assuming Core PHP runs on a different port
    }

    upstream laravel_backend {
        server unix:/var/run/php/php8.2-fpm.sock; # Or a separate PHP-FPM pool
        # If Laravel is served via a separate web server or load balancer
        # server laravel.internal.domain:80;
    }

    server {
        listen 80;
        server_name yourdomain.com;

        location / {
            proxy_pass http://$canary_backend;
            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;
        }
    }
}

To enable canary for a specific user/session, you might set a cookie or pass a custom header.

3. Disabling Legacy Components

Once 100% of traffic is successfully served by Laravel and stability is confirmed over a period (e.g., 24-72 hours), begin disabling and eventually removing the Core PHP application components. This includes:

  • Updating Nginx configuration to remove routes pointing to the Core PHP app.
  • Decommissioning the Core PHP application server(s).
  • Removing dual-write logic from the Laravel application.
  • Cleaning up legacy database tables if they are no longer needed.

4. Performance Tuning and Monitoring

After the migration, continuously monitor the Laravel application’s performance. Utilize Laravel’s built-in tools and external services:

  • Laravel Telescope/Horizon: For debugging, performance monitoring, and queue management.
  • APM Tools: New Relic, Datadog, Sentry for real-time performance metrics and error tracking.
  • Database Optimization: Analyze slow queries using `EXPLAIN` and optimize Eloquent queries.
  • Caching Strategies: Implement robust caching for frequently accessed data.
  • Queue Optimization: Offload long-running tasks to queues.

This systematic, incremental approach, coupled with robust infrastructure and careful data management, is key to achieving a zero-downtime migration from Core PHP to Laravel 11.