Встроенный веб‑сервер PHP: как запустить, настроить роутинг и отладку (пошаговое руководство)

Встроенный веб‑сервер PHP — это самый быстрый способ запустить проект локально без лишней конфигурации. Команда php -S поднимает сервер за секунду, а простой роутер на PHP позволяет эмулировать ЧПУ, API и даже CORS для фронтенда. Разберём всё пошагово: от базового запуска до практичного мини‑роутинга.

Когда использовать встроенный сервер PHP

• Быстрый старт прототипа или тестового задания
• Локальная разработка без Apache/Nginx
• Тестирование API и статических файлов

Важно: встроенный сервер предназначен только для разработки, не для продакшена.

Проверка версии и первый запуск

Убедитесь, что PHP установлен и доступен в терминале:

php -v

Запустим простой сервер из текущей папки (докрут — текущий каталог):

php -S localhost:8000

Создайте файл index.php в корне и добавьте:

<?php
echo 'Привет из встроенного сервера PHP!';

Откройте http://localhost:8000 — вы увидите сообщение.

Запуск с отдельной папкой public и роутером

Рекомендуем хранить публичные файлы в каталоге public, а логику — вне веб‑докрута. Структура:

project/
  public/
    index.php
    assets/style.css
  router.php
  src/...

Запуск с указанием докрута и роутера:

php -S localhost:8000 -t public router.php

Роутер перехватывает запросы, отдаёт статические файлы напрямую, а всё остальное — пробрасывает в index.php.

router.php

<?php
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$full = __DIR__ . '/public' . $path;

// Если запрашивают существующий файл (CSS, JS, изображения) — отдать его сервером напрямую
if (is_file($full)) {
    return false; // Встроенный сервер сам отдаст файл
}

// Иначе — передать управление front controller-у
require __DIR__ . '/public/index.php';

public/index.php: мини‑роутинг без фреймворков

<?php
declare(strict_types=1);

// Включим подробные ошибки для разработки
ini_set('display_errors', '1');
error_reporting(E_ALL);

$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$method = $_SERVER['REQUEST_METHOD'];

// Простая зона API с CORS (для запросов с фронтенда)
if (str_starts_with($uri, '/api/')) {
    header('Access-Control-Allow-Origin: *');
    header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
    header('Access-Control-Allow-Headers: Content-Type');
    if ($method === 'OPTIONS') {
        exit; // preflight ответ
    }
}

if ($uri === '/' && $method === 'GET') {
    echo '<h1>Главная</h1><p>Это мини‑роутер на встроенном сервере PHP.</p>';
    exit;
}

if ($uri === '/api/ping' && $method === 'GET') {
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['pong' => true]);
    exit;
}

if ($uri === '/users' && $method === 'GET') {
    $users = [
        ['id' => 1, 'name' => 'Алиса'],
        ['id' => 2, 'name' => 'Боб'],
    ];
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($users, JSON_UNESCAPED_UNICODE);
    exit;
}

http_response_code(404);
echo '404 Not Found';

Теперь запросы к /assets/style.css отдаются напрямую, а URL вроде /api/ping и /users обрабатываются вашим PHP‑кодом.

Полезные флаги и сценарии запуска

• Привязать сервер только к локальному интерфейсу (без доступа из сети):

php -S 127.0.0.1:8000 -t public router.php

• Поделиться сервером в локальной сети (осторожно! для разработки):

php -S 0.0.0.0:8000 -t public router.php

• Windows PowerShell (из папки проекта):

php -S localhost:8000 -t public router.php

Отладка и ошибки

Для разработки включайте вывод ошибок и уровень E_ALL (как в примере выше). Для глубокой отладки можно подключить Xdebug, но чаще достаточно логов и var_dump().

Частые проблемы и решения

• Порт занят (Address already in use). Измените порт: php -S localhost:8001. На macOS/Linux проверьте: lsof -i :8000 и завершите процесс.
• Белый экран. Включите ошибки: ini_set('display_errors','1'); error_reporting(E_ALL);
• Статика не грузится. Проверьте, что роутер возвращает false для файлов и путь к public совпадает.
• Фронтенд не видит API из другого порта. Добавьте CORS‑заголовки и обрабатывайте метод OPTIONS (см. код выше).

Зачем нужен роутер, если есть index.php?

Без роутера встроенный сервер попытается найти физический файл по запрошенному пути. Роутер перехватывает запросы к «несуществующим» файлам (например, /users/42) и перенаправляет их в ваш front controller для дальнейшей логики, имитируя поведение веб‑сервера с mod_rewrite.

Лучшие практики

• Храните публичные файлы в public и не смешивайте их с исходниками
• Не запускайте встроенный сервер в продакшене
• Добавляйте мини‑роутер для ЧПУ и API
• Возвращайте корректные коды ответа: 200, 404, 405 и т. д.
• Формируйте JSON с JSON_UNESCAPED_UNICODE для читаемости на русском

Что дальше изучать

Если хотите системно прокачать PHP (включая работу с MySQL, архитектурой и практикой), посмотрите программу курса и начните обучение: Прокачать навыки на курсе «PHP и MySQL с Нуля до Гуру 3.0».

Вывод

Встроенный веб‑сервер PHP — идеальный инструмент для быстрого старта. С одной командой php -S и коротким router.php вы получаете удобную среду для локальной разработки: статика, ЧПУ‑роутинг, JSON‑API и CORS — всё работает из коробки и без сложной настройки веб‑сервера.