Installing PHP Extensions from PECL on Linux Servers

PHP extensions are fundamental components that enhance the features, capabilities, and overall performance of PHP handlers. Certain PHP applications and codebases may require specific extensions to be installed to function correctly. While many popular PHP extensions are typically pre-installed with server management platforms, the PHP Extension Community Library (PECL) offers a vast repository for additional extensions.

For Linux-based server environments, integrating PHP extensions from PECL can be managed efficiently through both the graphical user interface (GUI) of your server management control panel and the command-line interface (CLI). This comprehensive guide will walk you through the process of installing, updating, and uninstalling PHP extensions obtained from PECL.

Prerequisites and Important Considerations

The functionality to manage PECL extensions within your server management control panel is generally available for PHP handlers version 7.3 and newer. Before proceeding, it's crucial to acknowledge that extensions sourced from PECL are developed and maintained by third-party contributors. These extensions are not created, maintained, or officially vetted by the server management platform vendor. Therefore, users should exercise caution and install them at their own discretion and risk, ensuring compatibility and stability with their server environment.

Installing PHP Extensions

When you install a PHP extension from PECL using your server management control panel, you associate it with a specific PHP handler. It's important to understand that an extension installed for one PHP handler may not automatically be available for all others. Instead, an extension installed for a particular PHP handler becomes accessible to all other PHP handler types that utilize the same core PHP version and binary. This ensures consistent functionality across different execution modes for that specific PHP version.

For instance, if you install an extension for an 8.3.14 FPM application handler, it will also be available for 8.3.14 FastCGI application and 8.3.14 Dedicated FPM application handlers. However, it will not be available for an 8.2.25 FPM application handler. To make the extension accessible for the 8.2.25 FPM application handler, you would need to install it specifically for that handler or any other handler utilizing the PHP 8.2 version and its corresponding binary.

Installing the Latest Stable Version of an Extension

Adhering to best practices, it is always recommended to utilize the latest stable versions of all software components, including PHP extensions, to benefit from the most recent features, bug fixes, and security enhancements. By default, when installing an extension, the latest stable version available from PECL will be deployed.

Via the Graphical User Interface (GUI):

1. Access your server management control panel.
2. Navigate to the Tools & Settings section, then click on PHP Settings (typically found under “General Settings”).
3. Select the desired PHP handler from the list, and then proceed to click Manage PECL Packages.
4. Locate the specific extension you wish to install using the search bar if necessary, and then click the install icon (often represented by a plus sign or similar action button).

Upon successful installation, the extension will be activated and become available for the chosen handler, as well as any other handlers configured to use the same PHP version and binary. You can verify its presence within the list of available extensions for those handlers. For example, after installation, an extension like ioncube_loader would appear in the list. By default, newly installed extensions are enabled, but they can be disabled or re-enabled just like any other PHP extension.

Via the Command-Line Interface (CLI):

1. Establish an SSH connection to your server as the root user.
2. Execute the following command, replacing <extension name> with the actual name of the extension and <handler id> with the identifier of the target PHP handler:

   plesk bin php\_handler --extension-install <extension name> -id <handler id>

   For example, to install the msgpack extension for the PHP 8.3 FPM application handler, you would run:

   plesk bin php\_handler --extension-install msgpack -id plesk-php83-fpm

   To identify the correct ID for a specific PHP handler, you can run the command: plesk bin php_handler --list.

Once the extension is installed through the CLI, it will be listed among the other extensions available for the specified PHP handler, ready for use.

Installing a Specific Version of an Extension

There may be situations where installing an older version of an extension is necessary, for example, to maintain compatibility with existing applications or to test a beta release. This procedure allows you to specify a precise version or state for the extension you wish to install.

Via the Graphical User Interface (GUI):

