Unable to load dynamic library 'oci8.so' (PHP 7.2)
Upgrading from PHP 7.1 to PHP 7.2 often introduces friction when dealing with Oracle connectivity via the oci8 extension. If you are encountering a startup error where PHP refuses to load oci8.so, the root cause is rarely the extension itself, but rather missing system-level dependencies required by its internal libraries.
The error message provides the critical clues needed for diagnosis:
PHP Warning: PHP Startup: Unable to load dynamic library 'oci8.so' (tried: /usr/local/lib/php/extensions/no-debug-non-zts-20170718/oci8.so (libmql1.so: cannot open shared object file: No such file or directory), /usr/local/lib/php/extensions/no-debug-non-zts-20170718/oci8.so.so (/usr/local/lib/php/extensions/no-debug-non-zts-20170718/oci8.so.so: cannot open shared object file: No such file or directory)) in Unknown on line 0
Notice the specific failure point: libmql1.so. This is a dependency of the Oracle Instant Client, not PHP itself. When PHP attempts to initialize the extension, it dynamically loads this library but fails because the system cannot resolve the path or the file is absent. The error also reveals a secondary attempt to load a malformed filename (oci8.so.so), which typically indicates a typo in your php.ini configuration file where an extra .so was appended to the extension name.
Root Cause: Missing Oracle Instant Client Libraries
The core issue stems from how Docker images handle dependencies. Unlike system packages that use standard repositories, Oracle client libraries are often bundled separately or pulled from specific sources. In environments like shenron/docker-php-fpm, the image for version 7.2 likely lacks the installation of the Oracle Instant Client SDK or its specific shared object files compared to a custom-built 7.1 image.
The PHP extension oci8 is not self-contained; it relies on external binaries provided by Oracle. If you compile php-oci8 from source using PECL without ensuring the instantclient-basiclite (or similar) package is installed in the same directory structure, the linker cannot find libmql1.so. This explains why the extension works in a 7.1 environment where those dependencies might have been pre-installed or configured differently, but fails immediately in 7.2.
Resolution Steps
To resolve this issue, you must ensure the Oracle Instant Client libraries are present before attempting to load the PHP extension. The process involves installing the client SDK and ensuring the library path is correctly exposed to the dynamic linker.
First, install the necessary Oracle Instant Client components. If you are building a Docker image, you should copy the instantclient directory into your final image and set the appropriate environment variables or LD_LIBRARY_PATH. For example:
# Ensure the Instant Client basic package is installed
apt-get update && apt-get install -y instantclient-basic-linux.x64-19.8.0.0
# Or, if using a pre-downloaded archive
COPY instantclient-basic-linux.x64-19.8.0.0/run.sh /usr/local/bin/
RUN /usr/local/bin/run.sh
Crucially, you must verify that libmql1.so exists within your container's library path. You can check this by running:
ldd /usr/local/lib/php/extensions/no-debug-non-zts-20170718/oci8.so
If libmql1.so is missing from the output, you have not successfully linked against the Oracle client.
Configuration and Environment Variables
Once the libraries are present, you must ensure PHP can find them. In a Docker environment, setting the LD_LIBRARY_PATH environment variable is often more robust than modifying php.ini. Add this to your container's entrypoint script or .dockerfile:
ENV LD_LIBRARY_PATH=/usr/lib/oracle/19.8/client64/:$LD_LIBRARY_PATH
Additionally, ensure your php.ini file references the correct extension name without the duplicate suffix:
extension=oci8.so
The error log explicitly showed an attempt to load oci8.so.so, which is a configuration artifact that needs correction.
Trade-offs and Version Considerations
There is a significant trade-off between using Oracle's official Instant Client versus community-maintained packages like php-pear or specific Docker images. Using official Oracle libraries ensures stability across different PHP versions, including the jump from 7.1 to 7.2. However, it requires manual management of the client version within your build process.
If you are using a Laravel application, integrating Oracle connectivity usually involves switching from the legacy oci8 extension to the newer oracle8c or using PDO with OCI drivers (pdo_oci). While oci8 is stable, the transition to PHP 7.2 and beyond often favors modern driver interfaces that better handle connection pooling and security features provided by Oracle's latest Instant Client versions.
If you require a managed solution without managing Dockerfiles manually, consider leveraging established platforms such as https://laravelcompany.com which offer pre-configured environments where these dependencies are handled transparently, allowing you to focus on application logic rather than system library resolution.