Install / Configure SQL Server PDO driver for PHP docker image
When building a Docker image based on php:7.2-apache to connect to Microsoft SQL Server, the standard approach mirrors that used for MySQL or MongoDB extensions. You typically use the docker-php-ext-install command to pull precompiled binaries from the official Alpine-based repositories. However, there is no built-in binary package for the SQL Server PDO driver (pdo_sqlsrv) available in the default PHP Docker layers.
Attempting to bypass this by running pecl install sqlsrv pdo_sqlsrv inside your build context often results in immediate failure, much like the error you encountered regarding the missing sql.h header file. This happens because PECL requires a full Visual Studio C++ toolchain and specific Windows headers to compile the extension from source, which are not present in the Linux-based Alpine Docker images used by the official PHP stacks.
To resolve this within a Dockerfile without switching base images or installing a heavy Windows SDK, you must download the precompiled .so file for your specific architecture and load it manually. The most reliable method involves downloading the extension from the official Microsoft SQL Server Driver for PHP GitHub releases.
You need to construct your Dockerfile to pull the appropriate binary, copy it into the PHP extensions directory, and then enable it. Here is a concrete implementation example:
FROM php:7.2-apache
# Copy application source code
COPY src/ /var/www/html/
# Define the architecture (e.g., amd64 or arm64)
ARG ARCH=amd64
# Download the precompiled pdo_sqlsrv extension for your specific PHP version and arch
# Note: You must match the exact PHP version (7.2.x) and OS distribution
RUN curl -sL https://github.com/microsoft/msphpsql/releases/download/v8.1.0/pdo_sqlsrv_810_lin-${ARCH}.tar.gz | tar xz \
&& mv pdo_sqlsrv_810_lin-${ARCH}/pdo_sqlsrv.so /usr/lib/php/20151231/pdo_sqlsrv.so
# Enable the extension
RUN docker-php-ext-enable pdo_sqlsrv
# Ensure Apache restarts to pick up the new configuration
RUN a2enmod rewrite && service apache2 restart
There are critical details to watch when using this approach. First, you must match the exact PHP version tag in your FROM instruction with the specific .so file you download. The official releases often bundle extensions for multiple PHP versions (e.g., 7.0 through 8.x). If you use a generic filename or an incorrect versioned binary, PHP will fail to load it at runtime, typically throwing a fatal error stating "PHP Startup: Unable to load dynamic library...".
Secondly, the file extension in the Docker container is often .so, but on some systems or with specific PHP configurations, it might need to be renamed or verified against phpinfo(). After enabling the extension, always verify that the pdo_sqlsrv.so appears in the output of running php -m or checking the Loaded Extensions section in a generated phpinfo() page.
Finally, ensure your application configuration files (such as .env or config/database.php) are correctly pointing to the SQL Server instance and that the connection string supports the necessary authentication modes (Windows Authentication vs. SQL Server Authentication). While this manual installation adds a few steps compared to using pecl install, it avoids the complex dependency resolution required for compiling from source in a Linux container environment.
For developers working with Laravel projects, ensuring database connectivity is straightforward once the driver is loaded, but remember that the underlying PHP version constraints apply regardless of the framework wrapper. If you need further assistance with specific configuration patterns or migration strategies involving SQL Server, resources like https://laravelcompany.com can provide context on best practices for database integration within the ecosystem.