Install PHP Extensions with docker php-ext-install and Pecl Commands

PHP runs great on Docker containers. But to extend your PHP Docker functionalities, you need to install, configure and enable PHP related extensions such as Redis, PostgreSQL (pgsql), MySQL, Imagick, GD, mysqli, zip, MongoDB, curl, bcmath, Memcached, mssql and Xdebug.

This guide delves deep into the realm of docker php ext and how to use Docker php-ext-install and Pecl Commands to install, configure, and enable PHP extensions within Docker containers.

To extend your PHP Docker development environment, you’ll set up PHP extensions on the Docker and cover the following key aspects:

• How to ideally use docker php ext install and pecl install commansd with Docker to install any PHP extension.
• How to use RUN with Dockerfile and install Docker PHP extensions.
• Using Docker Compose to run PHP code based on PHP Docker Extention you have installed.
• Learn how to use docker php ext configure to modify settings or features tailored to the extension of your choice, such as docker php ext configure gd.
• How to use docker php ext enable so you can enable an extension and make it available in PHP scripts. This includes docker php ext enable xdebug and Docker php ext enable redis.

Dive into this guide and learn how to install PHP extensions within Docker containers. You will use examples of popular extensions such as Redis, PostgreSQL MySQL, and Xdebug to understand how to integrate these extensions completely.

Understanding Docker-PHP-ext-install Command

Docker-php-ext-install is a script for installing PHP extensions. You use it on Dockerfile to ensure the required extensions are available in the PHP environment within a Docker container.

How to Use Docker-php-ext-install and pecl Commands

In your Dockerfile, you must have the following docker-php-ext-install basic syntax:

RUN docker-php-ext-install extension_name

Consider using PostgreSQL. In this case, you will install the pgsql extension using Dockerfile as follows:

# Add PHP-Apache base image
FROM php:8.2-apache
# Install common extensions bundled with PHP
RUN docker-php-ext-install mysqli pdo_mysql

I have created the following Guide describing how to use docker php-ext-install and pecl install commands.

• How to use docker php ext install (pecl install) and enable MongoDB Command
• How to use docker php ext install pgsql Postgres Command
• How to use RUN docker php ext install mysqli MySQL Command

Docker php-ext-install vs. pecl Install Command

Suppose you are using Docker and PHP. These are the two main commands you will use to install extensions.

docker-php-ext-install is part of the official PHP Docker images. You need to install PHP extensions sourced from PHP distributions. They are mainly bundled with PHP and standard extensions.

pecl install is the PHP Extension Community Library. If you have used PHP before, you might have used pecl to install extensions on your computer. I have seen it used largely when installing third-party extensions not included in the PHP source.

Compare Redis and mysqli. In this case, you will use docker-php-ext-install to install mysqli and pdo_mysql and pecl install for Redis extension as follows:

FROM php:8.2-apache

# Install bundled extensions
RUN docker-php-ext-install mysqli pdo_mysql

# Install third-party extension - Redis
RUN pecl install redis \
    && docker-php-ext-enable redis

Third-party extensions like Xdebug, MongoDB, or Redis will use pecl install.

Installing Extension for Using Docker-php-ext-install Command

Assume you want to use MySQL with PHP on Docker. You will need MySQL and pdo_mysql extensions so your Dockerized PHP app can connect to MySQL. You will use a Dockerfile to create your configurations in this case.

The Dockerfile uses RUN, which equals your Docker terminal. This way, you can run docker-php-ext-install or pecl-install and ready your mysqli extension.

You must have mysqli installed using Dockerfile as follows:

# Using a PHP dockerhub image
FROM php:8.2-apache

# Installing extensions
# Incorporating mysqli for MySQL connection
RUN docker-php-ext-install mysqli pdo pdo_mysql

Check this Fixes for Docker PHP Ext Install Command Not Found guide to solve any docker-php-ext-install errors.

Using Docker-php-ext-install Extensions with Docker Compose

Let’s use the following structure to demonstrate how to use the docker-php-ext-install Command:

php-ext/
│ ├── ext.dockerfile
│ └── docker-compose.yml
└── test/
    └── index.php

You already have mysqli Dockerfile ready in the above step.

Here, I will assume your index.php file contains the following MySQL database CONNECTION script:

<?php
// MySQL database host (as your MySQL Docker service name)
$mysql_host = 'db-srv'; 
// MySQL user
$user = 'test_user'; 
// MySQL user password
$pass = 'db_user_pass';
// Database name 
$db_name = 'test_db'; 

// Creating a MySQLi connection object
$conn = new mysqli($mysql_host, $user, $pass, $db_name); 

if ($conn->connect_error) { 
    // Checking connection status
    die("Connection failed: " . $conn->connect_error); 
    // Show what error if the connection fails
}

echo "MySQL Database and PHP Connected successfully"; 
// Display success message if the connection is successful

$conn->close(); 
// Closing the database connection
?>

In this example, you must have a container named mysql-db. At the same time, your container needs to access index.php to run your code.

Now, in your docker-compose.yml file, you spin up a MySQL and PHP container as follows:

version: "3.8"
services:
  #  container to serve PHP to the web
  simple-php-app:
    container_name: simple-php-app
    # Docker Image Build Context
    build:
      context: . 
      # path to ext.dockerfile 
      dockerfile: ext.dockerfile 
    volumes:
    # Mount local directory to container's web root
      - ./test:/var/www/html 
      # Map host port 8000 to container port 80
    ports:
      - 8000:80 
    depends_on:
      - mysql-db

  # db service
  db-srv:
    image: mysql:8.0
    environment:
    # Set root password
      MYSQL_ROOT_PASSWORD: password 
      # Create a database named 'test_db'
      MYSQL_DATABASE: test_db
      # Create a MySQL user 'test_user'
      MYSQL_USER: test_user 
      # Set password for 'test_user'
      MYSQL_PASSWORD: db_user_pass 
    ports:
    # Expose MySQL default port
      - "3306:3306" 

