README

一款快速、灵活的路由器，可用于快速构建RESTful网络应用程序。

许可证
作者
需求
安装
使用

许可证

本项目是开源的，遵循MIT许可证。

作者

需求

PHP ^8.0
ctype PHP 扩展

安装

composer require bayfrontmedia/route-it

使用

开始使用 Route It

默认选项

use Bayfront\RouteIt\Router;

$options = [
    'automapping_enabled' => false,
    'automapping_namespace' => '',
    'automapping_route_prefix' => '',
    'class_namespace' => '',
    'files_root_path' => '',
    'force_lowercase_url' => false
];

$router = new Router($options);

强制小写

当在 $options 数组中启用 force_lowercase_url 时，所有包含大写字母的传入请求将通过 301 重定向到其小写对应项。查询参数不受影响。

自动映射

当启用自动映射时，Route It 将自动尝试以 class/method/optional-parameter 的形式分发传入请求，而不必定义每个单独的路由。

传入请求必须匹配自动映射的路由前缀，并且类必须在 $options 数组中定义的自动映射命名空间中存在。

例如

use Bayfront\RouteIt\Router;

$options = [
    'automapping_enabled' => true,
    'automapping_namespace' => 'App\\Pages',
    'automapping_route_prefix' => '/app'
];

$router = new Router($options);

使用上述示例，传入请求将被自动映射如下

显然，自动映射并不能解决每个场景，在这种情况下，可以添加路由。

命名路由

命名路由在控制器、视图或模板中使用超链接时非常有用。通过引用命名路由而不是特定URL，超链接将保持与定义的路由同步更新。

使用 dispatch、dispatchTo 或 dispatchToFallback 方法分发请求时，Route It 将自动将所有命名路由的数组插入到目标中，作为具有 routes 键的参数，除非有其他指定。

有关这些方法的更多信息，请参阅文档。

通配符

定义路由时可以使用通配符来动态定义路径，并将其值作为参数发送到目标。语法是 {type:name}，其中 type 是通配符类型，name 是要传递到目标的参数的名称。

通配符包括

*：请求该部分中的任何非空白字符
alpha：请求该部分中的任何字母字符（见 ctype_alpha）
num：请求该部分中的任何数字字符（见 ctype_digit）
alphanum：请求该部分中的任何字母数字字符（见 ctype_alnum）
**：请求路径中可能存在的任何其他内容（通配符）
?：可选存在于请求该部分中（只能用于最后一个部分）

有关示例，请参阅addRoute。

公共方法

setHost
getHost
setRoutePrefix
getRoutePrefix
addFallback
getFallbacks
addRedirect
getRedirects
addRoute
any
connect
delete
get
head
options
patch
post
put
trace
getRoutes
addNamedRoute
getNamedRoutes
getNamedRoute
resolve
dispatch
dispatchTo
dispatchToFallback
redirect
getResolvedParameters

setHost

描述

为定义的路由设置主机名。

参数

$host (字符串)

(self)

示例

$router->setHost('example.com');

$router->addRoute('GET', '/login', function () {
 
    // Destination for example.com/login

});

$router->setHost('subdomain.example.com');

$router->addRoute('GET', '/login', function () {
 
    // Destination for subdomain.example.com/login

});

getHost

描述

检索定义的路由的主机名。

参数

None

(字符串)

setRoutePrefix

描述

为定义的路由设置路由前缀。

参数

$prefix (字符串)

(self)

示例

$router->setHost('example.com')->setRoutePrefix('app');

$router->addRoute('GET', '/login', function () {
 
    // Destination for example.com/app/login

});

getRoutePrefix

描述

检索定义的路由的路由前缀。

参数

None

(字符串)

addFallback

描述

当找不到路由时，为给定的请求方法添加回退目的地。将以 404 HTTP 状态码发送响应。

参数

$methods (字符串|数组): 此回退有效的请求方法，或 "ANY"
$destination (混合)
$params = [] (数组): 传递给目的地的参数

(self)

示例

$router->addFallback('ANY', function () {
    echo '404 page not found';
});

