Updating Your Code Studio Project to PHP 8.1 with Composer

As recently announced Acquia Code Studio now supports PHP 8.1! This article talks about how to configure Code Studio to change your PHP version. But, updating Code Studio is only one component of the necessary changes you need to make for a project to change PHP version. In this article we’ll talk about the other updates you’ll need to make to ensure you’re ready to change PHP versions. 

Steps to Upgrade Code Studio to PHP 8.1

At a high level, changing PHP versions must be done in a handful of places, but they can essentially be boiled down to two categories: code and environments. Code studio is one of the environments you’ll need to update, along with all of the developer workspaces (local or cloud development environments), and hosting environments. Obviously, you should update any of the hosting environments until you ensure that the code can be updated and your testing passes. 

Typically we would recommend the following order of operations:

• Conduct compatibility testing with a tool like PHPStan
• Update / re-provision your development workspace / local environment with PHP 8.1
• Use composer to update to PHP 8.1
  • Update your composer.json to require php 8.1
  • Run composer update php --with-all-dependencies
• Test! 
• Update Code Studio to use PHP 8.1
• Open a merge request 
• Automated Testing / Build Pipelines
• Update Development Environment to use PHP 8.1
• Deploy to Dev
• Test!
• Update Staging Environment to use PHP 8.1
• Deploy to Staging
• Test!
• Back up code / database in production
• Update Production Environment to use PHP 8.1
• Deploy to Production
• Final Testing

How to change PHP version for Composer?

Not all PHP code is compatible with PHP 8.1 So, the first step to updating is actually doing some basic testing for deprecated functionality. Believe it or not, PHP 8.1 is a more problematic update for many projects than PHP 8.0 due to Symfony. Symfony 4.x can still be run using PHP 8.0 but PHP 8.1 requires Symfony 6.x. As a result, many projects made the jump from PHP 7.4 quite easily, but are struggling to get into PHP 8.1. In other words, don’t just assume that all of your custom code, plugins, and contributed projects will be compatible. They may not be.

Once you have some degree of certainty that your code is ready for PHP 8.1, go ahead and update your development workspace / local environment to use PHP 8.1. You’ll also want to use composer to update to PHP 8.1 by updating the composer.json file and running composer update php --with-all-dependencies. 

"require": {
        "php": ">=8.1",
}

The composer update isn’t going to catch 100% of the incompatibilities out there. Unfortunately, not all plugins/modules define PHP version explicitly in composer. Once your code updates, it’s time to test. 

Testing the PHP Update

If you have automated testing, that is going to be the fastest way to test your site. If you don’t (or if you don’t have broad coverage) it may take a bit longer. But the key action here is to ensure that the critical functionality and portions of your site still behave as intended after the PHP update. You’re looking for two things:

1. Errors: fortunately (or unfortunately depending on your point of view) PHP errors tend to be quite explosive. Things tend not to “sort” of work if they are incompatible. So, finding a PHP error typically results in a white screen of death (WSOD). If you find any of these, check your error logs and either update/patch the offending code or you’ll have to downgrade until it is fixed.
2. Deprecation warnings: these aren’t a big deal, but if your logging is misconfigured or error config is set improperly, you should show these warnings to users (so you’ll want to make sure you chase them down ASAP and fix if possible)

Updating through to Production

Most of the critical testing for your update can be conducted locally in a developer workspace. Obviously, you still need to update the rest of your environments and test the various places. But, if your site works locally and you can validate the PHP 8.1 there you “should” be ok in production as well. So, update your various environments (Code Studio, Dev, Stage, Prod, etc.). Please test in each environment before you continue deploying up the stack. But, again, this is just a sanity check at this point. Your local and Code Studio testing should identify the vast majority of problems (but, you certainly don’t want to get all the way to production and then realize “oops.”)

In Conclusion

PHP updates are another critical piece of maintenance for your site/platform and if you get into the habit of updating regularly, it doesn’t need to be a scary process. The big thing is to make sure you carefully test. The PHP community is doing incredible things in terms of performance and capabilities in new versions of PHP. Updating gets you some fantastic benefits and it’s definitely worth your time. Just remember… even if you don’t care about the new versions, sooner or later you will have to update as security coverage ends and your hosting platform changes its requirements. Acquia publishes these end of life notifications here.