Docker will use the mysqli you previously installed in your Dockerfile (docker-php-ext-install mysqli) and communicate with MySQL.

Build your app using the Docker Compose command:

docker-compose up --build -d

Your containers should be running in your Docker demon as follows:

Apache will server PHP on http://localhost:8000/. It’s here that PHP should use the installed mysqli connect to MySQL:

Installing PHP Extensions using pecl Install Command

pecl Install Command works best when using third-party Extensions. Let’s say we want PHP to use MongoDB. It’s here we need to use pecl to get the MongoDB extension installed on Docker using your Dockerfile as follows:

FROM php:8.2-apache
RUN a2enmod rewrite
RUN pecl install mongodb \
    && docker-php-ext-enable mongodb

RUN pecl install mongodb will do the job and install MongoDB on Docker. If you need to test if the installed extension is working, you will need to use the following instructions in your docker-compose.yml file:

version: '3.9'

services:
# PHP Apache service configuration
  web-app: 
    build:
      context: . # Dockerfile location
      dockerfile: Dockerfile
    volumes:
      - ./test:/var/www/html # Mounting test directory to container path
    ports:
      - 8000:80 # Expose host port 8000 to container port 80
    depends_on:
    # dependency on database
      - mongodb 

# MongoDB service configuration
  mongodb: 
    image: mongo:latest
    ports:
      - "27017:27017" 

Now your index.php file should have a script to test MongoDB as follows:

<?php
//The service name in Docker Compose is your hostname
$mongoHost = 'mongodb';
// The port on MongoDB is using on Docker 
$mongoPort = 27017;  

try {
    // new MongoDB client
    $mongoClient = new MongoDB\Driver\Manager("mongodb://{$mongoHost}:{$mongoPort}");

    // If successful, print a success message
    echo "PHP Connected to MongoDB successfully!";
} catch (Exception $e) {

    echo "PHP can't connect to MongoDB Service: " . $e->getMessage();
}

?>

Using MongoDB Extension with Docker is a comprehensive guide. Check this How to Run PHP and Mongodb with Docker Compose and Apache post and explore more.

How to Use Docker php-ext-enable Command with Docker php-ext-install and pecl install

You will note that some PHP extensions won’t work unless you activate them. In this case, you will use the docker php-ext-enable command.

Your docker php-ext-enable command will apply in any docker php-ext-install vs. pecl install scenarios. This means your enable command won’t change because you chose a different install command:

For example:

• Using pecl install with docker php-ext-enable

FROM php:8.2-apache

# Install the Redis extension using pecl
RUN pecl install redis \
# enable it using ext
    && docker-php-ext-enable redis

# Install Xdebug extension
RUN pecl install xdebug \
    # Enable xdebug
    && docker-php-ext-enable xdebug

• Using docker php-ext-install with docker php-ext-enable

# Official base image
FROM php:8.2-apache

# Install the mbstring extension
RUN docker-php-ext-install mbstring \
# enable the mbstring extension
    && docker-php-ext-enable mbstring

# Install GD extension
RUN docker-php-ext-install gd \
# Enable it on Docker
    && docker-php-ext-enable gd

# Install opcache extension and enable it on Docker
RUN docker-php-ext-install opcache \
    && docker-php-ext-enable opcache

For more in-depth knowledge and practical examples, explore additional guides:

• Running PHP and MongoDB with Docker Compose and Apache
• Simplified Apache PHP Setup with Docker Compose, MySQL, and PhpMyAdmin
• Effortless PHP, Apache, and PostgreSQL Setup with Docker Compose
• Effortless PHP, Apache, and PostgreSQL Setup with Docker Compose

Using Additional Dependencies with Docker-php-ext-install and pecl install Commands

When installing these extensions, at some point, you need to install additional dependencies that a specific extension requires to function in the right way:

For example, to use the GD extension, you may want to add to install the extension with JPEG and PNG support as follows:

# Use the official PHP as Apache base image
FROM php:8.2-apache

# Install GD extension with JPEG and PNG support
RUN apt-get update \
    && apt-get install -y libfreetype6-dev libjpeg62-turbo-dev libpng-dev \
    
    # Configure GD extension with freetype, jpeg, and png
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-png \
    
    # Run the docker-php-ext-install command for GD extension
    && docker-php-ext-install -j$(nproc) gd

Or using PostgreSQL where you need to install additional dependencies as follows:

FROM php:8.2-apache
RUN apt-get update \
    # libpq-dev headers needed to compile the PostgreSQL client
    && apt-get install -y libpq-dev \
    # Install PostgreSQL extension
    && docker-php-ext-install pdo_pgsql

Here is the equivalent of using pecl install with Imagick extension:

FROM php:8.2-apache

# Install Imagick extension
RUN apt-get update \
    # Imagick dependencies
    && apt-get install -y libmagickwand-dev \
    # Using pecl, install Imagick extension
    && pecl install imagick \
    # Enable Imagick extension
    && docker-php-ext-enable imagick

Conclusion

Docker-php-ext-install or pecl install usage varies based on the extension and how it integrates with PHP. Note that certain extensions may have additional dependencies that need to be installed in the Dockerfile, and I hope you have learned how to do that.