有关更多目的地示例，请参阅 addRoute。

getFallbacks

描述

返回定义的回退数组。

参数

None

(数组)

addRedirect

描述

添加重定向。路径中可以使用通配符。

参数

$methods (字符串|数组): 此重定向有效的请求方法，或 "ANY"
$path (字符串): 请求路径
$destination (字符串): 可以是内部路径或完全限定的 URL
$status = 302 (整数): 与重定向一起使用的 HTTP 状态码

(self)

示例

// Internal temporary redirect (will not redirect to self)

$router->addRedirect('ANY', '{**:path}', '/under-construction', 302);

// Fully qualified URL

$router->addRedirect('GET', '/documentation', 'https://www.example.com/new-documentation');

有关更多路径定义示例，请参阅 addRoute。

getRedirects

描述

返回定义的重定向数组。

参数

None

(数组)

addRoute

描述

添加定义的路由。路径中可以使用通配符。

目的地可以是可调用的函数、命名路由、文件或 $class->method()。每个路由都可以有自己的预定义参数，并且也可以通过 "通配符" 动态定义参数。

参数

$methods (字符串|数组): 此路由有效的请求方法，或 "ANY"
$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。命名路由名称必须是唯一的，因为已存在的名称将被覆盖。

(self)

示例

$router

    // Callable

    ->addRoute('GET', '/customers', function () {

        echo 'Customers';

    })

    // Callable with a wildcard parameter

    ->addRoute('GET', '/customers/{num:id}', function ($params) {

        echo 'Customer id: ' . $params['id'];

    })

    // Callable with optional wildcard (if existing in the request path, it will overwrite the defined parameter)

    ->addRoute('GET', '/optional/{?:name}', function ($params) {

        echo 'Hello, ' . $params['name'] . '! This is a callable with an optional parameter.';

    }, [
        'name' => 'John'
    ])

    // Callable, saving as a named route

    ->addRoute('GET', '/login', function($params) {

        // Login

    }, [], 'login')

    // To a named route

    ->addRoute('GET', '/oldlogin', 'login')

    // To a file from the files_root_path as defined in the options array

    ->addRoute('GET', '/file', '@filename.html')

    // To a class:method from the class_namespace as defined in the options array

    ->addRoute('GET', '/class', 'TestClass:index', ['greeting' => 'Hello!']);

any

描述

添加适用于任何请求方法的路由。

