configure: error: Package requirements (oniguruma) were not met
When attempting to build a Docker image for a Laravel application, you might encounter the following error during the docker-php-ext-install step:
configure: error: Package requirements (oniguruma) were not met:
No package 'oniguruma' found
This failure halts the build process immediately, resulting in a non-zero exit code. The root cause is straightforward but often overlooked: the pdo_mysql extension requires the oniguruma library for regular expression handling. While this might seem like an obscure dependency, it is a hard requirement for the MySQL driver to function correctly within PHP.
The error message explicitly suggests two paths forward: either locate the package via pkg-config, or bypass the automatic detection by setting specific environment variables (ONIG_CFLAGS and ONIG_LIBS). In the context of Dockerizing PHP applications, the first approach is rarely viable because base images like php:7 (or modern equivalents like php:8) do not include the development libraries for oniguruma in their default state. Relying on system-wide installs outside the build stage or hoping a library appears magically after running composer install will only lead to runtime failures where your application cannot connect to the database.
To resolve this, you must install the development headers for oniguruma alongside your standard PHP extensions. The most robust solution involves adding a specific line to your Dockerfile before executing docker-php-ext-install. Since the php:7 tag is deprecated and lacks modern security patches, consider upgrading to a supported LTS version like php:8.2-fpm or php:8.3-cli, but the fix remains consistent across versions.
Here is how you should adjust your Dockerfile installation sequence:
FROM php:8.2-cli
# Install system dependencies, including oniguruma development headers
RUN apt-get update && apt-get install -y \
gnupg \
curl \
git \
unzip \
libonig-dev \
default-mysql-client \
&& rm -rf /var/lib/apt/lists/*
# Install Composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
# Install PHP extensions with the required dependencies present
RUN docker-php-ext-install pdo_mysql mbstring pdo_sqlite \
&& pecl install redis \
&& docker-php-ext-enable redis
WORKDIR /app
COPY . .
RUN composer install --no-dev --optimize-autoloader
CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8000"]
Notice the inclusion of libonig-dev in the apt-get install command. This package provides the header files and libraries that the PHP build script needs to compile pdo_mysql. Without it, the configure script fails to find the required library, triggering the error you observed. Additionally, I have switched the base image tag to a modern supported version and included default-mysql-client, which is often helpful for CLI tools that need to interact with MySQL during the build process.
Another common pitfall involves the order of operations. You might be tempted to install the library after copying your application code or running composer commands, but extension building must happen while the base image environment is clean and dependencies are fresh. Attempting to apt-get install inside a container that has already been built partially can lead to broken package states if the layer cache is not handled correctly with --no-cache.
If you are using a multi-stage build, ensure that the library is installed in your intermediate stage where you compile the extensions, rather than trying to inject it into the final production image. The production image should generally be as minimal as possible, containing only the compiled binaries and your application code.
For more advanced scenarios involving custom PHP versions or Alpine-based images (like php:alpine), you would need to manually download the oniguruma source, compile it, and set the environment variables mentioned in the error message. However, for standard Debian-based images, simply installing libonig-dev is the industry-standard fix.
If you require further guidance on setting up complex PHP environments or optimizing your Laravel deployment pipeline, you can refer to resources like https://laravelcompany.com. They often provide detailed documentation on production-ready configurations that go beyond basic Dockerfile examples.
