Tutorial: Updating to PHP 8.0 with Composer

I’ve been really excited to do this post for a while now. I’m going to do some experiments with PHP 8.x and this tutorial will walk you through everything you need to do the deed. We’ll use a few technologies to accomplish this such as:

• composer

• homebrew

• docker

Remember, you should be running the same version of PHP everywhere. This means on your working environment (e.g. VM / container), CI environment, and hosting environment. There are reasons why your host machine (the machine running the VM / container) might not be running the same version of PHP due to multiple project requirements. This is ok! But it may put some additional constraints on where / how you run certain commands.

Installing PHP 8 on your Host Machine

I’m running a Macbook Pro with Homebrew. If you haven’t seen my post on setting up your host machine for local php development, that might be a good read before you continue.

The TLDR here is that if you’re going to update composer to use PHP 8, the machine you’re running composer on needs PHP 8. This may sound obvious, but if you don’t have it you’ll almost certainly run into an error such as:

$ composer update php
Gathering patches for root package.
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires php >=8 but your php version (7.4.16) does not satisfy that requirement.

Essentially, this means that you can’t run PHP 8 on a project where the machine running the project is only running PHP 7.4. If you think about this, hopefully it makes sense!

When I started working on this tutorial, I was running PHP version 7.4 on my host machine. Here are the commands I ran to update to PHP 8:

First, I unlinked the currently installed version of PHP with

$ brew unlink php

Then, I installed the version I wanted (8.x). Note, this took a bit as there were a number of other packages and updates to install along with it.

$ brew install php@8.0

Once all of the update spam got done, I could run php -v in my terminal and got the following:

$ php -v

PHP 8.0.6 (cli) (built: May 13 2021 05:34:34) ( NTS )

So! Congrats to me, my host machine is now running PHP 8.x.

Updating your VM / Containers to PHP 8

The other thing I want to briefly call out is that your host machine may be “less” important to update to PHP 8 than any virtual machines you’re running. Remember, if you’re running any containers locally, in the cloud, in CI/CD, etc. these must all run the same version of PHP that you have configured in composer. In this case, I’ll want to make sure that my local Lando environment and my CI/CD build file are configured to run PHP 8.

For most Docker / Vagrant solutions (like Lando, Drupal VM, etc.) this is frequently configurable in a file. Here’s an example for Lando:

config:
  php: '7.4'

To update this to PHP 8.0, simple update the .lando.yml file like so:

config:
  php: '8.0'

Then rebuild the containers with lando rebuild. Similarly to the host machine, you should be able to run a php -v command inside your container to confirm that the php version was successfully updated.

$ lando php -v
PHP 8.0.3 (cli) (built: Apr 10 2021 13:18:16) ( NTS )

Note that the minor version of PHP inside the container is different than the version on my host machine. Typically this isn’t concerning, as long as you are running the same major version of PHP (but it is something to be mindful of).

Updating to PHP 8 with Composer

Now that all the PHP versions have been updated, it’s time to make the change in your composer.json file. Simply update:

"php": ">=8"

Then, it’s simply a matter of running composer update php --with-all-dependencies. Note that some packages may have explicit PHP dependencies defined in them, which could block you from updating to PHP 8. Sometimes you can work around this by deleting your composer.lock file and redrawing all of your dependencies with a composer update. But, if an upstream dependency requires PHP 7.x it will block you from updating to PHP 8. So, you’ll have to:

• update that dependency to a newer version that supports PHP 8

• remove that dependency

• wait until the dependency supports PHP 8

In my case, I hit these errors initially:

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

  Problem 1
    - slevomat/coding-standard 5.0.4 requires php ^7.1 -> your php version (8.0.6) does not satisfy that requirement.
    - acquia/blt-phpcs v1.0.0 requires acquia/coding-standards * -> satisfiable by acquia/coding-standards[v0.6.0].
    - acquia/coding-standards v0.6.0 requires slevomat/coding-standard ^5.0 -> satisfiable by slevomat/coding-standard[5.0.4].
    - acquia/blt-phpcs is locked to version v1.0.0 and an update of this package was not requested.

When I deleted my vendor directory and composer.lock and re-ran composer update more broadly however, everything installed fine.

Note that you can also run composer require php >=8 but given that you may well run into this exact issue with other dependencies, I usually find PHP updates to more easily be made by changing the composer.json manually and going through these last couple of steps I outlined here.

In Conclusion

There’s a lot of exciting enhancements in PHP 8. But, as with all major version updates make sure you carefully test these updates and only jump ahead when you’re sure that your hosting environment fully supports the new version AND you’ve thoroughly tested everything to make sure it works. Good luck and happy updating!

Related Content