Choosing your site's PHP version

Your host installs several versions of PHP side by side, and you get to pick which one your sites use. You do it yourself, from your own shell, by writing a tiny text file — no support ticket, no server access, no downtime for your other sites. This page shows you the files, what each one does, and how to check the switch actually happened.

There are really two different questions hiding in "which PHP version":

  • Which version serves your site to visitors (that's PHP-FPM), and
  • Which version runs your command-line tools like drush and composer (that's PHP-CLI).

They are set separately, with separate files, and it's fine — normal, even — for them to be the same. This page covers both, starting with the one most people mean.

Where the files live

Every file on this page goes in the same folder inside your account:

~/static/control/

That's a directory you already own. You reach it over SFTP or from your shell. You create these files by hand; none of them exist until you make one. To change a version you edit the file; to go back to the default you delete it.

Do it from your oN.ftp shell. When you connect to run drush, composer or anything command-line, connect as your oN.ftp user, not the plain oN one — that's the account with the BOA shell that reads these files and picks the right PHP for you. If command-line tools behave oddly, the wrong login is the usual reason. See Your shell and SFTP.

The version that serves your site: fpm.info

To choose the PHP version that runs your sites for visitors, write one line into fpm.info:

echo 8.3 > ~/static/control/fpm.info

That's the whole file — a single line, a single version number like 8.3. If you put more than one line in it, BOA ignores the file, so keep it to exactly one.

A background helper checks this file every three minutes and switches the PHP-FPM version for every site on your account. There's nothing to restart and nothing to click, and your sites keep serving throughout — you just wait a couple of minutes and the new version is live.

By default fpm.info sets the version for all your sites at once. If that's what you want — one PHP version across the whole account — this one file is all you need.

You don't have to create it to have a working default. If fpm.info isn't there, BOA is already running your sites on a sensible version. You only make the file when you want to change it.

A different version per site: multi-fpm.info

If some sites need one PHP version and others need another, add a second file, multi-fpm.info, and list the exceptions. Each line is a site name, a single space, then the version:

cat > ~/static/control/multi-fpm.info <<'EOF'
foo.com 8.5
bar.com 7.4
old.com 5.6
EOF

The rules for this file:

  • One site per line.
  • Start each line with the site's main domain name (the one you created the site with — not one of its aliases).
  • One space, then the PHP version.

Any site you list here uses the version you gave it. Any site you don't list falls back to the single default in fpm.info. So you can keep most sites on one modern version via fpm.info and pin just the one legacy site that needs an older one via multi-fpm.info. The two files work together — you'll usually have both.

The version for drush and the command line: cli.info

Your command-line PHP — the one that runs drush and Drush inside the Ægir control panel — is set separately with cli.info, in the very same folder and the very same one-line format:

echo 8.3 > ~/static/control/cli.info

Again: one line, one version. The same background helper reads it every three minutes and switches the command-line PHP for your whole account. Unlike fpm.info, there's no per-site version for the command line — cli.info applies to every site on the account, and that's the only option.

Two things worth knowing:

  • It doesn't touch Composer. composer runs from a shared, system-wide install, so it keeps using the server's default PHP no matter what your cli.info says. Only your host can change the version Composer runs on. Your cli.info still governs drush, which is what you're usually reaching for.
  • Match it to your site when it matters. If a site runs on an older PHP-FPM version, run its command-line work on the same version. Point cli.info at the version the site actually uses so drush and the site agree.
  • One legacy case pins it to 5.6 for you. If a site on your account runs on a platform that carries the old path_alias_cache module, and PHP 5.6 is installed on your host, BOA writes 5.6 into cli.info for you on its next pass — even if you set a newer version there. That module only works under the older command-line PHP, so this keeps its drush runs working. If your cli.info keeps reverting to 5.6, that's why; it isn't something you've done wrong.

Switch the command line instantly: phpNN.info

cli.info takes a couple of minutes to kick in. When you want the command-line PHP to change right now — for the very next command you type — use an empty marker file named after the version instead. The name is the whole instruction; what's inside doesn't matter, so an empty file is fine:

# Use PHP 8.3 on the command line immediately
touch ~/static/control/php83.info

The available markers follow the same pattern — php85.info, php84.info, php83.info, php82.info, php81.info, php74.info, and so on down the list.

The rule is simple: the highest version that's both marked and installed wins. So you don't have to tidy up when you move up — if php83.info exists and you add php84.info, your command line jumps to 8.4 (assuming 8.4 is installed on your host). A marker for a version that isn't installed is quietly skipped, and the next-highest installed marker takes over instead — so if a marker seems to do nothing, that version probably isn't built on your host yet. To step back down, delete the higher marker and the next-highest one takes over:

# Drop back from 8.4 to 8.3
rm ~/static/control/php84.info

This is the file to reach for when a tool tells you it needs a newer PHP — for example when a newer drush asks for at least PHP 7.4, creating a php74.info (or higher) marker gets you there on the next command.

Which version can I pick?

The versions BOA can run are:

5.6  7.0  7.1  7.2  7.3  7.4  8.0  8.1  8.2  8.3  8.4  8.5

Two practical limits sit on top of that list:

  • Not every version is installed on your host. To save space, versions no site is using may not be built. If you pick one that isn't installed, BOA won't leave your site broken — it falls back to another installed version instead — but you won't get the exact one you asked for. If you genuinely need a version that isn't there (a legacy one for an old site, say), that's an install on the server, so open a support request and ask your host to add it.
  • Your Drupal version decides the sane range. A given Drupal release only runs on certain PHP versions, so the right choice is "the newest PHP my site's Drupal supports." Pinning a site to a PHP version its Drupal can't handle will make the site error out. When in doubt, check Drupal's own requirements:

You can also write the version without the dot — 83 means the same as 8.3, and BOA reads it either way — but the dotted form is clearer, so prefer 8.3.

Confirm the change took

After you write fpm.info or cli.info, give it the three-minute window, then check. The friendliest confirmation is from the command line, as oN.ftp:

php -v

That prints the active command-line version, which reflects your cli.info (or your highest phpNN.info marker). For the version serving your sites, the source of truth is the file itself:

cat ~/static/control/fpm.info

If your change hasn't shown up yet, the answer is almost always "wait a little longer." The switch is on a three-minute cycle, so a quick re-check a minute later usually settles it. If a phpNN.info marker didn't switch the command line, confirm you're logged in as oN.ftp and not the plain oN account — that's the one wired to read these files.

When it's genuinely not yours to change

Everything on this page is yours to set from your own account. A couple of related things are not:

  • The server's overall default PHP, and the version Composer runs on, live in the host's own configuration. If you need those moved, that's your host's job — open a support request.
  • Installing a PHP version that isn't on the box. Adding a version is work on the server, so ask your host rather than looking for a file to edit.

Where to go next