PHP 8.4 introduces powerful new features, enhanced security, and performance improvements while deprecating outdated functionalities.

This guide will walk you through installing or upgrading to PHP 8.4 on Ubuntu, Debian, and their derivatives. While compiling PHP from source is an option, using an APT repository ensures a more secure and efficient installation with future security updates.

Since PHP 8.4 is not available in the official Debian and Ubuntu repositories, this guide utilizes Ondřej Surý’s trusted PHP repositories, widely recognized for maintaining up-to-date PHP packages.

Potential Backward Compatibility Changes in PHP 8.4

PHP 8.4 introduces improvements like property hooks, asymmetric visibility, and updates to DOM, Curl, and PCRE extensions. However, it also deprecates some features and moves certain extensions to PECL, which may impact existing applications.

Key changes include:

• Implicitly nullable parameter declarations deprecated
• E_STRICT constant removed
• Extensions moved to PECL: Pspell, IMAP, OCI8, and PDO_OCI

Since PECL extensions follow separate release cycles, updates depend on their maintainers, and they may not always receive timely updates.

Before proceeding, backup your system to ensure you can revert if needed. This guide provides a side-by-side installation method, allowing you to switch between PHP versions as required.

For a seamless PHP 8.4 installation or upgrade, follow our step-by-step guide on phpsouq.com.

1. List existing PHP packages

This step only applies when upgrading an existing PHP setup. The following command lists all installed PHP packages with the text php in its name, shows it on screen, and writes it to a file called packages.txt. This file comes in handy at a later step when installing the PHP 8.4 packages, to ensure the same list of PHP 8.4 versions of the extensions are installed.

• dpkg -l | grep php | tee packages.txt

2. Add ondrej/php PPA/DPA

Because PHP 8.4 packages are not available in any of the current Debian or Ubuntu software repositories, the PHP packages must come from another repo.

Ondřej Surý maintains a package archive that contains compiled binaries of all current PHP versions, for Ubuntu and Debian. It also ships several PECL extensions including PECL extensions for PHP core extensions unbundled in PHP 8.4.

Once this repository is added, the initial installation and updates can be done with the standard apt commands.

Ubuntu PPA

• sudo LC_ALL=C.UTF-8 add-apt-repository ppa:ondrej/php # Press enter to confirm.
  sudo apt update

Debian DPA

• sudo apt-get update
• sudo apt-get -y install lsb-release ca-certificates curl apt-transport-https
• sudo curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
• sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
• sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
• sudo apt-get update

3. Install PHP 8.4 Server API packages

In the Ondrej's PPA and DPA, PHP 8.4 packages follow the php8.1-NAME pattern. PECL and shared PHP extensions also follow the same pattern.

Before installing PHP extensions, make sure to install one of the following PHP Server API (SAPI) packages:

Install PHP-CLI only

To install PHP CLI, install the php8.1-cli package, along with the extensions desired.

• sudo apt install php8.4-cli

PHP-CLI and PHP as an Apache module

To install PHP CLI and PHP 8.4 as an Apache module, install the libapache2-mod-php8.4 package:

• sudo apt install php8.4-cli libapache2-mod-php8.4

Unless the PHP application requires PHP to be installed as an Apache module, consider installing PHP-FPM instead.

PHP CLI and PHP-FPM (recommended)

It is recommended to install PHP-FPM to integrate PHP with web-servers such as Apache, Nginx, and Caddy.

• sudo apt install php8.4-cli php8.4-fpm

This installs the php8.4-fpm service and automatically enables it. See the FPM web-server integration section for the additional steps required later.

5. Check Installation

For a quick check of the PHP installation, run the following: 

• php -v

It should show the PHP version, build time, and more information:

• `php -v` output

If the PHP-FPM service is installed, its status can be checked as follows:

• sudo systemctl status php8.4-fpm

If the PHP-FPM server is running successfully, it should show an output similar to below:

• `systemctl status php8.4-fpm` output

4. Install PHP Extensions

All of the shared PHP extensions and PECL extensions follow the php8.4-EXTNAME pattern, where extname is the name of the extension.

