Быстрый локальный веб‑сервер в PHP

О чём эта статья

Эта статья объясняет, как быстро запустить встроенный сервер PHP, какие есть параметры и ограничения, как подключить роутер‑скрипт, как распознать сервер из кода, и какие есть безопасные практики при тестировании на локальной сети. Включены чек‑листы, критерии приёмки, сценарии тестирования и рекомендации по безопасности.

Important: встроенный сервер предназначен только для разработки и тестирования. Не экспонируйте его в интернет или на общедоступные сети без дополнительной защиты.

Быстрые ссылки

• Использование встроенного сервера
• Запуск сервера
• Разрешение удалённого доступа
• Поведение при отсутствии URI (fallback)
• Использование router‑скрипта
• Определение встроенного сервера из PHP‑кода
• Обработка нескольких запросов одновременно
• Рекомендации по безопасности и сценарии использования
• Критерии приёмки, чек‑листы и тесты
• Краткое резюме

Использование встроенного сервера

Встроенный сервер PHP — это удобный инструмент для локальной разработки и тестирования. Он доступен начиная с PHP 5.4 и есть во всех последующих версиях. Сервер запускается прямо из каталога проекта и не требует настройки виртуального хоста.

Определение: встроенный сервер — это лёгкий HTTP‑сервер, интегрированный в интерпретатор PHP. Он служит только для разработки.

Важно: сервер не предназначен для продакшен‑нагрузок и не заменяет Apache, NGINX или полноценные промышленные серверы по безопасности и гибкости конфигурации.

Запуск сервера

Чтобы запустить сервер, передайте флаг -S исполняемому файлу php:

$ php -S localhost:8080

После запуска вы увидите сообщение вроде:

[Fri Jun 10 16:00:00 2022] PHP 8.1.5 Development Server (http://localhost:8080) started

Адрес и порт задаются в аргументе. Пример выше открывает порт 8080 на localhost. Затем посетите http://localhost:8080 в браузере — сервер будет отдавать файлы из текущей рабочей директории и исполнять PHP‑скрипты.

Если вы хотите, чтобы корневой документ находился за пределами рабочей директории, используйте флаг -t:

$ php -S localhost:8080 -t /home/$USER/public_docs

В этом случае документ‑рут будет указывать на /home/$USER/public_docs.

Поддержка: держите терминал открытым. Ctrl+C завершит сервер. Каждый входящий запрос логируется в терминал вместе с методом и URI. Необработанные ошибки PHP также будут видны в логах.

Разрешение удалённого доступа

По умолчанию сервер слушает только localhost. Чтобы принимать подключения с других устройств в сети, привяжите сервер к 0.0.0.0:

$ php -S 0.0.0.0:8080

Важно: это делает ваш сервер доступным в локальной сети. Не открывайте порт в интернет и используйте удалённый доступ только при необходимости (например, тестирование на мобильном устройстве). Проверьте правила брандмауэра и маршрутизации вашего компьютера.

Поведение при отсутствии URI (Request fallback matching)

Если входящий запрос не содержит компонент URI (например, запрос корневого пути /), PHP в документ‑руте ищет index.php или index.html. Если эти файлы отсутствуют, сервер поднимается вверх по дереву папок в поисках index в родительских директориях. Такое поведение может привести к неявной отдаче содержимого из родительских директорий, если вы не определили явный документ‑рут.

Когда запрос содержит URI (например, /file), сервер вернёт статический файл только при точном совпадении пути в документ‑руте; иначе — 404 Not Found. Для большинства широко используемых расширений PHP автоматически установит заголовок Content‑Type в соответствующий MIME‑тип.

Совет: всегда указывайте явный документ‑рут (-t) и проверяйте, какие файлы доступны, чтобы избежать случайной публикации конфиденциальных файлов из родительских директорий.

Использование router‑скрипта

Вы можете передать имя PHP‑файла при запуске сервера, чтобы этот файл вызывался при каждом запросе. Это позволяет реализовать front‑controller и сложную динамическую маршрутизацию:

$ php -S localhost:8080 router.php

Пример простого router.php:

Если ваш роутер возвращает false, встроенный сервер попытается отдать статический файл, соответствующий исходному URI. Это удобно для комбинированных приложений: динамические маршруты для API и контроллеров, статические файлы для ассетов.

Пример смешанного поведения:

Совет: в router‑скрипте делайте минимальную обработку и быстро возвращайте ответ или false, чтобы не блокировать другие запросы.

Определение встроенного сервера из PHP‑кода

Если в коде нужно отличить выполнение под встроенным сервером от других SAPI, используйте php_sapi_name():

if (php_sapi_name() === "cli-server") {
    // Выполняется под встроенным сервером
    enable_development_mode();
}

Определение: SAPI (Server Application Programming Interface) — интерфейс, через который PHP взаимодействует с окружением (CLI, FPM, Apache модуль и т.д.).

Применение: это позволяет активировать дополнительные механизмы отладки или mock‑поведение только в локальной среде.

Обработка нескольких запросов одновременно

По умолчанию встроенный сервер работает в одном процессе и обрабатывает запросы синхронно. Это означает: пока один запрос выполняется, другие ждут. Это ещё одна причина, почему сервер не пригоден для продакшена.

Начиная с PHP 7.4 появилась экспериментальная поддержка многопроцессности, которая опирается на fork() и не работает в Windows. При включении режим форка создаёт отдельный worker для каждого входящего запроса. Включение происходит через переменную окружения PHP_CLI_SERVER_WORKERS:

$ PHP_CLI_SERVER_WORKERS=8 php -S localhost:8080

Ограничения и советы:

• Работает только на системах с fork() (Unix‑подобные ОС). Не для Windows.
• Экспериментально помечено в PHP 8.1 — используйте с осторожностью.
• Fork увеличивает потребление памяти: каждый worker — отдельный процесс.
• Для большинства задач разработки достаточно однопроцессного режима.

Когда встроенный сервер подходит, а когда нет

Подходит:

• Быстрое локальное тестирование PHP‑скриптов.
• Прототипирование маршрутизации и API.
• Тестирование верстки и взаимодействия с бекендом на локальном устройстве.
• Лёгкая интеграция в CI для простых тестов (с оговорками безопасности).

Не подходит:

• Продакшен с высокой нагрузкой.
• Экспонирование сервиса в интернет.
• Сценарии, требующие сложной настройки HTTPS, модулей или балансировки нагрузки.

Рекомендации по безопасности при тестировании в сети

• Никогда не прокидывайте порт наружу без защиты. Используйте SSH‑туннель, VPN или временное проброс портов.
• Запускайте сервер под непривилегированным пользователем.
• Убедитесь, что в документ‑руте нет конфиденциальных файлов (.env, приватных бэкап‑копий и т.п.).
• Используйте файрвол для ограничения доступа по IP, если тестируете на нескольких устройствах.
• Для тестирования HTTPS используйте прокси (например, ngrok или Caddy в режиме прокси), а не прямой запуск сервера в интернет.

Важно: встроенный сервер не умеет управлять сертификатами и TLS, поэтому прямое тестирование HTTPS невозможно без внешнего прокси.

Чек‑лист для быстрого запуска (роль: разработчик)

• Задать корневую директорию через -t (рекомендуется).
• Убедиться, что в корне нет секретных файлов.
• Открыть терминал и запустить php -S с нужным адресом.
• При необходимости передать router.php для маршрутизации.
• Проверить доступность в браузере с localhost.
• Если нужен доступ с мобильного — привязать к 0.0.0.0 и проверить брандмауэр.
• После тестов завершить процесс Ctrl+C.

Чек‑лист для QA

• Проверить статические файлы (CSS, JS, изображения) на корректную отдачу с Content‑Type.
• Проверить роуты API через router‑скрипт.
• Смоделировать несуществующий маршрут и убедиться в 404.
• Прогнать тесты на одновременные запросы (имитация конкурирующих пользователей).
• Проверить логи в терминале на наличие ошибок PHP.

Критерии приёмки

• Сервер запускается командой php -S и отвечает на запросы по указанному адресу.
• PHP‑скрипты исполняются и возвращают ожидаемые HTTP‑статусы.
• Router‑скрипт корректно перенаправляет запросы, а при return false происходит отдача статического файла.
• При запросах к несуществующим ресурсам сервер возвращает 404.
• Нету утечек конфиденциальных файлов из родительских директорий.

Тесты и сценарии проверки (пример)

1. Тест: статический файл
   • Действие: создать test.txt в корне, открыть /test.txt
   • Ожидаемо: содержимое файла и Content‑Type text/plain
2. Тест: выполнение PHP
   • Действие: index.php с phpinfo(); открыть /
   • Ожидаемо: страница phpinfo() отображается
3. Тест: router возвращает false
   • Действие: настроить router.php так, чтобы он возвращал false для /assets/*; создать /assets/app.js
   • Ожидаемо: /assets/app.js отдан как статический файл
4. Тест: 404
   • Действие: запрос несуществующего пути
   • Ожидаемо: 404 статус
5. Тест: удалённый доступ
   • Действие: запустить на 0.0.0.0 и обратиться с другого устройства в локальной сети
   • Ожидаемо: доступ только при корректной сетевой настройке

Быстрая методология: как интегрировать в рабочий процесс

1. Для каждого проекта создайте простой start.sh или Makefile, который запускает сервер с -t и router‑скриптом.
2. Включите в .gitignore ваши локальные файлы конфигурации.
3. Для командной разработки укажите явный адрес (например, 0.0.0.0:8080) и задокументируйте правила доступа.
4. Для CI используйте контейнер или изолированную среду и оставляйте сервер доступным только изнутри pipeline.

Пример start.sh:

#!/usr/bin/env bash
php -S localhost:8080 -t public router.php

Модель принятия решений (коротко)

• Нужно быстро проверить PHP‑скрипт локально → используйте встроенный сервер.
• Нужна безопасность, HTTPS, высокая нагрузка → используйте NGINX/Apache или контейнеры.
• Нужен доступ с телефона в той же сети → запуск на 0.0.0.0 с ограничением по брандмауэру.

Маленький факто‑бокс

• Начиная с: PHP 5.4
• Основной режим: однопроцессный, синхронный
• Многопроцессность: через PHP_CLI_SERVER_WORKERS (требуется fork())
• Работает на: Unix‑подобных системах полностью, функциональность форка недоступна на Windows

Сравнение с альтернативами

• Python SimpleHTTPServer / http.server: быстрый для статики, не выполняет PHP.
• http-server (npm): хорош для статических сайтов, не обрабатывает PHP.
• Docker/WAMP/XAMPP: полноценные среды, подходят для более сложных сценариев и продакшена.

1‑строчный глоссарий

• Document root — корневая директория, из которой сервер отдаёт файлы.
• Router‑скрипт — PHP‑файл, который сервер вызывает при каждом запросе для динамической маршрутизации.
• SAPI — интерфейс запуска PHP (cli, fpm, cli-server и т.д.).

Итог и рекомендации

Встроенный сервер PHP — отличный инструмент для локальной разработки и быстрого прототипирования. Он прост в использовании и не требует дополнительной настройки. Однако он не заменяет полноценный веб‑сервер в продакшене и должен применяться с осмотрительностью при доступе из сети.

Резюме:

• Используйте php -S для локальной отладки.
• Передавайте router.php для сложной маршрутизации.
• Не экспонируйте сервер в интернет.
• При необходимости многопроцессной обработки тестируйте режим workers только на Unix‑системах.

Спасибо за внимание — удачной разработки!