等同于调用 addRoute('ANY'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->any('/customers', 'Controller:anyMethod');

connect

描述

添加适用于 CONNECT 请求方法的路由。

等同于调用 addRoute('CONNECT'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->connect('/customers', 'Controller:connectMethod');

delete

描述

添加适用于 DELETE 请求方法的路由。

等同于调用 addRoute('DELETE'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->delete('/customers', 'Controller:deleteMethod');

get

描述

添加适用于 GET 请求方法的路由。

等同于调用 addRoute('GET'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->get('/customers', 'Controller:getMethod');

head

描述

添加适用于 HEAD 请求方法的路由。

等同于调用 addRoute('HEAD'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->head('/customers', 'Controller:headMethod');

options

描述

添加适用于 OPTIONS 请求方法的路由。

等同于调用 addRoute('OPTIONS'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->options('/customers', 'Controller:optionsMethod');

patch

描述

添加适用于 PATCH 请求方法的路由。

等同于调用 addRoute('PATCH'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->patch('/customers', 'Controller:patchMethod');

post

描述

添加适用于 POST 请求方法的路由。

等同于调用 addRoute('POST'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->post('/customers', 'Controller:postMethod');

put

描述

添加适用于 PUT 请求方法的路由。

等同于调用 addRoute('PUT'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->put('/customers', 'Controller:putMethod');

trace

描述

添加适用于 TRACE 请求方法的路由。

等同于调用 addRoute('TRACE'...)

参数

$path (字符串): 请求路径
$destination (混合)
$params = [] (数组): 传递给目的地的参数
$name = NULL (字符串|null): 分配给此路由的可选名称

注意：不应将名称分配给路径中包含通配符的路由。命名路由仅用于定义特定的 URL。

(self)

示例

$router->trace('/customers', 'Controller:traceMethod');

getRoutes

描述

返回定义的路由数组。

参数

None

(数组)

addNamedRoute

描述

将特定路径作为命名路由添加。

当想要引用未定义为路由的 URL 时，这很有用。

参数

$path (字符串): 请求路径
$name (字符串): 分配给此路由的名称

(self)

示例

$router->setHost('example.com')->setPrefix('app');

$router->addNamedRoute('/assets/css', 'css');

// Returns: https://example.com/app/assets/css
echo $router->getNamedRoute('login');

getNamedRoutes

描述

返回命名路由数组。

自动将通配符替换为已解析的参数。

参数

$params = [] (数组): 用于替换命名路由中通配符的额外参数

(数组)

getNamedRoute

描述

返回命名路由的 URL。

自动将通配符替换为已解析的参数。

参数

$name (字符串)
$default = '' (字符串): 如果命名路由不存在时返回的默认值
$params = [] (数组): 用于替换命名路由中通配符的额外参数

(字符串)

resolve

描述

通过搜索匹配的重定向、路由、自动映射的位置或回退来解析传入的HTTP请求。特定于目标的位置参数将覆盖相同键的全局参数。

返回的数组包含以下键

类型
目标
status (HTTP状态码)
params (数组)

目标将根据类型而变化

如果请求无法解析，将抛出 DispatchException。

参数

$params = [] (数组): 传递给所有目标的全局参数

(数组)

dispatch

描述

解析和派发传入的HTTP请求。

特定于目标的位置参数将覆盖相同键的全局参数。

参数

$params = [] (数组): 传递给所有目标的全局参数

(混合类型)

抛出

Bayfront\RouteIt\DispatchException

示例

use Bayfront\RouteIt\DispatchException;
use Bayfront\RouteIt\Router;

$options = [
    'automapping_enabled' => false,
    'automapping_namespace' => '',
    'automapping_route_prefix' => '',
    'class_namespace' => '',
    'files_root_path' => '',
    'force_lowercase_url' => false
];

$router = new Router($options);

// Add routes here

try {

    $router->dispatch();

} catch (DispatchException $e) {
    die($e->getMessage());
}

dispatchTo

描述

派发到特定目标。

目标可以是可调用的函数、命名路由、文件或 $class->method()。

参数

$destination (混合)
$params = [] (数组): 传递给目的地的参数

(混合类型)

抛出

Bayfront\RouteIt\DispatchException

示例

try {

    $router->dispatchTo('TestClass:index');

} catch (DispatchException $e) {
    die($e->getMessage());
}

dispatchToFallback

描述

派发到当前请求方法的回退，或抛出异常。

使用 addFallback 方法定义的特定于回退的参数将覆盖这些参数的相同键。

参数

$params = [] (数组): 传递给目的地的参数

(混合类型)

抛出

Bayfront\RouteIt\DispatchException

示例

try {

    $router->dispatchToFallback();

} catch (DispatchException $e) {
    die($e->getMessage());
}

redirect

描述

使用给定的状态码重定向到指定的URL。

参数

$url (字符串): 完整的URL
$status = 302: 要返回的HTTP状态码

(无返回值)

抛出

Bayfront\RouteIt\DispatchException

示例

try {

    $router->redirect('https://www.example.com);

} catch (DispatchException $e) {
    die($e->getMessage());
}

getResolvedParameters

描述

一旦解析/派发，获取当前路由中存在的所有参数的数组。

参数

None

(数组)

bayfrontmedia / route-it

维护者

详细信息

README

许可证

作者

需求

安装

使用

开始使用 Route It

强制小写

自动映射

命名路由

通配符

公共方法

setHost

getHost

setRoutePrefix

getRoutePrefix

addFallback

getFallbacks

addRedirect

getRedirects

addRoute

any

connect

delete

get

head

options

patch

post

put

trace

getRoutes

addNamedRoute

getNamedRoutes

getNamedRoute

resolve

dispatch

dispatchTo

dispatchToFallback

redirect

getResolvedParameters