Laravel6 to 9 Upgrade: Common Pitfalls and How to Avoid Them

For those of you who have been using Laravel for many years, this time I will introduce the specific steps to upgrade from Laravel6 to Laravel9.

Upgrading offers many benefits, such as access to new features, enhanced security, and continued long-term support. Now, let’s move on to the steps.

Prerequisites

• PHP version must be 8.0 or higher
• Your current Laravel6 application must be running properly
• You must have backups of your database and application

Advantages and Disadvantages

Upgrading has the following advantages and disadvantages.

Advantages

• Access to the latest security measures and bug fixes
• Improved performance and additional new features
• Long-term support and community support

Disadvantages

• Code modifications may be required due to compatibility issues
• The upgrade process requires time and resources

Step 1: Prepare Backups

First, take a complete backup of your current application and database. This is extremely important in case any issues arise.

Step 2: Update the Environment

Laravel9 requires PHP 8.0 or higher. Check your server’s PHP version and upgrade if necessary. Also, make sure to install any required PHP extensions.

Step 3: Update composer.json

This step took quite a bit of time.

Open your project’s composer.json file and change the Laravel version in the require section to “9.*”. Also, verify that other packages are compatible with Laravel9 and update their versions if necessary.

Editing the composer.json file is one of the most important steps when upgrading the Laravel version.

Below is an explanation of how to edit the composer.json file when upgrading from Laravel6 to Laravel9.

Open the composer.json File

First, open the composer.json file located in the root directory of your project using a text editor.

Update the Laravel Version

Find the require section and change the version of laravel/framework from the current 6.x to 9.*. For example:

"require": {
    "php": "^8.0",
    "laravel/framework": "9.*",
    // Other dependencies...
},

Check the PHP Version

Laravel9 requires PHP 8.0 or higher. Make sure the PHP version specified in the require section of composer.json is set appropriately. For example, specify it as “php”: “^8.0”.

Check Other Dependencies

Ensure that other packages (for example, fideloper/proxy and laravel/tinker) are updated to versions compatible with Laravel9, and update them if necessary.

Edit the composer.json File

Laravel6 composer.json File

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The Laravel Framework.",
    "keywords": [
        "framework",
        "laravel"
    ],
    "license": "MIT",
    "require": {
        "php": "^7.2.5|^8.0",
        "fideloper/proxy": "^4.4",
        "laravel/framework": "^6.20",
        "laravel/tinker": "^2.5",
        "maatwebsite/excel": "^3.1"
    },
    "require-dev": {
        "facade/ignition": "^1.16.4",
        "fakerphp/faker": "^1.9.1",
        "laravel/ui": "^1.0",
        "mockery/mockery": "^1.0",
        "nunomaduro/collision": "^3.0",
        "phpunit/phpunit": "^8.5.8|^9.3.3"
    },

    // Other entries...
}

composer.json File After Updating to Laravel9

{
    "name": "laravel/laravel",
    "type": "project",
    "description": "The Laravel Framework.",
    "keywords": [
        "framework",
        "laravel"
    ],
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "fideloper/proxy": "^4.4",
        "laravel/framework": "^9.0",
        "laravel/tinker": "^2.5",
        "maatwebsite/excel": "^3.1"
    },
    "require-dev": {
        "spatie/laravel-ignition": "^1.0",
        "fakerphp/faker": "^1.9.1",
        "laravel/ui": "^3.4",
        "mockery/mockery": "^1.4.4",
        "nunomaduro/collision": "^6.1",
        "phpunit/phpunit": "^9.5.10"
    },

    // Other entries...
}

Save Changes and Update Dependencies

After saving the changes, navigate to the root directory of your project in the command line and run the following command to update dependencies:

composer update

Check and Resolve Errors

If an error occurs while running composer update, carefully read the error message and make additional corrections as needed. This may include updating incompatible packages or locking specific package versions.

Editing composer.json and updating dependencies are extremely important when upgrading the Laravel version. By doing this accurately, the upgrade process will proceed smoothly. Also, when upgrading, always remember to take backups and thoroughly test in the development environment.

Step 4: Modify and Fix Code

Refer to the Laravel upgrade guide and make the necessary code changes. Pay special attention to areas that have changed in Laravel9, such as routing, middleware, and models.

Modifying the app/Exceptions/Handler.php File

Before Modification

namespace App\Exceptions;

use Exception;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    protected $dontReport = [
        //
    ];

    protected $dontFlash = [
        'password',
        'password_confirmation',
    ];

    public function report(Exception $exception)
    {
        parent::report($exception);
    }

    public function render($request, Exception $exception)
    {
        return parent::render($request, $exception);
    }
}

After Modification

namespace App\Exceptions;

use Throwable;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    protected $dontReport = [
        //
    ];

    protected $dontFlash = [
        'password',
        'password_confirmation',
    ];

    public function report(Throwable $exception)
    {
        parent::report($exception);
    }

    public function render($request, Throwable $exception)
    {
        return parent::render($request, $exception);
    }
}

Modifying the app/Http/Middleware/TrustProxies.php File

Before Modification

namespace App\Http\Middleware;

use Fideloper\Proxy\TrustProxies as Middleware;
use Illuminate\Http\Request;

class TrustProxies extends Middleware
{
    protected $proxies="**";

    protected $headers = Request::HEADER_X_FORWARDED_ALL;
}

After Modification

namespace App\Http\Middleware;

use Fideloper\Proxy\TrustProxies as Middleware;
use Illuminate\Http\Request;

class TrustProxies extends Middleware
{
    protected $proxies="**";

    //protected $headers = Request::HEADER_X_FORWARDED_ALL;
    protected $headers =
        Request::HEADER_X_FORWARDED_FOR |
        Request::HEADER_X_FORWARDED_HOST |
        Request::HEADER_X_FORWARDED_PORT |
        Request::HEADER_X_FORWARDED_PROTO |
        Request::HEADER_X_FORWARDED_AWS_ELB;
}

Step 5: Test the Application

After upgrading, thoroughly test whether the application works correctly. If any issues are found, fix them and test again.

Important Notes

• Thorough testing in the development environment is essential.
• Ensure that third-party packages are compatible with Laravel9.
• It is recommended to test in a staging environment before deploying to production.

Conclusion

Upgrading from Laravel6 to Laravel9 is a process that takes some time, but it is extremely worthwhile to benefit from improved stability, security, and new features. I hope this guide is helpful. Good luck!

※If you use this as a reference, please do so at your own risk.