Документация WbRouter

Введение

WbRouter — это мощный и оптимизированный роутер для PHP приложений, который обеспечивает гибкую маршрутизацию запросов с поддержкой паттернов, автоматическим извлечением параметров и телеметрией запросов.

Основные возможности:

Гибкая маршрутизация с паттернами и плейсхолдерами
Автоматическое извлечение Bearer токенов из заголовков
Парсинг GET и POST параметров
Поддержка различных форматов тела запроса (JSON, URL-encoded)
Сбор телеметрии запросов (IP, домен, протокол и т.д.)
Прекомпиляция регулярных выражений для производительности
Автоматический поиск конфигурационных файлов

Производительность:

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

Установка

Шаг 1: Подключение файла

Подключите файл роутера в начале вашего приложения:

require_once __DIR__ . '/router/router.php';

Шаг 2: Создание экземпляра

Создайте экземпляр роутера. Роутер автоматически ищет конфигурационные файлы:

// Автоматический поиск router.ini или engine/router.ini
$router = new WbRouter();

// Или укажите путь к конфигурации явно
$router = new WbRouter('/path/to/router.ini');

💡 Автоматический поиск:

Если путь к конфигурации не указан, роутер ищет файлы в следующем порядке:

DOCUMENT_ROOT/engine/router.ini
DOCUMENT_ROOT/router.ini

Шаг 3: Обработка запроса

Используйте метод parse() для обработки текущего запроса:

$route = $router->parse();
// $route содержит информацию о маршруте, параметры, токен и телеметрию

Конфигурация

Маршруты настраиваются в файле router.ini в формате INI с секцией [router].

Формат конфигурации

[router]
# Паттерн = Назначение
/user/:num = /controller:user/action:profile/id:$0
/api/:any = /mode:api/table:$0
/files/\.:any = /mode:file/path:$0

Структура назначения:

Назначение маршрута состоит из частей, разделенных слэшем. Каждая часть может содержать пару ключ:значение.

⚠️ Важно:

Файл должен содержать секцию [router]
Паттерны чувствительны к регистру
Порядок маршрутов важен — первый совпавший маршрут используется

Паттерны маршрутов

Паттерны маршрутов позволяют создавать гибкие правила маршрутизации с использованием специальных символов и плейсхолдеров.

Базовые паттерны

Паттерн	Описание	Пример
/user/profile	Точное совпадение	/user/profile
/user/:num	Числовой параметр	/user/123
/user/:str	Строковый параметр (только буквы)	/user/john
/user/:any	Любой параметр (кроме слэша)	/user/john-doe
/files/\.:any	Расширение файла	/files/image.jpg

Экранирование специальных символов:

Для использования точки в паттерне (например, для расширений файлов) используйте обратный слэш: \.

Плейсхолдеры

Плейсхолдеры позволяют захватывать части URL и использовать их в назначении маршрута.

Доступные плейсхолдеры

Плейсхолдер	Регулярное выражение	Описание
:any	([^\/]+)	Любые символы кроме слэша
:str	([a-zA-Z]+)	Только буквы (латиница)
:num	([0-9]+)	Только цифры
:end	(.+)	Любые символы до конца строки (включая слэши)

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

[router]
# Захват ID пользователя
/user/:num = /controller:user/action:view/id:$0

# Захват имени пользователя
/user/:str = /controller:user/action:profile/username:$0

# Захват пути к файлу
/files/:end = /controller:files/action:download/path:$0

Параметры

Захваченные значения из паттерна можно использовать в назначении маршрута с помощью переменных $0, $1, $2 и т.д.

Нумерация параметров

Параметры нумеруются начиная с $0:

$0 — первый захваченный параметр
$1 — второй захваченный параметр
$2 — третий захваченный параметр
И так далее...

[router]
# Пример: /api/users/123/posts/456
/api/:any/:num/posts/:num = /mode:api/table:$0/user_id:$1/post_id:$2

# Результат:
# table = "users"
# user_id = "123"
# post_id = "456"

💡 Подсказка:

Параметры автоматически подставляются в значения назначения маршрута. Если параметр не найден, переменная остается как есть.

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

Базовое использование

<?php
require_once __DIR__ . '/router/router.php';

// Создание роутера
$router = new WbRouter();

// Парсинг текущего запроса
$route = $router->parse();

