How to install LDAP in Docker php-fpm alpine
Building a PHP environment inside Alpine Linux within Docker introduces specific friction points compared to Debian-based images. The most common stumbling block occurs when attempting to extend the php image with the LDAP module. The error message "configure: error: Cannot find ldap.h" is not a bug; it is a direct consequence of how Alpine handles system libraries and development headers.
The root cause lies in the base image you are using: FROM php:7.2-fpm-alpine. While this is a valid starting point, standard PHP images often assume Debian's package management (apt) for installing system dependencies. Alpine relies exclusively on apk. When you run docker-php-ext-install ldap, the underlying build process attempts to locate the LDAP development files. If these are not explicitly present in the container's filesystem before the compilation step begins, the configure script fails immediately because it cannot find the required header files like ldap.h or ldblib.h.
To resolve this, you must ensure that all necessary system libraries and their corresponding development headers are installed via apk prior to invoking the PHP extension installer. The command chain requires a specific order of operations: first install the runtime library for LDAP, then install the development headers required for compilation, and finally trigger the extension build.
Here is the corrected Dockerfile approach:
FROM php:7.2-fpm-alpine
# Install system dependencies including LDAP libraries and headers
RUN apk add --no-cache \
curl \
libxml2 \
openssl \
oniguruma \
freetype \
tcl-ldap \
tcl-tk \
&& docker-php-ext-install ldap
# Copy the application code
COPY . /var/www/html
Notice the inclusion of tcl-ldap and tcl-tk. In many Alpine setups, the base LDAP libraries might be missing or incomplete without these specific packages, which provide the necessary underlying C libraries that PHP's LDAP extension depends on. Simply running apk add ldap is often insufficient because it installs only the runtime library, not the .h header files required for the configure step.
There is a trade-off to consider here regarding version compatibility. The example above targets PHP 7.2, which is quite old. If you are starting a new project, you should verify whether your specific use case supports modern PHP versions (8.x) and their respective LDAP implementations in Alpine. Modern Alpine images for PHP often bundle more up-to-date libraries by default, but the fundamental rule remains: if you are compiling an extension from source or enabling one that isn't pre-installed, the development headers must be present.
A common pitfall is assuming that docker-php-ext-install handles dependency resolution automatically. It does not. The command only compiles and installs the PHP extension itself; it does not pull in missing system libraries like libldap.so. If you skip the apk add step, the compilation fails with cryptic errors about missing headers or libraries.
If your application stack involves Laravel, ensuring consistent dependency versions across different environments is crucial for stability. While specific vendor setups vary, maintaining a clean Alpine image with explicit package declarations prevents "it works on my machine" scenarios from becoming production disasters. For more in-depth discussions on containerized PHP environments and best practices for scaling Laravel applications, you might find useful insights at https://laravelcompany.com.
Finally, always remember to clear any cache if the build fails repeatedly due to stale layer data, although fixing the apk installation order is the primary solution. Once the headers are present in /usr/include, the docker-php-ext-install ldap command will proceed without error, and your PHP-FPM container will be ready to authenticate against an LDAP directory service.