20-php — PHP-FPM + расширения + Composer
Ставит PHP-FPM с типовым набором расширений и Composer; рантайм для пресетов
laravelиwordpressкомандыmitdev app. ☐ опциональный модуль.
Зачем нужен
PHP — язык, на котором написаны Laravel, WordPress и множество других приложений. Модуль ставит PHP-FPM (FastCGI Process Manager — демон, который обрабатывает PHP-запросы и общается с веб-сервером через unix-сокет, то есть локальный файл-«разъём» вместо TCP-порта), набор расширений, нужных почти любому PHP-приложению, и Composer — менеджер зависимостей PHP.
В отличие от Node/Python/Go, для PHP-приложения не запускается отдельный процесс через PM2: nginx напрямую передаёт запросы в PHP-FPM по сокету. Одного демона PHP-FPM достаточно для всех PHP-сайтов на сервере.
Когда включать и когда не нужен
Включайте для развёртывания Laravel, WordPress или любого другого PHP-приложения (пресеты laravel, wordpress в mitdev app).
Не нужен, если PHP-приложений нет. WordPress вдобавок требует MySQL/MariaDB — mitdev отдельным модулем их не ставит, поэтому базу для WordPress поднимают через docker-compose в репозитории (или используют пресет docker).
Зависимости и требования
- Работает в связке с модулем
06-nginx— именно nginx принимает HTTP-запросы и передаёт их в PHP-FPM по сокету (шаблонtemplates/nginx/php.conf.template). Без nginx PHP-FPM работать будет, но снаружи сайт не откроется. - Для HTTPS — модуль
08-certbot. - База данных ставится отдельными модулями: PostgreSQL (
12-postgresql) для Laravel; для WordPress — MySQL/MariaDB своими силами (Docker). - Доступ к
getcomposer.orgдля установки Composer.
Что именно делает
Шаги module_install (файл modules/20-php.sh):
- Установка PHP-FPM и расширений.
- Debian/Ubuntu:
php-fpm php-cli php-common php-mysql php-pgsql php-mbstring php-xml php-curl php-zip php-gd php-bcmath php-intl php-redis. - RHEL/SUSE:
php php-fpm php-cli php-common php-mysqlnd php-pgsql php-mbstring php-xml php-gd php-bcmath php-intl. Ставится PHP версии по умолчанию для дистрибутива (например,php8.3на Ubuntu 24.04).
- Debian/Ubuntu:
- Включение и запуск PHP-FPM через systemd. Имя службы определяется автоматически:
php8.3-fpmна Debian/Ubuntu,php-fpmна RHEL. - Установка Composer официальным установщиком (с проверкой контрольной суммы) в
/usr/local/bin/composer. Если Composer уже есть — шаг пропускается. - Верификация и отметка модуля.
Расширения покрывают типовые нужды: работа с MySQL и PostgreSQL, многобайтовые строки (mbstring), XML, cURL, ZIP, изображения (gd), точная арифметика (bcmath), интернационализация (intl), Redis.
Файлы, службы и порты
| Путь / объект | Назначение | Права |
|---|---|---|
php-fpm-служба (php8.3-fpm / php-fpm) |
демон обработки PHP | systemd |
/run/php/php*-fpm.sock (Debian) |
unix-сокет FPM, через который nginx общается с PHP | владелец — www-data |
/run/php-fpm/*.sock (RHEL) |
то же на RHEL | системные |
/etc/php/ |
конфигурация PHP (пулы FPM, php.ini) |
root |
/usr/local/bin/composer |
Composer (менеджер зависимостей) | 755 |
/etc/nginx/sites-available/<app>.conf |
конфиг сайта с fastcgi_pass unix:<сокет> (создаёт mitdev app) |
root |
/var/lib/mitdev/state/php.done |
отметка, что модуль установлен | root |
PHP-FPM собственного TCP-порта не открывает — связь идёт по unix-сокету. Наружу торчит только nginx (80/443).
Настройка
Собственных переменных defaults.conf у модуля нет — ставится версия PHP по умолчанию дистрибутива, набор расширений фиксирован в коде модуля. Настройки PHP (лимиты памяти, размер загрузки и т.п.) правятся в /etc/php/*/fpm/php.ini и пулах /etc/php/*/fpm/pool.d/.
Как узнать версию PHP-FPM и её systemd-юнит:
php -v # версия PHP CLI
systemctl list-unit-files 'php*-fpm.service' # имя юнита FPM, напр. php8.3-fpm.service
systemctl status php8.3-fpm # состояние службы
ls /run/php/ # путь к сокету FPM
Как переопределить настройки
Модуль вопросов не задаёт и переменных не читает. Чтобы изменить поведение PHP:
# Установить модуль отдельно после первичной настройки:
sudo mitdev add php
# Поднять лимиты загрузки/памяти (пример; путь версии подставьте свой):
sudo nano /etc/php/8.3/fpm/php.ini # upload_max_filesize, post_max_size, memory_limit
sudo systemctl restart php8.3-fpm
# Nginx-шаблон для PHP уже поднимает client_max_body_size 64m — при загрузке
# больших файлов синхронно увеличьте и его, и php.ini.
Проверка, что всё работает
Автоматическая верификация проверяет наличие php, работу php -v и активность службы PHP-FPM.
Вручную:
php -v # версия PHP
composer --version # версия Composer
systemctl is-active php8.3-fpm # ожидается: active
ls -l /run/php/php*-fpm.sock # сокет существует
# Сквозная проверка через nginx (после mitdev app):
curl -I http://shop.example.com # ожидается ответ 200/302 от приложения
Развёртывание приложения на этом рантайме
Установлены модули php, nginx, для HTTPS — certbot; для Laravel — postgresql.
Laravel
# 1. Развернуть (пресет laravel):
sudo mitdev app laravel shop https://github.com/you/shop.git shop.example.com
Что произойдёт:
- репозиторий клонируется в
~deploy/apps/shop; - если есть
composer.json— выполняетсяcomposer install --no-interaction --no-dev --optimize-autoloader; - если есть
.env.exampleи нет.env— создаётся.env; - nginx настраивается по шаблону
php.conf.templateс корнем (root) в~deploy/apps/shop/public(Laravel отдаёт наружу именноpublic/),fastcgi_passна найденный сокет PHP-FPM; конфиг проверяетсяnginx -t; - предлагается выпустить SSL.
# 2. Настроить БД в .env Laravel (данные PostgreSQL — в /root/.mitdev-credentials):
sudo cat /root/.mitdev-credentials
sudo -u deploy nano ~deploy/apps/shop/.env
# DB_CONNECTION=pgsql
# DB_HOST=127.0.0.1 DB_PORT=5432
# DB_DATABASE=<db> DB_USERNAME=<user> DB_PASSWORD=<pass>
# 3. Ключ приложения и миграции:
sudo -u deploy bash -lc 'cd ~/apps/shop && php artisan key:generate && php artisan migrate --force'
# 4. Сертификат (если не выпустили при app):
sudo mitdev ssl shop.example.com [email protected]
# 5. Обновление после push:
sudo mitdev deploy shop
WordPress
WordPress требует MySQL/MariaDB, которую mitdev отдельным модулем не ставит. Практичный путь — база в контейнере, а PHP + nginx через пресет wordpress:
# 1. Развернуть WordPress (nginx + PHP-FPM, docroot — корень репозитория):
sudo mitdev app wordpress blog https://github.com/you/blog.git blog.example.com
# 2. Базу MySQL/MariaDB поднять рядом (docker-compose в репозитории), например:
# services:
# db:
# image: mariadb:11
# environment: { MARIADB_DATABASE: wp, MARIADB_USER: wp, MARIADB_PASSWORD: secret, MARIADB_ROOT_PASSWORD: rootsecret }
# ports: ["127.0.0.1:3306:3306"]
# и указать в wp-config.php DB_HOST=127.0.0.1.
# 3. Сертификат:
sudo mitdev ssl blog.example.com [email protected]
Логи PHP-приложения:
sudo tail -f /var/log/nginx/shop.error.log # ошибки nginx/FastCGI
sudo journalctl -u php8.3-fpm -f # журнал самого PHP-FPM
sudo tail -f ~deploy/apps/shop/storage/logs/laravel.log # лог Laravel (если включён)
Типовые задачи
# Узнать версию PHP-FPM и её юнит:
systemctl list-unit-files 'php*-fpm.service'
# Перезапустить PHP-FPM (после правки php.ini):
sudo systemctl restart php8.3-fpm
# Обновить зависимости приложения вручную:
sudo -u deploy bash -lc 'cd ~/apps/shop && composer install --no-dev --optimize-autoloader'
# Очистить и пересобрать кэш Laravel:
sudo -u deploy bash -lc 'cd ~/apps/shop && php artisan optimize:clear && php artisan optimize'
# Посмотреть включённые расширения:
php -m
# Обновить сам Composer:
sudo composer self-update
Частые ошибки
Симптом: nginx отдаёт 502 Bad Gateway.
Причина: PHP-FPM не запущен или nginx указывает на несуществующий сокет.
Решение: sudo systemctl restart php8.3-fpm; сверьте путь сокета в /etc/nginx/sites-available/<app>.conf с ls /run/php/.
Симптом: при развёртывании — «Сокет PHP-FPM не найден — nginx для PHP не настроен».
Причина: модуль php не установлен или FPM не запустился.
Решение: sudo mitdev add php, убедитесь, что служба активна, повторите mitdev app.
Симптом: Laravel показывает белый экран / 500.
Причина: нет ключа приложения, прав на storage/bootstrap/cache или неверный .env.
Решение: php artisan key:generate; sudo chown -R deploy:deploy ~deploy/apps/shop/storage; проверьте лог storage/logs/laravel.log.
Симптом: большой файл не загружается (413/ошибка).
Причина: лимиты client_max_body_size (nginx) и upload_max_filesize/post_max_size (PHP) малы.
Решение: увеличьте оба и перезапустите nginx и php-fpm.
Безопасность и продакшен
- Composer в продакшене — только
--no-dev(dev-зависимости не попадают на сервер). - nginx-шаблон для PHP уже запрещает доступ к
.env,composer.json/lock,package.jsonи скрытым файлам — не ослабляйте эти правила. - Для Laravel корень сайта —
public/, а не корень репозитория: так исходники и.envнедоступны из веба (mitdev настраивает это автоматически). - Держите PHP на поддерживаемой версии и ставьте обновления безопасности дистрибутива.
- Не открывайте базу данных наружу — приложение ходит к ней по
127.0.0.1.
Откат и удаление
module_rollback (при сбое): останавливает и отключает PHP-FPM, удаляет php-fpm php-cli php-common и Composer.
Ручное удаление:
sudo mitdev remove php # PHP и Composer удалены, /etc/php сохранён
sudo mitdev remove php --purge # плюс удаляется /etc/php (вся конфигурация)
module_remove: останавливает PHP-FPM, удаляет пакеты PHP (на Debian — apt-get purge 'php*') и Composer. Конфигурация в /etc/php по умолчанию сохраняется; удаляется только с --purge. Каталоги приложений в ~deploy/apps не трогаются.
См. также
- ../COMMANDS.md — команды
mitdev app laravel|wordpress,deploy,ssl. - ../RECIPES.md — рецепт «Laravel + PostgreSQL».
06-nginx.md— reverse-proxy / веб-сервер (в связке с PHP-FPM).08-certbot.md— выпуск SSL-сертификатов.