Laravel 5.1 to 12 Upgrade: PART 1

Upgrading one of my client's old Laravel projects can feel like untangling a decade-old web of code—especially when jumping from Laravel 5.1 to 12. A direct upgrade seemed nearly impossible with so many breaking changes, outdated dependencies, and new architectural patterns.

At first, I considered upgrading step by step through each version, but that approach would have been time-consuming and error-prone. Instead, I discovered a more efficient method that saved time and reduced the complexity of fixing many errors.

Curious about how I pulled it off? Let’s dive into the smartest way to migrate from Laravel 5.1 to 12 without breaking everything!

Hey Artisans! It’s Worth Upgrading to Laravel 12 – Here’s Why

Sticking with Laravel 5.1 is making me uncomfortable in terms of security and performance, and it’s holding the application back.

Security First!

When considering the development of an application, security is the priority. Laravel 5.1 is no longer supported, meaning zero security updates. Running an old version is like leaving your front door wide open—upgrading keeps your app secure and future-proof

Modern Development

Compared to 5.1 to 12 - a lot of game-changing features are available in version 12 - blade components, query caching, and better improvement in Eloquent features.

PHP 8+ Compatibility

Laravel 5.1 runs on PHP 5.5, which is practically ancient. Laravel 12 takes full advantage of PHP 8+, bringing better performance, type safety, and modern features.

🔄 No More Upgrade Nightmares – Avoid the Pain of Version-by-Version Torture!

The longer you wait, the harder it gets. Upgrading in small steps (5.1 → 5.5 → 6 → … → 12) is painful. Instead, I took a different route—I started fresh with Laravel 12 and migrated my project piece by piece. Spoiler alert: It saved me tons of time and headaches!

Many of the packages you relied on in Laravel 5.1 are now deprecated or no longer maintained. Instead of forcing outdated solutions to work, it's smarter to find modern, well-supported alternatives that align with Laravel 12’s ecosystem. Choosing the right replacements ensures better security, performance, and long-term support, saving you from future upgrade nightmares.

Here’s a detailed table outlining the prerequisites required to upgrade from Laravel 5.1 to Laravel 12.

---

Prerequisites for Upgrading Laravel 5.1 to Laravel 12

---

This table ensures clarity by listing the changes in Laravel 5.1 vs. Laravel 12.

Steps to Upgrade from Laravel 5.1 to Laravel 12

Since upgrading Laravel step by step from 5.1 to 12 is time-consuming and can introduce many breaking changes, the best approach is to create a fresh Laravel 12 project and migrate your old project files into it while fixing compatibility issues. Here’s how to do it:

Step 1: Backup Your Old Laravel 5.1 Project

Before making any changes, create a full backup of your existing project.

Step 2: Install Laravel 12 in a New Directory

To get a clean Laravel 12 installation, run:

composer create-project laravel/laravel project_name

Navigate into the new project directory:

cd project_name

Step 3: Configure New Laravel 12 Project

Copy the .env file from your Laravel 5.1 project and update it in the new Laravel 12 project:

cp /path/to/old_project/.env .env

Update the database credentials inside .env to match your existing database.

Step 4: Run the application in version 12:

After the installation in version 12, execute the command

php artisan serve

otherwise, configure it in Nginx or Apache to run.

After the Successful check, the application is working properly with a welcome page without any errors.

Step 5: Migrate Your Old Codebase

🎉 Congratulations! Your Laravel 12 Project is Live... But Hold On!

You might be tempted to throw all your old files into the new project at once—DON’T DO IT!

Laravel 12 has a different directory structure, so dumping everything in without a plan will only lead to "White Screen of Death" nightmares.

Instead, follow this error-proof migration order to avoid breaking the welcome page:

• Move Your Models First – Laravel 12 keeps models inside app/Models. If yours are still chilling in app/, give them a new place

• Bring in Your Controllers - Place them inside app/Http/Controllers/, and don’t forget to update namespaces to App\Http\Controllers;

• Routes Come Next – Laravel 5.1 had a single routes.php file, but Laravel 12 has routes/web.php and routes/api.php. Split them accordingly. Also, initially, comment all your routes other than the welcome page route endpoint

• Migrate Your Views – Drop your Blade templates into resources/views/, but watch out for deprecated Blade syntax changes!

• Config & Middleware – Copy over necessary config files from config/ and move your middleware into app/Http/Middleware/

Composer & Migrations – Run composer install, php artisan migrate, and clear cache (php artisan cache:clear) to make sure everything is running smoothly.

Now, refresh your browser… and BAM! Your Laravel 12 app is alive without a single “Whoops” error!

Now, the welcome page only shows the need to fix the issues one by one based on version upgrade changes in version 12 of every class.

Change the key in .env in Laravel for Cache Config

In the upgrade process, the first change is that we are updating the key name for the default cache configuration

# laravel 5.1
CACHE_DRIVER =file

# laravel v12.0
CACHE_STORE = file

This is an example of changes based on your need change the cache store management also do the changes in cache.php config folder.

Route Config Changes in Laravel 12

• In Laravel 5.1, the routes are added routes.php and loaded via RouteServiceProvider.php
  But in the new version, you only need to do the changes for the version 12 requirement.

• In Laravel 12, there is no more RouteServiceProvider.php Some of the defining method changes need to be done in your laravel version 5.1 migrated file in the web.php

If your application is Web, add the routes in web.php If it is API, add the routes in api.php
by default web.php file will be in the config folder, but if you need to use the api.php file, you may install additional route files for API routes

php artisan install:api

load all your routes from the bootstrap/app.php like this

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        //
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

need to update your app.php file.

