PHPTime

PHP в Docker: образ, nginx, PHP-FPM и docker compose

Официальный образ PHP запускает скрипты из командной строки, обслуживает сайт через Apache или предоставляет PHP-FPM для связки с nginx. Ниже — рабочий проект на Docker Compose, который можно запустить локально, а затем взять за основу для сборки образов приложения.

Docker PHP: какой образ выбрать

У официального образа php есть несколько вариантов. Суффикс определяет способ запуска PHP. Если нужен nginx, выбирайте fpm: nginx принимает HTTP-запрос, а PHP-FPM выполняет скрипт и возвращает результат по протоколу FastCGI.

ОбразКогда использоватьЧто запускается
php:8.5-cliКонсольные команды, тесты и воркерыPHP CLI
php:8.5-apacheСайт на Apache в одном контейнереApache с модулем PHP
php:8.5-fpmСайт на nginx с отдельным контейнером PHPPHP-FPM, FastCGI на порту 9000

Для первого запуска удобен Debian-вариант без суффикса -alpine. В Alpine используется musl, а системные пакеты устанавливаются через apk. При переходе на Alpine проверьте зависимости расширений и совместимость сторонних бинарников. Для воспроизводимой сборки указывайте точную версию базового образа или его digest и обновляйте её вместе с патчами безопасности.

Docker PHP-FPM: Dockerfile и расширения

Создайте в корне проекта Dockerfile и php.ini. Рядом будут compose.yaml, nginx.conf и каталог public с файлом index.php. Пример собирается на PHP 8.5. Аргумент PHP_VERSION позволяет проверить ту же сборку на PHP 8.3 и 8.4.

Dockerfile
ARG PHP_VERSION=8.5
FROM php:${PHP_VERSION}-fpm

# pdo_mysql нужен приложению для подключения к MySQL через PDO.
RUN docker-php-ext-install -j$(nproc) pdo_mysql

WORKDIR /var/www/app
COPY php.ini /usr/local/etc/php/conf.d/zz-app.ini
COPY public/ ./public/

docker-php-ext-install собирает расширения из исходников PHP и подключает их. Для pdo_mysql в этой сборке достаточно встроенного драйвера mysqlnd. Расширения с внешними зависимостями требуют системных библиотек и заголовков, например intl требует ICU. Для PECL-расширений фиксируйте версию пакета, совместимую с выбранной веткой PHP, и подключайте его через docker-php-ext-enable. Пакеты вида php8.x-* из системного репозитория рассчитаны на PHP из этого же репозитория.

Настройки PHP для разработки

ini
; Ошибки записываются в журнал контейнера.
display_errors = Off
log_errors = On
error_log = /proc/self/fd/2
error_reporting = E_ALL

memory_limit = 128M

; При разработке PHP должен замечать изменения файлов.
opcache.enable = 1
opcache.validate_timestamps = 1
opcache.revalidate_freq = 0

На PHP 8.3 и 8.4 добавьте opcache в список расширений в строке RUN, чтобы собрать и включить его. Начиная с PHP 8.5 OPcache входит в PHP и загружается автоматически. При публикации неизменяемых образов можно выключить opcache.validate_timestamps, если новый релиз заменяет контейнеры PHP-FPM. При обновлении файлов в работающем контейнере с этой настройкой в памяти может остаться предыдущая версия скриптов.

nginx и PHP-FPM: настройки FastCGI

Сохраните конфигурацию как nginx.conf. nginx отдаёт статические файлы из public, а остальные запросы направляет в index.php. Только этот файл передаётся на выполнение в PHP-FPM. Если приложению нужны другие публичные PHP-скрипты, добавьте для них отдельные правила.

