Гнучкі Docker-образи з PHP INI змінними середовища

Нещодавно я публікував статтю про те, як налаштувати Xdebug з Docker та PHP 8.4, щоб продемонструвати, наскільки просто отримати з'єднання Xdebug. У тому навчальному посібнику я зафіксував налаштування INI, аби зосередитися на налаштуванні Xdebug. В реальному застосунку, однак, важливо, щоб Docker-образи були гнучкими, щоб кожен розробник міг налаштувати свої параметри без впливу на конфігурацію образу.

У цьому дописі я покажу, як використовувати змінні середовища для підвищення гнучкості ваших образів. Починаючи з версії 8.3, PHP підтримує значення за замовчуванням у синтаксисі змінної середовища INI, що дозволяє створити більш чисту конфігурацію INI.

Для порівняння, наш файл xdebug.ini виглядав так:

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

xdebug.client_host = host.docker.internal

; Або ви можете використати IP-адресу хосту:
; xdebug.client_host = 192.168.86.203

xdebug.start_with_request = yes

Якщо один з ваших колег не хоче, щоб Xdebug запускалася за замовчуванням, йому доведеться змінювати файл INI і або комітити зміни, або просто скасовувати їх. Це не найкраще рішення.

Це не найзручніший підхід, особливо з огляду на те, що PHP тепер підтримує значення за замовчуванням у INI-файлах. Перед тим як перейти до його налаштування, ми можемо безпосередньо конфігурувати Xdebug за допомогою змінних середовища. Наступний код є еквівалентним нашому файлу xdebug.ini:

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"

Якщо перемістити значення змінних середовища в невідстежуваний ENV-файл, кожен розробник зможе самостійно налаштовувати параметри Xdebug. Інший спосіб конфігурації Xdebug — через INI, як ми робили раніше, але за допомогою змінних середовища:

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

Я префіксував ці змінні з PHP_, щоб уникнути конфліктів і швидко їх впізнавати. Наприклад, XDEBUG_MODE зарезервовано для безпосередньої конфігурації Xdebug, тому, якщо ми хочемо налаштувати його через INI-змінну, потрібно вибрати унікальне ім'я.

Якщо ви перезапустите образ Docker, ви зможете перевірити ці налаштування, додавши phpinfo(); exit; на початок public/index.php або підключившись до контейнера:

$ docker compose up --build -d
$ docker compose exec app bash

# В контейнері
$ php -i | grep xdebug\.start_with_request
xdebug.start_with_request => trigger => trigger

Якщо ви хочете спробувати налаштувати ці значення локально, додайте наступне до вашого compose.yaml:

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

Потім створіть файли .docker.env та .docker.env.example в кореневій директорії вашого проєкту. Додайте до прикладового файлу розумні значення за замовчуванням, а також внесіть .docker.env у ваш .gitignore. Ось приклад вмісту:

PHP_XDEBUG_MODE=debug

PHP_XDEBUG_CLIENT_HOST=host.docker.internal
# Або використайте локальну IP-адресу комп'ютера
# PHP_XDEBUG_CLIENT_HOST=192.168.86.250

PHP_XDEBUG_START_WITH_REQUEST=trigger

Вам потрібно буде відновити контейнер, щоб побачити оновлені значення ENV, але, як тільки ви це зробите, ви повинні побачити, що ваші налаштування ENV прийняті:

Отже, ваші INI налаштування легко змінюються без впливу на файли збирання образу.

Тепер ви можете зробити свої Docker-образи гнучкими, використовуючи змінні середовища з налаштуваннями INI. Я також показав, як використовувати вбудовані змінні середовища Xdebug для налаштування, якщо ви надаєте перевагу простоті. Однак не всі налаштування можуть бути визначені через змінну середовища XDEBUG_CONFIG, тому обирайте спосіб конфігурації, який підходить саме вам!