My experience upgrading Laravel framework 5.8 to 8.X

Laravel is known as an open-source framework based on PHP technology. Like other frameworks, its purpose is to ease the web development process by giving free access to pieces of code.

Software development has given the human imagination unlimited perspectives. Daily we witness how developers become crafters of the future, changing what we know now with something we could only wish for.

To create a space of free speech and vision, we’ve allowed the AROBS specialists to write about what they’re passionate about in technology.

Read below an article written by Sergiu T., web developer at Nordlogic by AROBS, about the Laravel framework that could save you from some headaches, as he concludes.

Nordlogic joined AROBS Group in 2022, bringing new capabilities to the Software Services division of the company.

Starting a fresh project is exciting for anybody, especially for developers: it gives them the flexibility to choose whatever tools they want in order to craft the software product. It also gives them the ability to pick the latest versions available at the time for their frameworks and packages.

Once we get past the project’s kick-off phase, many new features that depend on various packages are being developed. As time passes, contributors release new versions of their tools, and we keep up with them by maintaining our codebase and updating its core dependencies. Or we should because, sometimes, not enough attention is paid to this aspect. We might end up where I recently found myself working on a personal project: upgrading the backend’s framework from an outdated version to the latest one, an upgrade spanning several significant releases.

Things to consider before upgrading the Laravel framework

Major framework releases are scheduled every six months. In contrast, minor and patch releases may be released as often as every week. Even if these minor/patch releases don’t contain breaking changes, it doesn’t mean they won’t possibly affect your application. You should periodically check the upgrade guide from the official documentation to keep track of these changes and update your code accordingly.

Our current Laravel version was 5.8.37, and, at the time of the upgrade, there were already 3 major versions released: 6.x, 7.x, 8.x. The safest approach, in this case, is to incrementally upgrade Laravel to the latest version, one version at a time, to avoid dealing with a bunch of high-impact changes at once.

How do we actually upgrade the Laravel framework?

As you may know, Laravel uses Composer to manage its dependencies. In order to update these dependencies, we must make some changes inside composer.json file, specifically within the “require” and “require-dev” objects. It goes without saying that the core framework packages should be updated according to the documentation. It is also important to mention that our 3rd-party packages should be updated too!

For this operation, you must check each package’s compatibility with the framework version you are about to upgrade.

Finally, the upgrade process is triggered by a simple command: composer update.

To sum it up, the upgrading process consists of three steps:

Update the framework’s core dependencies
Update 3rd party packages
Run composer update

First upgrade: 5.8 to 6.x

As I stated earlier, we should follow the upgrade guide from the official documentation in order to make this process… less complicated.

Right away we see that Laravel 6.x requires PHP 7.2 to run, so you should make sure you have at least this version installed on your server. Next, we start updating core dependency versions inside the composer.json file: “laravel/framework” to “^6.0” and “laravel/passport” to “^9.3.2” (if used). In the same manner, we update the 3rd party packages our application uses individually, according to their release history/documentation.

composer.json :

				
					"require": { 
**** Core framework packages ***** 
   "php": "^7.2", 
   "laravel/framework": "^6.0", 
   "laravel/passport": "^9.3.2", 
   **** 3rd Party packages *****   
   "s-ichikawa/laravel-sendgrid-driver": "^2.1.0", 
   "adaojunior/passport-social-grant": "^4.2", 
   "cviebrock/eloquent-sluggable": "^6.0",
   "dees040/laravel-api-responses": "^0.2.4", 
**** More packages... *****
},

Then simply type composer update from your application’s root path and hope everything runs silky smooth. Unfortunately, we came across a few issues related to the installed packages and framework changes.

“Your requirements could not be resolved to an installable set of packages.

Problem 1

– adaojunior/passport-social-grant v3.5 requires laravel/passport ^6.0|^7.0|^8.0 -> found laravel/passport[v6.0.0, …, 6.0.x-dev, v7.0.0, …, v7.5.1, v8.0.0,

…, 8.x-dev] but it conflicts with your root composer.json require (^9.3.2).

Problem 2

– laravel/framework v6.0.0 requires ext-mbstring * -> it is missing from your system. Install or enable PHP’s mbstring extension.”

Running composer dump-autoload caused another error which was somehow related to the first one:

“In ProviderRepository.php line 208: Class ‘Adaojunior\Passport\SocialGrantServiceProvider’ not found”

I managed to get rid of this by removing its reference from the “App\Providers\AppServiceProvider” class, running composer remove adaojunior/passport-social-grant and requiring it again. As for the second problem, all I had to do was to enable the mbstring extension from the php.ini configuration file and restart the apache server.

composer update ran without any errors and php artisan –version showed version: 6.20.3.

The upgrade process was completed, but I had to check if there were any errors caused by this upgrade. I tried to open a blade view from the admin panel but failed due to an exception:

`Illuminate\\Routing\\Exceptions\\UrlGenerationException(code: 0): Missing required parameters for [Route: admin.users.update] [URI: users/{user}].`

I figured there was a problem with the way I pass arguments to the route() helper:

				
					------------------------------------------------------------------------------------- 

|          Method		|	          URI		    |	    	Alias	        	| 

|-----------------------------------------------------------------------------------| 

|         PUT|PATCH 	|	     users/{id} 		 |	         (users.update)		| 

------------------------------------------------------------------------------------

Throws error after upgrading to Laravel 6.0 (http://placeholder-website.com/users?id=1)

Works fine after upgrading to Laravel 6.0 (http://placeholder-website.com/users/1)

We get this error because this error is that in previous releases of Laravel, passing associative array parameters to the route method would occasionally use these parameters as URI values when generating URLs for routes. But starting with Laravel 6.0, these values will be attached to the query string instead.

I fixed this issue, and everything seemed to be in place. Moving to the next upgrade!

Second upgrade: 6.x to 7.x

Following the official guide, we managed to upgrade the framework to the 7th version. There were some issues related to compatibility between 3rd party and core packages and minor codeadjustments to make Still, in the end, everything was all right.

Prior to this upgrade, we used an older version of barryvdh/laravel-cors package which caused an error. Thankfully their GitHub page tells us what to do:

“If you get a conflict, this could be because an older version of barryvdh/laravel-cors or fruitcake/laravel-cors is installed.

Remove the conflicting package first, then try install again:”

composer remove barryvdh/laravel-cors fruitcake/laravel-cors

composer require fruitcake/laravel-cors

In the same manner, Laravel’s upgrade guide tips us off about some high-impact changes:

“App\Exceptions\Handler class should accept instances of the Throwable interface instead of Exception instances”
“You should install laravel/laravel-ui ^2.0 if you are using Laravel’s authentication scaffolding”
Update your session configuration file’s secure option to have a fallback value of null: ‘secure’ => env(‘SESSION_SECURE_COOKIE’, null);

Third upgrade: 7.x to 8.x

The minimum PHP version for this version is now 7.3.0, according to their documentation.

Namespaces for seeders and factories were added. To accommodate these changes, you can simply add the Database\Seeders namespace to your seeder classes. In addition to this change, you should rename the project’s database/seeds to database/seeders. Fix any package-dependency errors / address framework’s impact changes and you should see the latest version installed by running php artisan –version

Final thoughts

It’s essential to keep our project’s framework and its dependencies up to date . This way, we can take advantage of new functionalities and make our software more secure, as lots of exploits and vulnerabilities are being patched. Doing minor, incremental software upgrades is more cost-efficient than one big jump from an outdated version to the latest version.

We were lucky this time, but these significant version gaps can be the source of major headaches. Save yourself future trouble by making sure your frameworks are always up to date!