Middleware changes in Laravel 12

Middleware in Laravel acts like a security checkpoint for your application. It filters HTTP requests before they reach your controllers.

All the middleware moved app/Http/Middleware no artisan command is available 5.1 now it is available

php artisan make:middleware MiddlewareName

All the middleware is configured in the app.php file; the kernel.php is no longer in the project v-12

all the middlewares configured in laravel 5.1 now need to add in the app.php those are already configured.

If your custom middleware is available, add this in app.php file based on the need of web and api

use App\Http\Middleware\WebMiddleware;
use App\Http\Middleware\ApiMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->group('web', [
        WebMiddleware::class,
    ]);
    $middleware->group('api' [
        ApiMiddleware::class,
    ]);
})

If the custom middlewares are added with alias class, change it to this format

use App\Http\Middleware\AliasMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'alias' => AliasMiddleware::class
    ]);
})

Route Changes in Laravel 12

Route Definition Syntax Changes

Laravel 5.1:

Routes were defined in the app/Http/routes.php file.

Route::get('home', 'HomeController@index');

Laravel 12:

The routes/web.php and routes/api.php files are used instead.

use App\Http\Controllers\HomeController;
use Illuminate\Support\Facades\Route;

Route::get('home', [HomeController::class, 'index']);

Key Changes:

• No more routes.php (moved to web.php and api.php).

• Controllers must be referenced using ::class.

Middleware Application

Laravel 5.1:

Middleware was applied directly within the routes.php file like this:

Route::get('admin', ['middleware' => 'auth', 'uses' => 'AdminController@index']);

Laravel 12:

Middleware is applied using a cleaner syntax:

Route::middleware(['auth'])->group(function () {
    Route::get('admin', [AdminController::class, 'index']);
});

Key Changes:

• Middleware is applied using groups for better readability.

• The array syntax is no longer used.

API Routes & Versioning

Laravel 5.1:

API routes were mixed with web routes, leading to complexity.

Route::get('api/users', 'Api\UserController@index');

Laravel 12:

API routes are now defined separately in routes/api.php, and route versioning is recommended.

use App\Http\Controllers\Api\UserController;

Route::prefix('v1')->group(function () {
    Route::get('users', [UserController::class, 'index']);
});

Key Changes:

• routes/api.php separates API routes from web routes.

• Versioning (v1, v2) allows better API management.

• manage this versioning is easy in app.php configuration also.

Named Routes Syntax Changes

Laravel 5.1:

Named routes were defined using an array.

Route::get('profile', ['as' => 'profile', 'uses' => 'ProfileController@index']);

Laravel 12:

Named routes are now applied using name()

Route::get('profile', [ProfileController::class, 'index'])->name('profile');

Key Changes:

• No more array syntax name() is used instead.

Route Model Binding Enhancements

Laravel 5.1:

Manual fetching of models was required in controllers.

Route::get('user/{id}', function ($id) {
    return User::findOrFail($id);
});

Laravel 12:

Implicit Route Model Binding automatically fetches the model.

Route::get('user/{user}', function (User $user) {
    return $user;
});

Migration File Structure Changes

Updating an Existing Migration files the moved files from version 5.1 need to be upgraded as using anonymous class. This will avoid a naming collision

return new class extends Migration {
    public function up(): void {
        Schema::table('users', function (Blueprint $table) {
            $table->string('phone')->nullable();
        });
    }

    public function down(): void {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('phone');
        });
    }
};

File System Changes (config/filesystems.php)

Need to upgrade the default filesystem driver in .env and make the changes in composer.json

# composer.json
{
    "require": {
        "php": "^8.1",
        "laravel/framework": "^12.0",
        "guzzlehttp/guzzle": "^7.7",
        "league/flysystem": "^3.0", 
        "aws/aws-sdk-php": "^3.0"
    }
}

then run the command to update composer.json

Query Execution Changes

Old DB Facade Usage

In Laravel 5.1, the DB facade was commonly used like this:

use DB;

Laravel 12 (Modern DB Facade Usage)

use Illuminate\Support\Facades\DB;

Raw Queries Were More Prone to SQL Injection

#version 5.1
$users = DB::select("SELECT * FROM users WHERE email = '" . $email . "'");

Laravel 12: Uses Safer Parameter Binding

• Uses prepared statements to prevent SQL injection

$users = DB::select("SELECT * FROM users WHERE email = ?", [$email]);

search all over the place app()→envioronment() and replace it to config(‘app.env’)

Conclusion of Part 1: The Upgrade Journey Begins

Upgrading from Laravel 5.1 to Laravel 12 might seem like a massive leap, but taking the right approach makes all the difference. Instead of struggling with step-by-step version upgrades, we took a clean slate approach—setting up a fresh Laravel 12 project and migrating essential parts of the old application.

So far, we’ve covered why upgrading is worth it, prerequisites, project setup, and file migration strategies to ensure a smooth transition without unexpected errors. But the journey doesn’t end here!

In Part 2, I’ll dive deeper into the core changes you need to tackle, including models, Blade components, request handling, database modifications, and package deprecations—along with real-world challenges I faced (and how I solved them).

Stay tuned for the next phase of this Laravel upgrade adventure!

If you find any of them particularly novel or useful, feel free to share them with your Laravel developer friends and colleagues, and if you feel inclined to support my work, you can do so through BuyMeACoffee. Your support is greatly appreciated!

Important Links:

• Laravel Framework Repository: https://github.com/laravel/framework

• Laravel Documentation : v5.1 - https://laravel.com/docs/5.1

• Laravel Documentation : v12 - https://laravel.com/docs/12.x