Skip to content
ServerPilot

Install third-party PHP extensions

PHP extensions add new functionality to PHP that do not exist in the core PHP language.

There are two types of third-party PHP extensions.

  • PECL extensions — Open-source extensions from the PHP community.
  • Proprietary extensions — Extensions for use with a commercial product.

The PHP Extension Community Library (PECL) is a repository of open-source, third-party PHP extensions. See the PECL packages directory for a full list of available PECL extensions.

List installed PECL extensions

To list the installed PECL extensions for a particular PHP version, SSH into your server as root and run the following command.

Terminal window
sudo pecl8.4-sp list

If the output of the command is “(no packages installed from channel pecl.php.net)”, then there are no PECL extensions installed for that PHP version.

Install a PECL extension

Install the compiler

PECL extensions must be compiled from source code.

To install the compiler, run the following command on your server as root.

Terminal window
export DEBIAN_FRONTEND=noninteractive
sudo apt-get -y install gcc g++ make autoconf libc-dev pkg-config

Install the extension’s library

Next, compile and install the extension’s library. Replace EXTENSION with the name of the extension in the commands below.

Terminal window
sudo pecl8.4-sp install EXTENSION

Enable the extension in PHP

After compiling and installing the extension’s library, configure PHP to load the extension.

Terminal window
sudo bash -c "echo extension=EXTENSION.so > /etc/php8.4-sp/conf.d/EXTENSION.ini"

After configuring PHP to load the extension, restart PHP-FPM.

Terminal window
sudo service php8.4-fpm-sp restart

Remove a PECL extensions

If you no longer need an extension you’ve installed, you can remove the extensions.

Disable the extension in PHP

To remove a PHP extension, SSH into your server as root and run the following command. Replace EXTENSION with the name of the extension to remove.

Terminal window
sudo rm /etc/php8.4-sp/conf.d/EXTENSION.ini

Next, restart PHP-FPM.

Terminal window
sudo service php8.4-fpm-sp restart

If the extension was installed on multiple PHP versions, repeat the above steps for each PHP version.

Remove the extension’s library

Once you’ve removed the extension’s configuration file, you can choose to remove the extension’s library.

To remove the library file for an extension installed through PECL, run the following command as root. Replace EXTENSION with the name of the extension.

Terminal window
sudo pecl8.4-sp uninstall EXTENSION

The output of the above command will include the following message:

Unable to remove "extension=EXTENSION.so" from php.ini

This message can be safely ignored.

Finally, restart PHP to make sure there are no errors.

Terminal window
sudo service php8.4-fpm-sp restart

If you did not correctly remove the extension’s configuration file, restarting PHP will show warnings.

Recompile PECL extensions

PECL extensions need to be recompiled if libraries used by the extension have changed in a way that is not backwards compatible. For example, you will need to recompile PECL extensions after upgrading Ubuntu.

Recompiling a PECL extension involves three steps:

  1. Remove the extension’s library.
  2. Install the extension’s library.
  3. Restart PHP-FPM.

You do not need to disable or enable the extension in PHP.

You should ignore all messages about php.ini when recompiling PECL extensions.