// Использование результата
if (isset($route['controller'])) {
    $controller = $route['controller'];
    $action = $route['action'] ?? 'index';
    // ... ваша логика
}

Доступные методы

parse($url = null)

Парсит запрос и возвращает массив с информацией о маршруте.

$route = $router->parse();
// Возвращает массив с ключами:
// - параметры маршрута (controller, action и т.д.)
// - token (Bearer токен, если есть)
// - query (query string)
// - query_params (распарсенные GET параметры)
// - _get, _post (массивы параметров)
// - _method (HTTP метод)
// - _uri (URI запроса)
// - _req (объединенные GET и POST)
// - телеметрия (host, domain, ip и т.д.)

getBearerToken()

Возвращает Bearer токен из заголовка Authorization.

$token = $router->getBearerToken();
// Возвращает токен или null

getRawGetParams()

Возвращает массив GET параметров.

getParsedBodyParams()

Возвращает массив POST параметров (распарсенных из JSON или URL-encoded).

getRequestTelemetry()

Возвращает массив с телеметрией запроса (IP, домен, протокол и т.д.).

Обработка ошибок

$route = $router->parse();

if (isset($route['error'])) {
    // Маршрут не найден
    http_response_code(404);
    echo json_encode(['error' => $route['error']]);
    exit;
}

Телеметрия запросов

Роутер автоматически собирает информацию о запросе, которая доступна через метод getRequestTelemetry() или в результате parse().

Доступные поля телеметрии

Поле	Описание
method	HTTP метод (GET, POST и т.д.)
scheme	Протокол (http или https)
hostname	Имя хоста
port	Порт сервера
domain	Домен (например, example.com)
zone	Зона домена (com, ru и т.д.)
subdomain	Поддомен (если есть)
host	Полный host со схемой
uri	URI без query string
url	Полный URL без query string
full_url	Полный URL с query string
localreq	Является ли запрос локальным
file	Путь к файлу (если существует по URI)
fileinfo	Информация о файле (pathinfo)

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

$telemetry = $router->getRequestTelemetry();
echo "IP: " . $telemetry['real_ip'];
echo "Domain: " . $telemetry['domain'];
echo "Protocol: " . $telemetry['scheme'];

Примеры

Пример 1: Простая маршрутизация

[router]
# Главная страница
/ = /controller:home/action:index

# Страница пользователя
/user/:num = /controller:user/action:view/id:$0

# Профиль пользователя
/user/:num/profile = /controller:user/action:profile/id:$0

Результат для /user/123:

[
    'controller' => 'user',
    'action' => 'view',
    'id' => '123'
]

Пример 2: API маршрутизация

[router]
# API endpoints
/api/:any = /mode:api/table:$0
/api/:any/:num = /mode:api/table:$0/id:$1
/api/:any/:num/:any = /mode:api/table:$0/id:$1/action:$2

Результат для /api/users/123:

[
    'mode' => 'api',
    'table' => 'users',
    'id' => '123'
]

Пример 3: Работа с файлами

[router]
# Статические файлы
/assets/\.:any = /mode:static/path:assets/$0
/images/\.:any = /mode:static/path:images/$0

Результат для /images/logo.png:

[
    'mode' => 'static',
    'path' => 'images/logo.png'
]

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

<?php
require_once __DIR__ . '/router/router.php';

try {
    $router = new WbRouter();
    $route = $router->parse();
    
    // Проверка ошибки маршрутизации
    if (isset($route['error'])) {
        http_response_code(404);
        echo json_encode(['error' => 'Route not found']);
        exit;
    }
    
    // Получение Bearer токена
    $token = $router->getBearerToken();
    if ($token) {
        // Проверка токена
        // ...
    }
    
    // Использование параметров маршрута
    $controller = $route['controller'] ?? 'home';
    $action = $route['action'] ?? 'index';
    
    // Получение GET параметров
    $getParams = $router->getRawGetParams();
    
    // Получение POST параметров
    $postParams = $router->getParsedBodyParams();
    
    // Использование телеметрии
    $telemetry = $router->getRequestTelemetry();
    $userIp = $telemetry['real_ip'] ?? 'unknown';
    
    // Ваша логика обработки запроса
    // ...
    
} catch (Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => $e->getMessage()]);
}