How to Install PDO Driver in a PHP Docker Image
When deploying a PHP application inside a container, the default base image often lacks database drivers. A common symptom is encountering a PDOException stating "could not find driver" when attempting to connect to MySQL. In many scenarios, developers instinctively try to patch this by installing packages like php5-mysql via apt-get. While this command installs the library files, it frequently fails to activate the extension within the PHP runtime environment of a Docker container.
The root cause lies in how the official PHP Docker images are built. These images start with Alpine Linux or Debian-based minimal distributions where extensions are not loaded by default. Even if you successfully copy the .so file for pdo_mysql into the correct directory and create an entry in your configuration file (e.g., /usr/local/etc/php/conf.d/mysql.ini), PHP will ignore it unless the extension is explicitly enabled or if the build process did not include the necessary dependencies to load it dynamically.
In the specific case of using php:5.6-apache, running apt-get install php5-mysql might appear to succeed because the package manager installs the shared object files. However, checking with php -i | grep PDO reveals a critical warning: "Unable to load dynamic library... cannot open shared object file." This indicates that while the extension file exists on the filesystem, the PHP interpreter cannot find it at runtime, or the configuration directive pointing to it is ineffective.
To resolve this without relying on fragile apt-get installations inside a running container, you should modify the Dockerfile to install the correct packages during the build phase. The official documentation suggests using specific package names that correspond to the PHP version and the underlying OS distribution of the image tag. For an Alpine-based image (common in older 5.x tags), you typically need to install php-pdo and php-mysql alongside your application dependencies.
Here is a robust approach to ensuring the driver is present:
- Identify the Base Image: Check if your specific tag uses Alpine or Debian. The command
docker inspect php:5.6-apachecan help verify the underlying OS. - Update Package Lists: If using a Debian-based image, you must run
apt-get updatebefore installing packages to ensure you have access to the latest repositories. - Install Dependencies: Instead of just
php5-mysql, install the full set of required extensions. A typical command sequence in your Dockerfile would look like this:
RUN apt-get update && apt-get install -y \
libapache2-mod-php5 \
php5-cli \
php5-common \
php5-curl \
php5-gd \
php5-mysql \
php5-pdo \
&& rm -rf /var/lib/apt/lists/*
After building the image with these dependencies, restart your container and verify the installation. Run php -m inside the container to list loaded modules. You should see both pdo_mysql and pdo listed without any warnings about missing files.
It is also vital to ensure that your php.ini file actually loads the extension. In some configurations, simply creating a file in conf.d is not enough if the extension file path was hardcoded incorrectly during the package installation or if the .so file is missing its shared library dependencies (like libmysqlclient).
If you are using a modern PHP version (7.x or higher), the process is cleaner because the official images usually include these drivers by default, or they use musl/libc setups that handle dependencies better. However, for legacy stacks like PHP 5.6, manual intervention in the Dockerfile is almost always required to avoid runtime errors.
For those maintaining large-scale PHP applications, ensuring database connectivity at the container level is a standard part of the setup. If you are looking for modern best practices or managed solutions for PHP deployment, resources such as https://laravelcompany.com often discuss how to streamline these configurations using orchestration tools like Docker Compose or Kubernetes, which can handle environment variables and connection pooling more gracefully than raw container patches.
Ultimately, the "could not find driver" error is a configuration mismatch between your application code and your runtime environment. By fixing the Dockerfile to explicitly install and enable the PDO MySQL extension during the build process, you eliminate the need for complex post-installation debugging and ensure your application can connect to its database immediately upon startup.