Upgrade PHP Versions

Learn how to upgrade PHP versions to resolve compatibility issues.

Tweet

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

Before You Begin

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

Verify Current PHP Versions

Verify current PHP settings from the Site Dashboard by clicking Settings > PHP version.

 Note

Changes made to the pantheon.yml file on a branch are not detected when creating the Multidev environment for that branch. See Deploying Configuration Changes to Multidev for more information.

The recommended PHP versions available on Pantheon are:

Click on the links above to see the complete PHP info for each version, including the list of supported PHP extensions.

All PHP Versions

VersionRecommendedStatus
7.3✔Active
7.2✔Active
7.1❌EOL
7.0❌EOL
5.6❌EOL
5.5❌EOL
5.3❌Retired
EOL

End-of-life (EOL) versions are available on the platform but no longer under active development, and should not be used unless absolutely necessary.

Retired

Sites using retired versions of PHP will continue to serve pages, but new development cannot be done. To resume development on a site using a retired version of PHP, first upgrade the PHP version on the development environment.

 Note

Before changing your PHP version, confirm that your CMS is compatible:

Configure PHP Version

Manage PHP versions by committing a pantheon.yml configuration file to the root of your site's code repository. If you have a local git clone of your site, this is the project root. When looking at the site over an SFTP connection, look in the code directory. If the pantheon.yml file is not present, create one to look like the following:

api_version: 1

php_version: 7.0

You do not need to specify the PHP version's exact point release (e.g, 7.2.6), as these are managed by the platform and deployed automatically.

Now your site’s PHP version is determined via pantheon.yml, and managed in version control.

The next time you push your changes back to Pantheon, your site will begin using the newly specified PHP version.

Verify Changes

Git Mode

The first place to determine if your changes have been successful is the output from your git push command. A correct implementation will return:

remote: PANTHEON NOTICE:
remote:
remote: Changes to `pantheon.yml` detected.
remote:
remote: Successfully applied `pantheon.yml` to the 'dev' environment.

If you have an invalid pantheon.yml file, the git push operation will fail and your commit will be rejected. In this example, we've set an unavailable PHP version:

remote: PANTHEON ERROR:
remote:
remote: Changes to `pantheon.yml` detected, but there was an error while processing it:
remote:
remote:
remote: Validation failed with error:
remote: >   8.0 is not one of [5.3, 5.5, 5.6, 7.0]

Modify pantheon.yml until valid and commit the fix before attempting to push again.

 Note

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

SFTP Mode

When you upload a new or modified pantheon.yml file in SFTP mode, your site dashboard will detect the changes:

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. In the example below we've attempted to set the PHP version to 12:

The Site Dashboard doesn't commit invalid changes

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, see 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

If you see errors on the Pantheon Dashboard when trying to auto-run update.php, for example, upgrading Drush should resolve the issue. For more information, see Manage Drush Versions on Pantheon.

See Also