How to install/upgrade PHP 8.2 on Debian and Ubuntu systems

PHP 8.2 brings major new features such as Read-only classes, New random extension, sensitive parameter redaction as well as language streamlining changes including deprecation of dynamic properties and string interpolation related deprecations.

Currently, PHP 8.2 packages are not offered in the default software repositories of Debian or Ubuntu, but PHP 8.2 packages are available from the repository maintained by Ondřej Surý. Ondrej's repository is the main and most up to date repository offering PHP packages and PECL extensions to Debian and Ubuntu based operating systems, and are used for all PHP.Watch guides on installing PHP on these systems.

What's New and Changed in PHP 8.2

PHP 8.2 brings a healthy list of new features for security and performance, and a few deprecations that may emit additional warnings on existing legacy systems because it deprecates dynamic properties, along with a few other deprecations.

For a full list of what's new and changed in PHP 8.2, see PHP 8.2: What's New and Changed

Notable Extension and INI changes

PHP 8.2 does not include any notable changes that should affect the installation or upgrade process. PHP 8.2 does in fact add a new extension called random, but this extension is always a bundled extension and PHP cannot be compiled without it.

One notable change in PHP's INI settings and files is that PHP 8.2 emits a warning upon ill-formatted INI settings that were silenced in old PHP versions. See PHP 8.2: INI Parsing warnings for more information.

---

Heads up: Potentially destructive actions ahead
The following actions are executed as sudo, and requires that level of permissions to continue. The usual warnings when making any system-wide changes apply here as well. Make sure to backup the system and check the backups before continuing.

---

Quick-Start

Below the command-line commands to install/upgrade to PHP 8.2, for detailed steps, go to Detailed Installation/Upgrade guide

Ubuntu

sudo dpkg -l | grep php | tee packages.txt
sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update
sudo apt install php8.2 php8.2-cli php8.2-{bz2,curl,mbstring,intl}

sudo apt install php8.2-fpm
# OR
# sudo apt install libapache2-mod-php8.2

sudo a2enconf php8.2-fpm

# When upgrading from older PHP version:
sudo a2disconf php8.1-fpm

## Remove old packages
sudo apt purge php8.1*

Debian

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

sudo apt install apt-transport-https lsb-release ca-certificates wget -y
sudo wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg 
sudo sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt update

# Expand the curly braces with all extensions necessary.
sudo apt install php8.2 php8.2-cli php8.2-{bz2,curl,mbstring,intl}

sudo apt install php8.2-fpm
# OR
# sudo apt install libapache2-mod-php8.2

sudo a2enconf php8.2-fpm

# When upgrading from older PHP version:
sudo a2disconf php8.1-fpm

## Remove old packages
sudo apt purge php8.1*

Detailed Guide

1. List and store the list of PHP extensions

The following command lists all PHP-related packages that exist on the current system, and saves them to a text file named packages.txt. This helps to reconstruct the same list of packages on PHP 8.2.

On a fresh installation, this step is not necessary.

dpkg -l | grep php | tee packages.txt

2. Add ondrej/php PPA as a software repository.

The repositories maintained by Ondřej Surý contain the main PHP packages, and are kept updated.

After this repository is added to the system's list of software sources, the initial installation and updates can be done with the standard apt commands.

Ubuntu LTS Versions

sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update

Debian

sudo apt install apt-transport-https lsb-release ca-certificates 
software-properties-common
sudo add-apt-repository ppa:ondrej/php # Press enter when prompted.
sudo apt update

3. Install PHP 8.2 and extensions

All PHP 8.2 packages available in the repository added in step #2 follow php8.2- naming pattern. Bundled extensions in PHP, such as json, ctype, date, random, etc do not need to be installed manually.

The php8.2-common package includes several common PHP packages. It is possible to selectively disable unnecessary extensions later.

sudo apt install php8.2 php8.2-cli php8.2-{curl,bz2,mbstring,intl}

Expand the curly braces above to include all extensions necessary on the new system. When upgrading an existing PHP setup, the packages.txt file created in step #1 should list all current PHP packages.

4. Install and enable server APIs

On a system that a web server integrates with PHP, install the additional Server API packages. The following are some examples on most popular combinations:

---

Apache web server with PHP-FPM

sudo apt install php8.2-fpm
sudo a2enconf php8.2-fpm
sudo a2disconf php8.1-fpm # When upgrading from an older PHP version
sudo service apache2 restart

---

Apache web server with PHP as an Apache module
Installing PHP as an Apache module is not recommended, unless it's required for an edge use case.

sudo apt install libapache2-mod-php8.2
sudo a2enmod php8.2
sudo a2dismod php8.1 # When upgrading from an older PHP version
sudo service apache2 restart

---

Nginx web server with PHP-FPM

sudo apt install php8.2-fpm
sudo service nginx restart

Then, edit the relevant Nginx configuration file to point to the new PHP socket at fastcgi_pass directive:

- fastcgi_pass unix:/run/php/php8.1-fpm.sock;
+ fastcgi_pass unix:/run/php/php8.2-fpm.sock;

5. Test PHP 8.2 Installation

To test the PHP CLI installation, try running the following commands:

php -v
php -m

The output is expected to show PHP 8.2, along with a list of enabled PHP extensions.

To test the web server integration, try running a PHP file via the web server.

6. Purge old PHP packages

The following commands remove older PHP versions. It is recommended to not remove them until the PHP 8.2 installation is verified to be working correctly.

sudo apt purge php8.1* # Change "php8.1" with the old PHP version names.

This removes configuration files for the packages being removed as well.

---

Running Multiple PHP 8.2 Alongside Other Versions

It is not necessary to install PHP 8.2 globally, and remove the old PHP version because it is possible to run multiple PHP versions on the same server simultaneously.

The PHP 8.2 CLI will be installed at /usr/bin/php8.2 location by default, but are linked Similarly, other PHP binary files will be located in the same directory (/usr/bin/php8.0, /usr/bin/php7.4, etc). The default php name will be symlinked to the latest PHP version by default, but it is possible to change where the default php command links to.

The update-alternatives command provides an easy way to switch between PHP versions for PHP CLI if there are multiple PHP versions linking to the same php path.

sudo update-alternatives --config php

This brings up a prompt to interactively 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.2   82        auto mode
  1            /usr/bin/php8.1   81        manual mode
  2            /usr/bin/php8.2   82        manual mode

To set the path without the interactive prompt:

update-alternatives --set php /usr/bin/php8.1