Download the PHP package triangle/router without Composer

Маршрутизатор HTTP-запросов

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

Установка

Для установки через Composer:

Требуется PHP 8.0 или выше.

Usage

Пример использования:

Определение маршрутов

Маршруты определяются путем вызова функции simpleRouteDispatcher(), которая принимает вызываемый объект, принимающий экземпляр Triangle\Router\RouteCollector. Маршруты добавляются путем вызова addRoute() на экземпляре коллектора:

Параметр $method — это строка HTTP-метода в верхнем регистре, для которой должен совпадать определенный маршрут. Можно указать несколько допустимых методов с помощью массива:

По умолчанию $routePattern использует синтаксис, где {foo} указывает заполнитель с именем foo и соответствует регулярному выражению [^/]+. Чтобы настроить шаблон, которому соответствует заполнитель, вы можете указать пользовательский шаблон, написав {bar:[0-9]+}. Вот несколько примеров:

Пользовательские шаблоны для заполнителей маршрутов не могут использовать группы захвата. Например, {lang:(en|de)} не является допустимым заполнителем, поскольку () является группой захвата. Вместо этого вы можете использовать либо {lang:en|de}, либо {lang:(?:en|de)}.

Кроме того, части маршрута, заключенные в [...], считаются необязательными, поэтому /foo[bar] будет соответствовать как /foo, так и /foobar. Необязательные части поддерживаются только в конце, но не в середине маршрута.

Параметр $handler не обязательно должен быть обратным вызовом, он также может быть именем класса контроллера или любым другим типом данных, которые вы хотите связать с маршрутом. Маршрутизатор только сообщает вам, какой обработчик соответствует вашему URI, как вы его интерпретируете, зависит от вас.

Сокращения для популярных методов

Для методов GET, POST, PUT, PATCH, DELETE, HEAD и OPTIONS доступны сокращения. Например, маршруты:

Эквивалентны:

Если маршрут предполагает все существующие (и не существующие) методы - можно использовать:

Группы маршрутов

Кроме того, вы можете указать маршруты внутри группы. Все маршруты, определенные внутри группы, будут иметь общий префикс.

Например, определение ваших маршрутов как:

Будет иметь тот же результат, что и:

Также поддерживаются вложенные группы, в этом случае префиксы всех вложенных групп объединяются.

Кэширование

Причина, по которой simpleRouteDispatcher принимает обратный вызов для определения маршрутов, заключается в том, чтобы разрешить бесшовное кэширование. Используя cachedRouteDispatcher вместо simpleRouteDispatcher, вы можете кэшировать сгенерированные данные маршрутизации и создать диспетчер из кэшированной информации:

Вторым параметром функции является массив параметров, который можно использовать, среди прочего, для указания местоположения файла кэша.

Обработка URI

URI обрабатывается путем вызова метода dispatch() созданного диспетчера. Этот метод принимает метод HTTP и URI. Получение этих двух битов информации (и их нормализация соответствующим образом) — ваша работа — эта библиотека не привязана к SAPI PHP.

Метод dispatch() возвращает массив, первый элемент которого содержит код состояния. Это один из Dispatcher::NOT_FOUND, Dispatcher::METHOD_NOT_ALLOWED и Dispatcher::FOUND. Для состояния «метод не разрешен» второй элемент массива содержит список методов HTTP, разрешенных для предоставленного URI. Например:

[Triangle\Router\Dispatcher::METHOD_NOT_ALLOWED, ['GET', 'POST']]

ПРИМЕЧАНИЕ: Спецификация HTTP требует, чтобы ответ 405 Method Not Allowed включал заголовок Allow: для детализации доступных методов для запрошенного ресурса. Приложения, использующие Triangle Router, должны использовать второй элемент массива для добавления этого заголовка при ретрансляции ответа 405.

Для статуса Dispatcher::FOUND второй элемент массива — это обработчик, который был связан с маршрутом, а третий элемент массива — это словарь имен переменных для их значений. Например:

/* Маршрутизация по GET /user/localzet/42 */

[Triangle\Router\Dispatcher::FOUND, 'handler0', ['name' => 'localzet', 'id' => '42']]

Переопределение парсера маршрута и диспетчера

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

Парсер маршрута берет строку шаблона маршрута и преобразует ее в массив информаций о маршруте, где каждая информация снова является массивом своих частей. Структуру лучше всего понять на примере:

/* Маршрут /user/{id:\d+}[/{name}] преобразуется в следующий массив: */
[
    [
        '/user/',
        ['id', '\d+'],
    ],
    [
        '/user/',
        ['id', '\d+'],
        '/',
        ['name', '[^/]+'],
    ],
]

Этот массив затем можно передать в метод addRoute() генератора данных. После добавления всех маршрутов вызывается getData() генератора, который возвращает все данные маршрутизации, необходимые диспетчеру. Формат этих данных далее не указывается — он тесно связан с соответствующим диспетчером.

Диспетчер принимает данные маршрутизации через конструктор и предоставляет метод dispatch(), с которым вы уже знакомы.

Парсер маршрута можно переопределить по отдельности (чтобы использовать другой синтаксис шаблона), однако генератор данных и диспетчер всегда следует изменять как пару, поскольку вывод первого тесно связан со вводом второго. Причина, по которой генератор и диспетчер разделены, заключается в том, что только последний нужен при использовании кэширования (поскольку вывод первого — это то, что кэшируется.)

При использовании функций simpleRouteDispatcher / cachedRouteDispatcher из вышеприведенных переопределение происходит через массив параметров:

Массив параметров выше соответствует значениям по умолчанию. Заменив GroupCountBased на GroupPosBased, вы можете переключиться на другую стратегию диспетчеризации.

Примечание о запросах HEAD

Спецификация HTTP требует, чтобы серверы поддерживали как методы GET, так и методы HEAD:

Методы GET и HEAD ДОЛЖНЫ поддерживаться всеми серверами общего назначения

Чтобы не заставлять пользователей вручную регистрировать маршруты HEAD для каждого ресурса, мы возвращаемся к сопоставлению доступного маршрута GET для данного ресурса. PHP SAPI прозрачно удаляет тело сущности из ответов HEAD, поэтому это поведение не влияет на подавляющее большинство пользователей.

Однако разработчики, использующие Triangle Router вне веб-среды SAPI (например, пользовательский сервер), НЕ ДОЛЖНЫ отправлять тела сущностей, сгенерированные в ответ на запросы HEAD. Если вы не являетесь пользователем SAPI, это ваша ответственность; Triangle Router не имеет полномочий, чтобы помешать вам нарушить HTTP в таких случаях.

Наконец, обратите внимание, что приложения МОГУТ всегда указывать свой собственный маршрут метода HEAD для данного ресурса, чтобы полностью обойти это поведение.

Авторы

Эта библиотека основана на маршрутизаторах, реализованных Levi Morrison и Nikita Popov.