1. Access your server management control panel.
2. Navigate to the Tools & Settings section, then click on PHP Settings (under “General Settings”).
3. Select the desired PHP handler, and then click Manage PECL Packages.
4. Click on the Install package option.
5. In the provided field, specify the exact name of the package along with the desired version number or state (e.g., beta), and then click OK. For example, to install the latest beta version of the msgpack extension, you would specify: msgpack-beta. To install version 2.2.0 of the msgpack extension, you would specify: msgpack-2.2.0.

After installation, the specified extension version will be available for the selected PHP handler and any other handlers sharing the same PHP version and binary. It will appear in the list of extensions, similar to how the ioncube_loader extension would be shown post-installation.

Via the Command-Line Interface (CLI):

1. Establish an SSH connection to your server as the root user.
2. Execute the following command, replacing <extension name> with the name of the extension combined with its desired version or state, and <handler id> with the ID of the specific PHP handler:

   plesk bin php\_handler --extension-install <extension name> -id <handler id>

   For example, to install the latest beta version of the msgpack extension for the PHP 8.3 FPM application handler, use:

   plesk bin php\_handler --extension-install msgpack-beta -id plesk-php83-fpm

   To install version 2.2.0 of the msgpack extension for the PHP 8.3 FPM application handler, use:

   plesk bin php\_handler --extension-install msgpack-2.2.0 -id plesk-php83-fpm

   As a reminder, to find the ID of a PHP handler, execute: plesk bin php_handler --list.

Once installed via the CLI, the specific version of the extension will be listed and active for the designated PHP handler.

Updating PHP Extensions

Maintaining up-to-date software components is essential for server security, performance, and access to the latest functionalities. This applies equally to PHP extensions. When a newer version of an already installed extension becomes available in PECL, the outdated extension will typically be indicated in the control panel's GUI with an update icon, signaling that an update is recommended.

Via the Graphical User Interface (GUI):

1. Access your server management control panel.
2. Navigate to the Tools & Settings section, then click on PHP Settings (under “General Settings”).
3. Select the desired PHP handler, and then click Manage PECL Packages.
4. Locate the extension that requires an update (you can use the search bar if needed), and then click the update icon (often an arrow pointing upwards or a similar symbol).

The system will then update the extension to the most recent version available from PECL.

Via the Command-Line Interface (CLI):

Updating an installed extension via the CLI follows a similar procedure to installing the latest version. You essentially re-run the install command for the extension. For example, to update the msgpack extension currently installed for the PHP 8.3 FPM application handler to its latest available version, you would execute:

plesk bin php\_handler --extension-install msgpack -id plesk-php83-fpm

This command will fetch and apply the newest version of the extension from PECL.

Removing PHP Extensions

It is considered a best practice to remove any software components that are no longer actively used on your server. This helps in mitigating potential conflicts, reducing the attack surface for security vulnerabilities, and keeping your server environment clean and efficient. If a PHP extension is no longer required, its removal is highly recommended. Should the extension become necessary again in the future, it can always be reinstalled.

Via the Graphical User Interface (GUI):

1. Access your server management control panel.
2. Navigate to the Tools & Settings section, then click on PHP Settings (under “General Settings”).
3. Select the desired PHP handler, and then click Manage PECL Packages.
4. Locate the extension you wish to remove, click the uninstall icon (often a trash can or similar symbol), and then confirm the removal action.

Once the extension is successfully removed, it will no longer be available for the selected handler or any other handlers that previously shared the same PHP version and binary.

Via the Command-Line Interface (CLI):

1. Establish an SSH connection to your server as the root user.
2. Execute the following command, substituting <extension name> with the name of the extension and <handler id> with the identifier of the specific PHP handler:

   plesk bin php\_handler --extension-uninstall <extension name> -id <handler id>

   For example, to remove the msgpack extension from the PHP 8.3 FPM application handler, you would run:

   plesk bin php\_handler --extension-uninstall msgpack -id plesk-php83-fpm

   To assist in finding the appropriate ID for a PHP handler, use the command: plesk bin php_handler --list.

After executing the CLI command, the extension will be uninstalled and will no longer be available for the designated PHP handler or any associated handlers.