Introduction
This article is a quick guide to the steps required for upgrading from PHP7.x to 8.1, and Laravel v8 to v9.
Since Laravel 9 now requires PHP 8, I thought this would be a useful reference for tackling the task.
Note: The environment used in this guide is Ubuntu 20.04 with Nginx. If using a different Linux distribution and/or Apache, the process and commands will be slightly different.
Approach
It goes without saying, but ensure you run through this process on a test environment first, to ensure a smooth production upgrade once certain that everything works.
PHP will need to be upgraded before Laravel, as we will run into Composer dependency issues if we try to do this the other way around.
Upgrading PHP
Follow these steps to get PHP 8.1 up and running in your environment.
Upgrade Steps
1. Let's start by making sure we have the PPA repository added, so we're able to install PHP 8.1. Run these two commands:
sudo apt install software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
2. Now we update our packages.
sudo apt update -y && sudo apt upgrade -y
3. We can now install PHP8.1 along with the libraries required for Laravel.
sudo apt install php8.1 php8.1-fpm php8.1-cli php8.1-curl php8.1-zip php8.1-mysql php8.1-mbstring php8.1-xml php8.1-bcmath
Note: You may need to install additional modules for certain libraries such as php8.1-gd. Don't worry if you miss any though - Composer will pick up these incompatibilities later when you upgrade the Laravel core.
4. Next, we'll need to update the FPM path in our Nginx hosts.
sudo vim /etc/nginx/sites-available/some-host.com
In this example we're upgrading from 7.4, so we'll change this:
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
to this:
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
5. Finally, we save the file and restart Nginx and FPM.
sudo systemctl restart nginx && sudo systemctl restart php8.1-fpm
Upgrading Laravel
This part can be quite tricky if you use a lot of libraries. My advice here is to check the status of the dependencies you use (i.e. in Packagist or GitHub), and ensure they are Laravel 9 compliant.
The other thing to keep in mind is that it's very common to run into dependency errors when running the upgrade, as many libraries require a version upgrade to support Laravel 9.
If this occurs, run composer update -vvv
for a verbose output, and check to see what is required. Quite often all the information is there, and fixing the issue is usually a case of updating the version reference in composer.json
to the latest.
Composer Edits
Per the documentation, you need to make some mandatory composer.json
updates.
Details here: https://laravel.com/docs/9.x/upgrade#updating-dependencies
And as mentioned above, check off each dependency in your composer.json
to ensure Laravel 9 compatibility.
Follow The Upgrade Guide
This part is self expanatory - run through the entire upgrade guide to see if any of your codebase is affected.
Details here: https://laravel.com/docs/9.x/upgrade
Most people have found the v8 - v9 migration fairly simple, with minimal breaking changes. In reality, this process only takes 15-20 minutes for non-complex codebases.
Run The Update
To kick off the update, run composer update
. If you run into compatibility issues while attempting the update, check your dependencies and make the appropriate updates in composer.json
.
Troubleshooting
Some tips if you are running into issues with the Composer update:
- Double check PHP 8 has upgraded and FPM is configured with the correct path in the Nginx host configuration (it may still be using 7.x).
- Run
composer update -vvv
for full verbose output - this should give you a clue as to which dependencies are having a problem. - Remove the dependencies and run an install from scratch -
sudo rm -rf vendor && composer install
. - If all else fails, remove all dependencies from your
composer.json
except for the ones that ship with the Laravel core. You should then be able to add them back one-by-one until you find the problematic library.
Wrapping Up
Thanks for reading the article, and best of luck if you're about to dive into the upgrade!
Top comments (0)