Choose and switch PHP versions

A server can run more than one PHP version at the same time. That is how you keep an old application on PHP 8.3 while a new one already uses 8.4, and how you test an upgrade on one site before you touch the others. SrvYard installs each version from the well-known ondrej/sury package repository, runs a separate PHP-FPM service for each one, and lets every site choose its own.

This article shows how to read the Runtimes tab, install and remove versions, set the two defaults and move a site from one version to another.

Before you begin#

• A server in the Ready state and the permission to manage PHP on it.
• Know what your application supports. Check the require section of composer.json and your framework's release notes before you move a site to a newer PHP. Most breakage on upgrade comes from packages that are not ready yet.
• Time for a few minutes. Installing a version runs apt on the server. Other PHP changes on the same server wait until it is done.

1. Read the Runtimes tab#

Open the server and choose Runtimes. The first card is PHP.

1. Install version opens the panel of step 2.
2. The version strip. Every version SrvYard offers, with a tick next to the installed ones and a label for its support status. Current is the newest stable release, Stable receives bug fixes and security fixes, Security fixes only receives only security fixes, End of life gets nothing any more, and a pre-release such as RC is not meant for production. The labels follow the official PHP support calendar and change on their own as dates pass.
3. The table lists the installed versions. PHP-FPM shows whether the service runs. Defaults shows which version is the CLI default and which is the Site default. Extensions counts the loaded extensions, and Sites counts the sites that run on this version.

1. A row is one installed version. Its label shows the support status, and a shield icon labelled Known security vulnerabilities appears next to a version that has them.
2. Extensions and Sites are counts. Look at Sites before you plan to remove a version.
3. The actions button at the end of the row opens the menu of step 3.

The page remembers when it last looked at the server (Checked 1h ago). Refresh asks the server again, which also picks up a PHP version somebody installed by hand over SSH.

2. Install another version#

Press Install version.

1. Version. Lists the versions that are not installed yet, each with its support label. If every supported version is already there, the panel says so.
2. Install PHP 8.5 (the button names your choice). SrvYard installs PHP-FPM, the command line and the standard extensions, starts the service and reports progress on the page and in the operation log. Your CLI default and site default stay as they are. Nothing changes for existing sites.

A pre-release version (the release candidate at the end of the list) asks for an extra confirmation: it can crash, and it is not for production. Install it only on a test server.

If the installation fails, the row stays in the table with Install failed and the error. Read it, fix the cause (a full disk, a broken package source), and choose Retry install in the row's menu.

3. Set the defaults and manage a version#

Open the menu at the end of a version's row. These entries matter for this article:

• Make CLI default. The version that answers when you type php in a terminal on the server, and the one any script that calls plain php gets. It is disabled for the version that already is the default.
• Make default for new sites. The version that the new site form preselects. Existing sites keep theirs. SrvYard confirms with New sites will use PHP 8.4.
• Extensions and Edit php.ini and pool are covered in PHP extensions and php.ini settings.
• Update packages runs the package update for that version only: use it to receive security fixes.
• Reload PHP-FPM, Restart PHP-FPM and Start PHP-FPM control the service of that version. A reload is gentle; a restart drops running requests.
• Uninstall removes the version. SrvYard asks you to type the version number and warns that it stops PHP-FPM and removes every package and configuration of that version.

An uninstall is refused, with the reason in the menu, when the version is busy, is the CLI default, is the default for new sites, or still has sites: One site runs on PHP 8.3 or 2 sites run on PHP 8.3. Move the sites and change the defaults first.

4. Move a site to another PHP version#

Open the site and choose Settings. The PHP version card sits below Identity.

1. PHP version. Lists only the versions installed on the server. Choose the new one.
2. Change PHP version. The card explains what happens: Switching creates a new pool, points Nginx at it and removes the old one. The site gets a fresh PHP-FPM pool for the new version, Nginx is reloaded to use it, and the old pool disappears.

Do the move in this order for a production site: install the version, move a staging copy first, run your tests, move the production site, watch the logs for a few minutes. If something breaks, switch the site back the same way: the old version is still installed.

The same list appears in the site's Advanced settings when you create a site, so a new site can start on the right version.

Which version should I pick?#

For a new site, choose the version labelled Stable or Current that your framework supports. Avoid End of life versions: they receive no security fixes, and SrvYard marks them in red so you notice. A good rule is to run production on the version one step behind the newest, and to try the newest on a staging site first.

Troubleshooting#

• "Another PHP operation is still running". Only one PHP change can run on a server at a time. Wait for the running one (see Recent operations at the bottom of the Runtimes tab) and try again.
• The version is not in the list when I change a site. It is not installed on that site's server. Install it from Runtimes first.
• "PHP 8.3 is the CLI default. Make another version the default first." The uninstall is blocked by a default. Make another version the default, then uninstall.
• After changing the site's PHP version, the site shows a 502. The new pool did not start, or an extension the code needs is missing for that version. Check the extensions of the new version, then the site's error log on the Logs tab.
• php -v shows another version than the site uses. That is normal: the command line uses the CLI default, and each site uses its own PHP-FPM. Use php8.3 -v to ask for a specific version.
• A pre-release cannot be installed without a confirmation. Tick the confirmation in the panel, or install a released version instead.

Related#

• PHP extensions and php.ini settings: extensions and limits per version.
• Node.js versions and package managers: the other half of the Runtimes tab.
• Create a site on your server: choose the PHP version when you create a site.
• Write and test a deploy script: scripts that call php use the CLI default.