Flexible Docker Images with PHP INI Environment Variables

I recently posted about Get Xdebug Working With Docker and PHP 8.4 to show you how easy it is to get an Xdebug connection working. In that tutorial, I hard-coded INI settings to keep the tutorial focused on setting up Xdebug. In a real application, you want your Docker images to be flexible so each developer can configure their own settings without affecting the image configuration.

In this post, I'll show you how to use environment variables to make your images super flexible. As of v8.3, PHP supports fallback values with the INI environment variable syntax, so we can really make our INI configuration clean.

If you reference the previous tutorial, our xdebug.ini file looked like the following snippet:

; 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

If another developer on your team doesn't want to start Xdebug by default, they'd have to update the INI file, and either commit the change or just revert it. Gross.

That is no way to live, especially since PHP now supports default fallback values in INI files. Before we get to that, we could also configure Xdebug directly with environment variables. The following is equivalent to our xdebug.ini file:

services:
  app:
    build:
      context: .
      dockerfile: build/Dockerfile
      target: development
    ports:
      - "8080:80"
    volumes:
      - .:/srv/app
    environment:
      XDEBUG_CONFIG: "client_host=0.0.0.0 start_with_request=yes"
      XDEBUG_MODE: "debug,develop"

If we moved the environment values to an unversioned ENV file, each developer could manage Xdebug settings locally. Another way to configure Xdebug is through INI like we initially did, but using envrionment variables:

; 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}

I've prefixed these variables with PHP_ to avoid conflicts and quickly recognize which ENV values were meant to be used with INI configuration. For example, XDEBUG_MODE is reserved for Xdebug configuration directly, so if we want to configure it via our INI ENV variable we need a unique name.

If you restart the Docker image, you can verify these settings by adding phpinfo(); exit; to the top of public/index.php or connect to the container:

$ docker compose up --build -d
$ docker compose exec app bash
 
# In the container
$ php -i | grep xdebug\.start_with_request
xdebug.start_with_request => trigger => trigger

If you want to try customizing these values locally, add the following to your compose.yaml file:

services:
  app:
    build:
      context: .
      dockerfile: build/Dockerfile
      target: development
    ports:
      - "8080:80"
    volumes:
      - .:/srv/app
+    env_file:
+      - .docker.env

Then, create a .docker.env and .docker.env.example file in the root of your project. Add sensible defaults to the example file and add .docker.env to your .gitignore file. Here's an example of the contents:

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

You will need to recreate the container to see the updated ENV values, but once you do, you should see your ENV settings take effect:

And that's it, your INI settings are easy to modify without affecting the image build files.

You can now make your Docker images flexible using environment variables with INI settings. I also showed you how to use Xdebug's built-in environment variables to configure things if you prefer simplicity. However, not all settings can be set via the XDEBUG_CONFIG environment, so use the method of configuration that works best for you!