Installing Extensions (PECL / PIE)

What Are PHP Extensions?

In simple terms: PHP's core language is extended by extensions — modules that add functions and classes: pdo_mysql for MySQL, intl for international formatting, gd for images, redis for Redis, xdebug for debugging. Some come built into PHP; others must be installed separately. When a project needs a feature PHP does not provide out of the box, installing the right extension is often the first step. Technically: Extensions are compiled modules (usually written in C) loaded by the PHP engine at startup. Bundled extensions ship with PHP's source code and are enabled at compile time or installed as operating-system packages. Third-party extensions are distributed through PECL (the PHP Extension Community Library) and, increasingly, through PIE (the PHP Installer for Extensions), the official successor to PECL that installs extensions published as Composer-style packages on Packagist. Extensions are enabled with extension= (or zend_extension= for engine-level extensions such as OPcache and Xdebug) in php.ini.

Checking Which Extensions Are Loaded

php -m

[PHP Modules]
Core
ctype
curl
date
...
pdo_mysql
sodium
...
[Zend Modules]
Zend OPcache

From PHP code:

<?php
$required = ['pdo_mysql', 'mbstring', 'intl', 'sodium', 'redis'];
foreach ($required as $extension) {
    printf("%-10s %s\n", $extension, extension_loaded($extension) ? 'OK' : 'MISSING');
}

Output (example)

pdo_mysql  OK
mbstring   OK
intl       OK
sodium     OK
redis      MISSING

Remember that the CLI and PHP-FPM may load different configurations (see PHP Configuration (php.ini)): an extension can be available in the terminal but missing on the website, or the other way around.

Declaring Requirements in Composer

{
    "require": {
        "php": "^8.3",
        "ext-pdo_mysql": "*",
        "ext-intl": "*",
        "ext-redis": "*"
    }
}

composer install refuses to proceed if a declared extension is missing, and composer check-platform-reqs lists all requirements and whether the current environment satisfies them. This catches missing extensions before deployment rather than at runtime.

Installing With Operating-System Packages

On Linux distributions, most common extensions — bundled and popular third-party ones — are available as packages built for the installed PHP version:

# Debian / Ubuntu (versions from the official or the Ondřej Surý repository)
sudo apt install php8.4-intl php8.4-mbstring php8.4-redis php8.4-gd
sudo systemctl restart php8.4-fpm

Packages are the easiest option: they are compiled for your PHP version, updated with system updates, and enabled automatically (through files in conf.d/). Restart PHP-FPM (or the web server) afterwards.

Installing With PIE

PIE installs extensions from Packagist, using the same package names and version constraints as Composer:

# Install PIE (a PHAR file) — see https://github.com/php/pie for current instructions
curl -fL --output /usr/local/bin/pie https://github.com/php/pie/releases/latest/download/pie.phar
chmod +x /usr/local/bin/pie
# Install extensions
pie install phpredis/phpredis
pie install xdebug/xdebug

What PIE Does

1. Finds the extension package on Packagist (extensions are published with the package type php-ext or php-ext-zend).
2. Downloads the source (or a prebuilt binary on Windows) for a version compatible with your PHP version.
3. Builds it with phpize, ./configure, and make (build tools and PHP development headers must be installed, for example php8.4-dev and build-essential).
4. Installs the compiled module and, where possible, enables it in php.ini. PIE targets the PHP version of the php executable it runs with; use --with-php-config=/usr/bin/php-config8.4 when several PHP versions are installed.

PECL

The traditional tool works similarly and is still found in many guides and Docker images:

pecl install redis

The PHP project is moving extension distribution from PECL to PIE, so prefer PIE (or system packages) for new setups.

Enabling an Extension Manually

When an installer does not enable the extension automatically, add it to a configuration file:

; /etc/php/8.4/mods-available/redis.ini (or directly in php.ini)
extension=redis
; Engine extensions use zend_extension
zend_extension=xdebug

Then verify and restart:

php -m | grep -i redis
php --ri redis          # shows the extension's version and settings
sudo systemctl restart php8.4-fpm

Extensions in Docker

The official PHP Docker images provide helper scripts:

FROM php:8.4-fpm
# Bundled extensions: build from PHP's source tree
RUN apt-get update && apt-get install -y libicu-dev libzip-dev \
    && docker-php-ext-install intl pdo_mysql zip opcache
# Third-party extensions: install, then enable
RUN pecl install redis \
    && docker-php-ext-enable redis

Install build dependencies (-dev packages) as needed, and keep images small by removing them after compiling in production images (or use multi-stage builds). Some community tools (for example, install-php-extensions) automate dependency handling.

Choosing Extensions Responsibly

Common Mistakes

Installing for the Wrong PHP Version or SAPI

Effect: The extension appears in php -m but not on the website (or vice versa). Fix: Check php --ini and the FPM configuration; install for the exact version; restart PHP-FPM.

Using extension= for Zend Extensions

Effect: OPcache or Xdebug fails to load. Fix: Use zend_extension= for engine extensions.

Missing Build Tools

Effect: PECL/PIE compilation fails. Fix: Install phpize (the PHP -dev package), a compiler, and the libraries the extension needs.

Leaving Xdebug Enabled in Production

Effect: Significant slowdowns. Fix: Install development extensions only in development images and environments.

Best Practices

• Prefer operating-system packages or official Docker helpers; use PIE for extensions not available as packages.
• Declare required extensions in composer.json and check them with composer check-platform-reqs.
• Verify extensions in the same SAPI that serves your application, and restart PHP-FPM after changes.
• Install only trusted, maintained extensions, and keep development tools out of production.
• Automate extension installation in Dockerfiles or provisioning scripts for reproducible environments. Official reference: https://www.php.net/manual/en/install.pecl.php