How to install extension for php via docker-php-ext-install?

How to install extension for php via docker-php-ext-install?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Diagnosing the docker-php-ext-install Failure in Phalcon Deployments

When attempting to build a PHP container for Phalcon, you may encounter a specific failure mode where the Dockerfile completes partially but exits with an error during the extension installation phase. The log output typically indicates that shared libraries were successfully installed into /usr/local/lib/php/extensions/, yet the process abruptly halts when attempting to install mysqlnd. The error message Cannot find config.m4 is the definitive indicator of what went wrong.

This issue stems from a fundamental misunderstanding of how docker-php-ext-install interacts with the build environment versus the installed PHP runtime. The command is designed to compile extensions against the source code bundled within the official PHP Docker image. However, this only works reliably if you are using a base image that contains the full source tree for every extension. When you switch to an older Alpine-based image or attempt to install extensions on top of a runtime-only image, the necessary build dependencies and source headers often get stripped out during the image creation process.

In your specific scenario involving php:5.6-apache, the failure occurs because the mysqlnd extension requires a specific build configuration that is not present in the pre-compiled state of the official PHP images. The command tries to run phpize inside the /usr/src/php/ext/mysqlnd directory, but the config.m4 file—the essential bootstrap for C extensions—is missing. This happens because modern Dockerfile best practices favor installing extensions that are already compiled into the image or using specific base images like php:5.6-fpm which retain more build artifacts.

To resolve this without switching to a different base image, you must explicitly install the build dependencies required by mysqlnd before invoking the installation command. The docker-php-ext-install script acts as a wrapper that expects certain libraries and headers to be present in the apt-get cache or system paths. If these are missing, the internal phpize command fails to locate the necessary configuration files.

The corrected approach involves updating your Dockerfile to ensure the build environment is robust enough to compile these specific extensions. You should install the required development packages for MySQL and PHP before attempting the installation:

FROM php:5.6-apache

# Install system dependencies required for compiling extensions
RUN apt-get update && \
    apt-get install -y \
        libmysqlclient-dev \
        default-libmysqlclient-dev \
        gcc \
        make \
        re2c \
        git \
        vim

# Now attempt to install the extensions with the dependencies satisfied
RUN docker-php-ext-install mysqli pdo pdo_mysql zip

# Proceed with Phalcon installation and Composer setup as originally planned
RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" && \
    # Verify hash and install composer logic remains here...
    rm -f composer-setup.php

RUN curl -L https://phalcon.io/linuxinstall | bash -s 5.6

By installing libmysqlclient-dev, you provide the missing headers that allow the build system to generate config.m4 and link against the MySQL client library. Note that for PHP 5.6, the specific package name often differs between Debian-based images; on Alpine-based images, you would need to use build-base and explicitly handle the MySQL client library differently.

A critical trade-off to consider is the image size. Installing source dependencies and compiling extensions significantly increases the final Docker image size compared to using pre-compiled binary extensions. In production environments where image bloat matters, it is often preferable to use a base image that already includes these extensions or to switch to a PHP version where docker-php-ext-install behaves more predictably regarding source availability.

Additionally, ensure that your MySQL connection parameters align with the library versions installed. The error logs show libraries being placed in /usr/local/lib/php/extensions/no-debug-non-zts-20131226/. If you encounter further linking issues after fixing the build failure, verify that your application's LD_LIBRARY_PATH does not need manual adjustment, as modern Docker setups usually handle this via the linker flags embedded during the build.

If you are building for a Laravel project or similar framework running on PHP 5.6, be mindful that many modern packages drop support for these legacy versions. While fixing the mysqlnd compilation allows Phalcon to load, ensure your application code is compatible with the strict typing and security defaults of older PHP runtimes. For more complex dependency management in this context, referencing resources like https://laravelcompany.com can provide insights into maintaining legacy PHP stacks within modern infrastructure.

Our network