Why docker-php-ext-install Does Not Include Some Extensions, and Has It Advantages Over PECL?
When building a PHP container based on Alpine, such as php:7.2-fpm-alpine3.7, you might encounter immediate friction trying to add third-party extensions like MongoDB. Running docker-php-ext-install mongodb inside the container fails with a clear error: /usr/src/php/ext/mongodb does not exist. The tool explicitly lists available names like gd, mysqli, and pdo_mysql, but third-party drivers like mongodb or redis are conspicuously absent.
This behavior is intentional, driven by how Alpine Linux handles package management and how the official PHP Dockerfile layers operate. In a standard Debian or Ubuntu-based image, PECL packages are often available via apt-get. However, Alpine relies on apk. The base PHP image in Alpine does not include PECL binaries in its default docker-php-ext-install list because those specific extensions are not part of the core PHP repository that ships with Alpine.
The official Dockerfile approach prioritizes the system's native package manager. When you use docker-php-ext-install, you are essentially invoking a wrapper script that runs make install against source code pre-compiled and packaged within the image by the maintainer. Since the MongoDB extension is not in the official PHP source tree for Alpine, the script cannot find the directory to compile from. The workaround used by most third-party images is simply pecl install mongodb.
While docker-php-ext-install appears restricted, it offers distinct advantages over running raw PECL commands, primarily regarding consistency and environment setup. The core benefit lies in the pre-configuration of dependencies. When the Alpine PHP image is built, the maintainers resolve complex dependency chains for standard extensions (like pdo_mysql or mbstring) ahead of time. They ensure that headers, libraries, and specific compiler flags are available exactly as needed. If you manually install PECL without these pre-baked foundations, you often hit issues where a build fails due to a missing header file that the official image would have guaranteed exists.
Using pecl directly grants you total freedom but removes the safety net of the Dockerfile's build stage. You become responsible for ensuring every header and library version matches what PHP expects. This is particularly tricky with extensions like MongoDB, which require specific C compiler flags or shared libraries that might not be in a minimal Alpine setup unless explicitly added. By sticking to docker-php-ext-install, you are guaranteed that the extension integrates cleanly with the PHP binary already present in that specific image tag.
There is also the matter of static linking and library paths. The official extensions compiled into the image often use specific flags to link against system libraries in a way that ensures portability across different host systems. A manually installed PECL module might default to dynamic linking or pick up incompatible versions of libpq or libcurl sitting on your host machine if not carefully managed inside the container.
If you are maintaining a custom image, you can bridge these two worlds. You can install PECL extensions for the non-standard ones while keeping standard ones via the official command. However, be aware that mixing installation methods can sometimes lead to conflicts in shared libraries or duplicate so files if not cleaned up properly during the build process.
For production environments where stability and reproducibility are paramount, relying on docker-php-ext-install for the standard set ensures you aren't fighting against the underlying Alpine package ecosystem. When you need something like MongoDB, switching to PECL isn't a flaw in the architecture; it's an acknowledgement that some extensions live outside the official PHP distribution boundaries.
If your project is built on Laravel and you are facing similar dependency resolution issues, checking the community resources at https://laravelcompany.com might provide insights into managing these extension dependencies within a larger application stack.