nginx
server {
    listen 80;
    server_name _;
    root /var/www/app/public;
    index index.php;

    location / {
        # Сохраняем параметры запроса при переходе к index.php.
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /index.php {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass php:9000;
    }

    location ~* \.php(?:/|$) {
        return 404;
    }

    location ~ /\. {
        deny all;
    }
}

php в fastcgi_pass — имя сервиса в Compose. Внутри контейнера nginx адрес 127.0.0.1 указывает на сам nginx. Порт 9000 доступен в общей сети Compose, поэтому публиковать его на хосте не требуется. FastCGI использует собственный протокол. HTTP-клиентом проверяйте порт nginx.

SCRIPT_FILENAME передаёт PHP-FPM абсолютный путь к скрипту. nginx использует тот же каталог для try_files, поэтому в примере public доступен обоим контейнерам по пути /var/www/app/public. Корнем сайта служит именно public. Конфигурацию приложения, зависимости и приватные данные храните за его пределами.

Docker Compose: запуск и проверка проекта

В примере оба сервиса читают public с хоста. Можно менять файлы приложения и сразу проверять результат без пересборки. Порт nginx открыт на loopback-интерфейсе хоста, поэтому сайт доступен локально на порту 8080.

YAML
services:
  nginx:
    image: nginx:stable
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      # nginx читает конфигурацию и публичные файлы.
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./public:/var/www/app/public:ro
    depends_on:
      - php

  php:
    build:
      context: .
      args:
        PHP_VERSION: "8.5"
    volumes:
      - ./public:/var/www/app/public:ro

Создайте public/index.php. Ответ покажет версию PHP и имя SAPI, через который обработан запрос. Для связки nginx и PHP-FPM ожидается fpm-fcgi.

PHP
<?php
declare(strict_types=1);

// Диагностический ответ для локальной проверки.
header('Content-Type: application/json; charset=utf-8');

echo json_encode(
    ['php' => PHP_VERSION, 'sapi' => PHP_SAPI],
    JSON_THROW_ON_ERROR,
);

Запустите сервисы из корня проекта. Откройте в браузере локальный порт 8080 и проверьте JSON-ответ. Команда php -m внутри контейнера показывает расширения CLI. Ответ от index.php подтверждает, что запрос прошёл через nginx и FastCGI.

Shell
# Проверяем итоговую конфигурацию и запускаем проект.
docker compose config --quiet
docker compose up -d --build
docker compose ps

# Проверяем конфигурацию nginx, модули и журналы.
docker compose exec nginx nginx -t
docker compose exec php php -m
docker compose logs --tail=50 nginx php

depends_on в короткой форме задаёт порядок запуска, но не ждёт готовности PHP-FPM. Если при автоматическом запуске важно дождаться готовности, добавьте healthcheck, который проверяет FastCGI, и зависимость с условием service_healthy. Пересоздание контейнера PHP может изменить его IP. Если nginx продолжает обращаться по старому адресу, перезагрузите его конфигурацию. Для автоматического обновления адреса настройте динамическое DNS-разрешение upstream с учётом используемой версии nginx.

PHP 8.3, 8.4 и 8.5: что меняется для проекта

  • PHP 8.3. Подходит как минимальная поддерживаемая версия, если проект и зависимости рассчитаны на неё. Можно использовать типизированные константы классов и атрибут #[Override]. В конце 2026 года ветка получает исправления безопасности.
  • PHP 8.4. Добавляет хуки свойств, асимметричную видимость свойств и функции array_find() и array_any(). Неявно допускающие null параметры вроде string $name = null устарели. Объявляйте их явно как ?string $name = null.
  • PHP 8.5. Добавляет оператор конвейера |> и функции array_first() и array_last(). Учитывайте встроенный OPcache при переносе Dockerfile со старой ветки. Если один код должен запускаться и на PHP 8.3, держите общий синтаксис в пределах возможностей 8.3.

Версию PHP согласуйте с ограничением require.php и требованиями ext-* в composer.json. Собирайте и тестируйте контейнер на целевой ветке. Когда Composer запускается в отдельном сборочном слое, проверьте итоговое окружение командой composer check-platform-reqs --no-dev там, где доступны Composer и тот же набор PHP-расширений, что в рабочем образе. declare(strict_types=1) в новых файлах делает вызовы со скалярными типами строже. Данные из HTTP-запросов всё равно нужно явно проверять и приводить к нужным типам.

Типичные ошибки nginx, PHP-FPM и Docker Compose

  • 502 Bad Gateway. Посмотрите docker compose ps и журналы обоих сервисов. При Connection refused проверьте, запущен ли PHP-FPM и слушает ли он порт 9000. При host not found in upstream сверьте имя сервиса в fastcgi_pass и общую сеть контейнеров.
  • 404 или Primary script unknown. Проверьте наличие файла по пути из SCRIPT_FILENAME в контейнере PHP. Затем проверьте путь в контейнере nginx: try_files может вернуть 404 ещё до обращения к FPM. Учитывайте регистр имён файлов при переносе проекта с Windows или macOS на Linux.
  • Could not find driver. Для PDO-подключения к MySQL нужен pdo_mysql, к PostgreSQL — pdo_pgsql. После изменения Dockerfile выполните docker compose up -d --build и проверьте расширения в запущенном сервисе.
  • В контейнере пропал vendor. Если смонтировать корень проекта поверх /var/www/app, файлы из образа в этом каталоге будут скрыты содержимым хоста. Установите зависимости в смонтированный проект или оставьте vendor в образе и ограничьте bind mount каталогами, которые редактируете.
  • Permission denied. У пользователя воркера PHP-FPM должны быть права на чтение файлов и доступ к родительским каталогам. Для кэша, сессий или загрузок выделите отдельные каталоги с нужным владельцем и правами на запись. Для исходников достаточно чтения.
  • 413 или 504. Для загрузок согласуйте client_max_body_size в nginx с upload_max_filesize и post_max_size в PHP. Оставьте запас в post_max_size под поля и служебные данные формы. При 504 сначала измерьте время обработки и проверьте зависимые сервисы. fastcgi_read_timeout задаёт время ожидания между чтениями ответа от FPM.

Чек-лист перед запуском PHP в Docker

  1. Укажите ветку PHP и соберите образ с нужными расширениями. Проверьте запуск приложения и требования Composer на этой версии.
  2. Откройте внешний HTTP-порт у nginx. Оставьте порт PHP-FPM в сети контейнеров и проверьте путь SCRIPT_FILENAME.
  3. Для production уберите локальные монтирования исходников. Соберите образ nginx с публичными файлами из того же релиза, что и образ PHP. Исключите диагностический ответ с версией PHP из публичного приложения.
  4. Оставьте display_errors = Off, проверьте журналы PHP-FPM и nginx. Настройте pm.max_children по доступной памяти и измеренному потреблению воркера под нагрузкой.
  5. После запуска проверьте через nginx обычную страницу приложения, статический файл и отсутствующий маршрут. Для приложений с загрузкой файлов дополнительно проверьте допустимый размер файла и права на запись.

Частые вопросы

Какой Docker-образ PHP выбрать для nginx?

Используйте официальный php:8.5-fpm или поддерживаемую ветку, на которую рассчитано приложение. nginx запускается отдельным сервисом и передаёт PHP-запросы по FastCGI на порт 9000.

Нужно ли пробрасывать порт 9000 у PHP-FPM в Docker Compose?

Для nginx и PHP-FPM в одной сети Compose достаточно fastcgi_pass php:9000, где php — имя сервиса. На хосте публикуется HTTP-порт nginx.

Почему nginx возвращает 502 после запуска Docker Compose?

Проверьте, запущен ли PHP-FPM, совпадает ли имя сервиса в fastcgi_pass и доступны ли оба контейнера в одной сети. Если ошибка возникает только при старте, проверьте готовность FPM и при необходимости настройте healthcheck.

Справка по теме

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин