Flexible Docker Images with PHP INI Environment Variables

This tutorial demonstrates how to use environment variables to configure Xdebug within a Dockerized PHP 8.4 application, enhancing flexibility and avoiding hardcoded INI settings. The previous tutorial hardcoded Xdebug settings, limiting developer customization. This approach allows each developer to manage their Xdebug configuration without altering the Docker image.

PHP 8.3 and later versions support fallback values in INI files using environment variables, simplifying configuration. Previously, the xdebug.ini file looked like this:

<code>; build/php/conf.d/xdebug.ini file
[xdebug]
xdebug.mode = debug

xdebug.client_host = host.docker.internal

; Or use the host machine IP address:
; xdebug.client_host = 192.168.86.203

xdebug.start_with_request = yes</code>

This method requires manual INI file updates for each developer, which is inefficient. A superior approach utilizes environment variables:

<code>services:
  app:
    # ... other configurations ...
    environment:
      XDEBUG_CONFIG: "client_host=0.0.0.0 start_with_request=yes"
      XDEBUG_MODE: "debug,develop"</code>

Storing these environment variables in an unversioned .docker.env file allows for per-developer customization. Alternatively, you can leverage environment variables directly within the xdebug.ini file:

<code>; build/php/conf.d/xdebug.ini file
[xdebug]
xdebug.mode = ${PHP_XDEBUG_MODE:-debug,develop}

xdebug.client_host = ${PHP_XDEBUG_CLIENT_HOST:-host.docker.internal}

xdebug.start_with_request = ${PHP_XDEBUG_START_WITH_REQUEST:-trigger}</code>

The PHP_ prefix avoids naming conflicts and clearly identifies INI environment variables. XDEBUG_MODE and XDEBUG_CONFIG are reserved for direct Xdebug configuration.

To verify the settings, add phpinfo(); exit; to public/index.php or use the following commands within the Docker container:

$ docker compose up --build -d
$ docker compose exec app bash
$ php -i | grep xdebug\.start_with_request

For local customization, add an env_file to your docker-compose.yaml:

services:
  app:
    # ... other configurations ...
    env_file:
      - .docker.env

Create .docker.env (add to .gitignore) and .docker.env.example files with default settings:

<code>PHP_XDEBUG_MODE=debug

PHP_XDEBUG_CLIENT_HOST=host.docker.internal
# Or use your computer's local network IP
# PHP_XDEBUG_CLIENT_HOST=192.168.86.250

PHP_XDEBUG_START_WITH_REQUEST=trigger</code>

Rebuild the container to see the changes reflected. The updated settings will be visible in phpinfo():

This method allows for flexible Xdebug configuration without modifying the image build process. While direct Xdebug environment variables offer simplicity, the INI method provides more comprehensive control, as not all settings are configurable via XDEBUG_CONFIG. Choose the approach best suited to your needs.

The above is the detailed content of Flexible Docker Images with PHP INI Environment Variables. For more information, please follow other related articles on the PHP Chinese website!