Upgrading Laravel: An easy Step-by-Step Guide from 5.7 to 10.x

In this article, I'll detail my method for upgrading any Laravel application, regardless of its current version, to the most recent Laravel release. Throughout this blog, I'll be showcasing my approach by upgrading an older Laravel 5.7 application directly to Laravel 10.x. Instead of a step-by-step version-by-version upgrade, we'll be transitioning directly to the latest version from any starting point.

Step 1: Environment Setup

The first step of the upgrade is to set up your environment to run your application into 10.x (intended version). The requirement for the Laravel version 10 is PHP 8.1 and extensions specified in Laravel Server Requirement.

Step 2: Laravel ONLY Upgrade

I understand that your application currently has numerous packages installed. However, for the initial phase, we will focus solely on upgrading the default packages that are specified within the framework. To begin this process, please make a backup of the existing composer.json file by renaming it to composer.json.back. Additionally, remember to remove the composer.lock file.

Next, create a new composer.json file, and copy the content from Laravel 10.x branch from the GitHub repository into it. This composer.json file from Laravel's repository will serve as the base for our upgrade.

Add scripts and custom config to new composer.json file from the backup.

Step 3: Install Dependencies

composer install

Running composer install at this stage is expected to encounter errors. This is because we haven't yet defined any previous dependencies or followed any Laravel upgrade guides. However, this deliberate approach allows us to identify and address issues in an iterative manner.

At this stage, you will get errors mostly related to the framework itself. In my example above, the error is because of that the signature of the method report of the class App\Exceptions\Handler has been changed. The best way to deal with this is to visit Laravel's repository and Compare what has been changed between your current version to the Latest Laravel version. The changes can be accessed from the git differences in GitHub at https://github.com/laravel/laravel/compare/5.7...10.x

The total number of modified files is 93. But most of these files such as .editorconfig, .env.example, .gitattributes, .gitignore, etc. don't require any attention. Your version of these files should be replaced by the new version of itself. Nevertheless, certain files cannot be directly replaced with the new version, as your version may have undergone modifications. In such cases, merging is required by determining the differences between the Laravel-side changes and your own. An example of this merging scenario is seen in the App\Exceptions\Handler file, where custom logic for handling 403 error is added from my side and Laravel changed the signature of the report method.

Don't affraid with the number of files count. This is not complicated as it seems.

Step 4: Installing Remaining Dependencies

At this stage, we've successfully addressed the framework-related issues. However, it's possible that when running the composer install command, errors may still arise due to pending dependencies. Therefore, the next task is to install these remaining dependencies. To begin, let's compare the composer.json.back and the new composer.json files, as illustrated in the image below.

Install any additional dependencies that you have installed into your application. Make sure not to install any dependencies that have been removed by Laravel. Utilize the Git comparison above to identify which dependencies have been removed by Laravel.

In the required section, the fideloper/proxy package has been removed in between 5.x to 10.x. Therefore, there is no need to install it. All of your remaining dependencies can be installed with composer require command. In my example,

composer require aammui/role-permission ausi/slug-generator barryvdh/laravel-

Follow the same procedure for dev dependencies with composer requrie --dev flag.

Step 5: Final suggestion

There could be numerous dependencies, each demanding a careful review of their specific upgrade guides. Robust test cases are pivotal in verifying the successful implementation of upgrades and ensuring the system's proper functionality. Consulting Laravel's GitHub repository for the most recent updates and adjusting your code accordingly is crucial. I recommend referring to the Laravel upgrade guides for further insights.

Conclusion

This method provides the advantage of skipping incremental version updates, enabling a direct transition from any version to your intended target version. prioritizes identifying errors initially and then addressing them accordingly. Robust test coverage is strongly recommended to validate the upgraded system's functionality. Additionally, it's highly encouraged to thoroughly review both Laravel's upgrade guides and those of various dependencies for a smoother upgrade process.