Quick Guide - Upgrading to Laravel 9 and PHP 8.1

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!