Upgrade PHP Versions

Learn how to upgrade PHP versions to resolve compatibility issues.


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.

Available PHP Versions

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.

EOL PHP Versions

Pantheon also makes PHP 7.0, 5.6, 5.5, and 5.3 available on the platform, although these are end-of-life (EOL), and should not be used unless absolutely necessary.

Configure PHP Version

Manage PHP versions by committing a pantheon.yml configuration file to the root of your site's code repository. When using SFTP mode, navigate to 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.

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