Install PHP

When to use it

Before serving a PHP application, running Composer, or when an application needs a newer PHP than the server has. Several versions can live side by side, so installing PHP 8.4 does not remove or change an existing PHP 8.2.

Choosing the options

PHP version — choose the newest version your application and its framework support; their documentation states which. PHP 8.2 receives security fixes only; choose it only for an application that cannot run on 8.3 or later.

Extensions — the PHP modules your application needs. The defaults (cURL, Intl, Mbstring, OPcache, XML, Zip) suit most applications. Add:

• MySQL / MariaDB for WordPress, Laravel and most PHP applications with a MySQL or MariaDB database.
• PostgreSQL for a PostgreSQL database.
• GD or Imagick for image resizing (WordPress uses both when present).
• BCMath for Laravel and anything handling money or large numbers.
• Redis, Memcached or APCu for caching and sessions.
• SQLite, SOAP, LDAP, GMP and Bzip2 when your application says it needs them.

From PHP 8.5 OPcache is built into PHP, and the run says so instead of installing a package.

Install PHP-FPM — keep it on to serve PHP through nginx or Apache. PHP-FPM is enabled and started. Turn it off for servers that only run PHP from the command line, such as queue workers.

Make this the version php runs — the php command, which cron jobs and scripts call, switches to this version only when you turn this on, or when the server had no PHP before. Leave it off while you move sites to the new version one at a time.

What it does on the server

• Ubuntu and Debian: uses the distribution's own packages when they carry the chosen version, and otherwise adds packages.sury.org, the standard source for other PHP versions on these distributions. Packages are named php8.4-cli, php8.4-fpm, php8.4-mysql, and so on; the binary is /usr/bin/php8.4 and the service php8.4-fpm.
• RHEL family: enables EPEL and Remi's repository and installs Remi's parallel packages, named php84-php-cli, php84-php-fpm, and so on; the binary is /usr/bin/php84 and the service php84-php-fpm.

Every extension you chose is checked to load before the run succeeds. No site, virtual host or PHP-FPM pool is configured.

After the run

Point your web server at the new PHP-FPM service's socket or port. Run Install Composer next if the application uses Composer.

Common problems

"These extensions are not available for PHP … on …" — Not every extension is packaged for every version and distribution. Nothing was installed. Remove the extensions the run lists, or choose another PHP version.

"PHP … is not available for …, even from packages.sury.org." — packages.sury.org no longer publishes for that release, as with Ubuntu 20.04. Upgrade the server's distribution.

"PHP … is installed, but these extensions do not load: …" — An extension's configuration is broken, often left by an earlier manual install. Check php8.4 -m (or php84 -m) on the server for the error.

"… already exists and was not created by this playbook, so php was not changed" — Something else manages the php command. Run the version's own binary, such as /usr/bin/php8.4, or remove the existing link and run again with Make this the version php runs on.

"The CodeReady Builder repository could not be enabled." (RHEL family) — Most of PHP installs without it. If an extension then fails to install, enable CodeReady Builder (CRB) on the server and run the playbook again.