Skip to main content
Log inGet free account
Last Reviewed: December 13, 2022

Upgrade PHP Versions

Learn how to upgrade PHP versions to resolve compatibility issues.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

This section provides information on how to upgrade to a supported version of PHP.

Upgrading your site's PHP version will improve the security, performance, and supportability of your site. Refer to our blog post for an example of 62% performance gains after upgrading PHP.

Before You Begin

Older software is more likely to contain code that is incompatible with recent PHP versions. Before you upgrade your PHP version:

Note

Changes to pantheon.yml deployed as hotfixes are not detected.

Verify Your Current PHP Version

Go to the Site Dashboard and click Settings, and then click PHP version to verify your PHP version.

Note

Changes made to the pantheon.yml file on a branch are not detected when creating the Multidev environment for that branch. Refer to Why can’t I update the PHP version on my Multidev? for more information.

CMS Version Requirements

Confirm that your CMS is compatible before changing your PHP version.

Configure Your PHP Version

PHP versions can be set using the pantheon.yml configuration file in the root of your site's code repository.

Configurations made in pantheon.yml will override custom settings in pantheon.upstream.yml.

You can use SFTP or Git mode to create or change the pantheon.yml file. Follow the steps below to create or change your pantheon.yml file.

  1. Go to the Site Dashboard and click Dev.

  2. Select SFTP as your Development Mode.

  3. Use the credentials under Connect with SFTP to connect to your preferred SFTP client to Pantheon.

  4. Check the /code directory for the pantheon.yml file (or create one if it is not already present) and edit it to include the desired PHP version.

    pantheon.yml
    api_version: 1

php_version: 8.2
    • You do not need to specify the PHP version's exact point release (for example, 8.1.10), as these are managed by the platform and deployed automatically.

  5. Navigate to your SFTP client and refresh the /code directory to verify that the pantheon.yml file has been created and contains the changed version.

  6. Go to the Site Dashboard and refresh the Dev environment tab to verify that the pantheon.yml file is available to commit.

  7. Enter a commit message and click Commit changes.

  8. Refresh the Dev environment tab and verify that the pantheon.yml file is now committed to the master branch.

  9. Pull changes to your local repository (if you have one).

    • Now your site’s PHP version is determined via pantheon.yml, and managed in version control. The next time you push your changes to Pantheon, your site will begin using the newly specified PHP version.

Your Site Dashboard will detect the changes when you upload a new or modified pantheon.yml file in SFTP mode.

The Site Dashboard sees changes to pantheon.yml

If the contents of pantheon.yml are valid, you can commit normally. If there is a problem with the file, the dashboard will fail to commit and display the error. The example below shows a failed attempt to set the PHP version to 12:

The Site Dashboard doesn't commit invalid changes

Multidev PHP Configuration

PHP version changes (and other configuration changes) are automatically detected when you modify the pantheon.yml file of a site with a pre-existing Multidev. A PHP version change will not appear in a Multidev created after your pantheon.yml changes are made.

Change the PHP Version on an Existing Multidev

Follow the steps to Configure Your PHP Version. Your Multidev configuration will automatically detect and apply the PHP version change from the pantheon.yml file.

Change the PHP Version on a New Multidev

You must make an additional modification to your pantheon.yml file to initiate the PHP version update in your Multidev if you created a new branch and added a Multidev after configuring your PHP version in the pantheon.yml file.

  1. Navigate to your pantheon.yml file.

  2. Modify your pantheon.yml file and re-commit to the Multidev.

  • It does not matter what change you make to the file. Any change- even a comment- will allow the Multidev to detect the configuration change. You will receive a notice indicating configuration changes have been detected and applied to the Multidev environment:
remote:
remote: PANTHEON NOTICE:
remote:
remote: Changes to `pantheon.yml` detected.
remote:
remote: Successfully applied `pantheon.yml` to the 'new-feature' environment.
remote:
remote:

Troubleshoot Post-Upgrade Errors

Resolve PHP Version Compatibility Issues

We recommend working with theme, module, or plugin maintainers to resolve any issues upstream. For custom code, refer to the corresponding Backward Incompatible Changes documentation in the PHP Manual for migrating from one PHP version to another.

Upgrading PHP Version May Require Upgrading Drush Versions

Upgrade your current version of Drush if you see errors on the Pantheon Dashboard when trying to auto-run update.php. Refer to Manage Drush Versions on Pantheon for more information.

More Resources