Настройка локального сервера на PHP с Docker для разработки
Я Равиль Зарипов, разработчик из Алматы. В своей практике я создаю приложения для Android, iOS, Windows, macOS и Linux, работаю с Delphi, FireMonkey, Kotlin, Swift, PHP и базами данных. Для веб-части проектов локальная среда должна воспроизводить серверное окружение, не зависеть от глобальных настроек компьютера и легко переноситься между рабочими машинами.
Docker позволяет собрать PHP, веб-сервер и СУБД в отдельных контейнерах. Зависимости фиксируются в образе, конфигурация хранится рядом с исходным кодом, а запуск сводится к одной команде. Такой подход особенно удобен при параллельной работе над несколькими проектами или при переходе на другую операционную систему.
Сравнение способов запуска
Перед настройкой окружения полезно сопоставить Docker Compose со встроенным PHP-сервером и виртуальными машинами. Важны скорость запуска, изоляция зависимостей и соответствие рабочей среде сервера. Встроенный PHP-сервер прост, но не воспроизводит полноценную архитектуру, а Vagrant требует отдельной виртуальной машины и дополнительных ресурсов.
| Способ | Скорость запуска | Изоляция | Основное назначение |
|---|---|---|---|
| Docker Compose | Высокая после сборки образов | Полная для процессов и зависимостей | Единое окружение для всех участников проекта |
| Встроенный PHP-сервер | Очень высокая | Минимальная | Быстрая проверка небольших скриптов |
| Vagrant | Средняя | Полная внутри виртуальной машины | Точное воспроизведение серверной конфигурации |
Docker Compose занимает промежуточное положение: контейнеры работают быстрее виртуальных машин, но дают больше возможностей, чем локальный сервер PHP. При этом веб-сервер, интерпретатор и база данных остаются раздельными сервисами с собственными параметрами.
Подготовка проекта и Docker
На Linux установите Docker Engine, а на Windows и macOS — Docker Desktop. В обоих случаях должен быть доступен плагин Compose второй версии, который запускается командой docker compose. Проверить готовность окружения можно командой docker compose version, не создавая отдельные файлы для каждого сценария.
В корне проекта подготовьте compose.yaml, Dockerfile, каталог с настройками Nginx и файл .env с параметрами подключения к базе данных. Значения для локальной разработки можно задать в .env, а этот файл добавить в .gitignore и .dockerignore, чтобы исключить пароли и служебные данные из репозитория и образа. Шаблон допустимых настроек удобно хранить отдельно под именем .env.example.
В образе указывают точную версию PHP и необходимые расширения. Сборку лучше начинать с официального образа php-fpm, добавляя Composer и системные библиотеки через отдельные слои. Такой Dockerfile выглядит достаточно компактно:
FROM php:8.3-fpm-bookworm
RUN apt-get update \
&& apt-get install -y git unzip libicu-dev libpq-dev \
&& docker-php-ext-install -j"$(nproc)" intl opcache pdo_mysql pdo_pgsql \
&& rm -rf /var/lib/apt/lists/*
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html
COPY composer.json composer.lock ./
RUN composer install --no-dev --prefer-dist --no-interaction --no-scripts
COPY . .
EXPOSE 9000
Запуск PHP, Nginx и базы данных
Типовая схема состоит из трёх сервисов: PHP-FPM обрабатывает код, Nginx принимает запросы, а PostgreSQL хранит данные. Наружу публикуется только порт Nginx; PHP и СУБД остаются доступными внутри сети Compose по именам app и db. Это исключает случайные подключения к контейнерным службам с других компьютеров.
Следующая конфигурация описывает зависимости, тома и проверку готовности базы данных:
services:
app:
build:
context: .
volumes:
- .:/var/www/html
- vendor:/var/www/html/vendor
environment:
DB_HOST: db
DB_PORT: "5432"
DB_DATABASE: ${DB_DATABASE}
DB_USER: ${DB_USER}
DB_PASSWORD: ${DB_PASSWORD}
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
environment:
POSTGRES_DB: ${DB_DATABASE}
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_USER} -d ${DB_DATABASE}"]
interval: 5s
timeout: 5s
retries: 10
web:
image: nginx:1.27-alpine
ports:
- "8080:80"
volumes:
- .:/var/www/html:ro
- ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
- app
volumes:
db_data:
Nginx должен передавать запросы PHP-FPM по внутреннему имени контейнера. Конфигурация размещается в docker/nginx/default.conf и подключается к сервису web через подготовленный том:
server {
listen 80;
server_name localhost;
root /var/www/html;
index index.php index.html;
location / {
try_files $uri /index.php$is_args$args;
}
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /var/www/html$fastcgi_script_name;
fastcgi_pass app:9000;
}
}
После создания файлов команда docker compose up -d --build запускает все службы в фоне. Проверка состояния выполняется через docker compose ps, а приложение открывается по адресу localhost:8080. Если нужно наблюдать за обработкой запросов, журналы Nginx и PHP-FPM доступны командой docker compose logs -f web app.
Composer, расширения и конфигурация
Зависимости PHP устанавливаются внутри контейнера командой docker compose exec app composer install. Она учитывает composer.lock, сохраняет одинаковый набор пакетов у всей команды и позволяет запускать привычные сценарии Composer без локального PHP. Отдельный том vendor не позволяет файлам зависимостей из операционной системы перекрыть содержимое контейнера.
Расширения pdo_pgsql, pdo_mysql, intl и opcache включаются ещё на этапе сборки образа. Их наличие проверяется командой docker compose exec app php -m, а параметры PHP можно передавать через дополнительные файлы в каталоге conf.d. Версии расширений и PHP стоит согласовыть с сервером, поскольку различия в драйверах способны вызывать ошибки, которые не возникают на локальной машине.
Для проверки сценария входа полезен материал о CrocoPlay Login: контейнерное окружение позволяет отдельно прогнать обработчики входа и обратного вызова, не затрагивая общую инфраструктуру команды. Переменные для внешних сервисов также задаются через окружение контейнера, а не сохраняются непосредственно в коде.
Базы данных и отладка
PostgreSQL доступна приложению по адресу db и порту 5432. В PHP-коде следует использовать эти значения вместо localhost, поскольку последний укажет на сам контейнер приложения. Данные сохраняются в именованном томе db_data, поэтому перезапуск или пересборка контейнера не удаляет локальную базу. Прямой порт PostgreSQL публиковать не требуется, если отладка выполняется внутри Compose.
Состояние служб и журналы помогают быстро локализовать ошибку:
docker compose ps
docker compose logs -f web app
docker compose exec db psql -U app -d app
docker compose exec app php -m
Миграции выполняются из контейнера приложения. В проектах на Laravel это может быть команда php artisan migrate, а в Symfony — php bin/console doctrine:migrations:migrate. Перед запуском миграций убедитесь, что контейнер db достиг состояния healthy, иначе соединение будет отклонено из-за преждевременного старта зависимости.
Для пошаговой отладки к образу development-профиля можно добавить Xdebug с режимом debug. Точку подключения следует открывать только на время сеанса и не пробрасывать её на внешний интерфейс. Значения Xdebug, настройки приложения и параметры базы передаются через .env, что позволяет менять режим без изменения Dockerfile.
Рабочий процесс и перенос проекта
Ежедневный запуск сводится к обновлению образов, выполнению зависимостей и открытию страницы проекта:
docker compose up -d --build
docker compose exec app composer install
docker compose exec app php bin/console doctrine:migrations:migrate
Изменения в PHP-файлах сразу видны благодаря монтированию каталога проекта. Контейнер приложения перезапускается командой docker compose restart app, а полная пересборка требуется только после изменения Dockerfile или списка расширений. Благодаря этому цикл проверки кода не зависит от настроек PHP, установленных в системе.
Остановка命令 docker compose down сохраняет данные в томах. Вариант docker compose down -v удаляет базу вместе с другими именованными томами, поэтому перед ним стоит создать резервную копию командой docker compose exec db pg_dump -U app app > backup.sql. Изменение пароля в .env также не обновляет существующего пользователя PostgreSQL: для новой базы потребуется новое хранилище или отдельная команда смены пароля.
В долгосрочной перспективе полезно фиксировать версии образов и проверять их совместимость с сервером. Файлы Dockerfile, compose.yaml и .env.example можно хранить в репозитории рядом с кодом, а типовые команды публиковать в блоге и GitHub. Одинаковая конфигурация на разных операционных системах сокращает различия между рабочим окруждением и развёртыванием, сохраняя привычный процесс разработки на PHP.