When upgrading an existing system, refer to the packages.txt file created in the first step to check the existing PHP 8.3 or older PHP extensions.

To install a PHP extension, use the apt install command with the PHP extension name with the php-8.4- prefix. For example, the gd extension is installed with the php8.4-gd package:

• sudo apt install php8.4-gd

The following command installs a set of most common PHP extensions required by a majority of PHP libraries and frameworks:

• sudo apt install php8.4-common php8.4-{bcmath,bz2,curl,gd,gmp,intl,mbstring,opcache,readline,xml,zip}

To search for additional PHP extensions, use the apt search command:

• apt search php8.4

Development Tools

Development tooling such as Xdebug and code coverage tools can also be installed following the same package naming convention.

This step is not recommended on production servers.

Xdebug

• sudo apt install php8.4-xdebug

PCOV

• sudo apt install php8.4-xdebug

5. Web Server Integration

Depending on the server API installed in step 3, web server integration might require additional configuration for the PHP 8.4 upgrade to take effect.

PHP-FPM

When using PHP-FPM (by installing the php8.4-fpm package), the web server needs to be reconfigured to communicate with the PHP 8.4 FPM server over the updated the socket path.

Apache: This configuration change is made easy by switching on the PHP 8.4 configuration file:

• sudo a2enconf php8.4-fpm

Nginx: Update the fastcgi_pass directive from the old PHP FPM socket path to the new PHP 8.4 path:

• - fastcgi_pass unix:/run/php/php8.3-fpm.sock;
• + fastcgi_pass unix:/run/php/php8.4-fpm.sock; 

See Nginx documentation for more information

Caddy Server: Update the reverse_proxy directive to use the new PHP 8.4 FPM server socket path:

• - reverse_proxy @phpFiles unix//run/php/php8.3-fpm.sock
• + reverse_proxy @phpFiles unix//run/php/php8.4-fpm.sock

See How to use Caddy Server with PHP for more configuration details.

PHP as an Apache module

If PHP is installed as an Apache module, the following command disables the previous PHP module (8.3 in this example) and enables the new PHP version:

• sudo a2dismod php8.3 # Change to the current PHP version
• sudo a2enmod  php8.4

Migrate Configuration

The configuration files for the new PHP setup will be in the /etc/php/8.4 directory. The existing PHP installations are likely installed in the /etc/php/VERSION directories.

If desired, the configuration can be copied from older PHP versions. Copying over the existing files is not configured. Instead, consider checking the differences between two php.ini files and updating the PHP 8.4 php.ini files.

• diff /etc/php/8.3/cli/php.ini /etc/php/8.4/cli/php.ini

When using PHP-FPM, make sure to update the /etc/php/8.4/fpm/pool.d/www.conf file to match the older PHP-FPM runner pool configuration.

Purge Old PHP Versions

After confirming that the new PHP CLI (and optionally the web server integrations) work correctly, the packages and services of the old PHP versions can be removed if they are no longer necessary.

• sudo apt purge '^php8.3.*'

The example above shows an apt purge command that wildcard matches all PHP 8.3 packages.

Running PHP 8.4 alongside other PHP versions

If desired, PHP 8.4 installation mentioned in the steps above can co-exist with other PHP versions.

When installing PHP 8.4 CLI, it will be installed at /usr/bin/php8.4. Other PHP versions will be installed at the same location with the version name suffix (for example, PHP 8.3 at /usr/bin/php8.3). It is possible to invoke other PHP CLI versions directly by calling this path.

The default php command name will be symlinked to the latest PHP version by default. However, using the update-alternatives command, this can be changed to any other PHP version:

• sudo update-alternatives --config php

This opens an interactive interface to select the alternative PHP binary path that php points to:

There are 2 choices for the alternative php (providing /usr/bin/php).

 Selection    Path             Priority   Status
------------------------------------------------------------
* 0            /usr/bin/php8.4   84        auto mode
 1            /usr/bin/php8.3   83        manual mode
 2            /usr/bin/php8.4   84        manual mode

To set the path without the interactive prompt:

• update-alternatives --set php /usr/bin/php8.4