README

简单、快速且功能强大的PHP路由器，易于集成，适用于任何项目。深受Laravel处理路由方式的启发，注重简洁性和扩展性。

使用simple-router，您可以快速创建新项目，无需依赖框架。

只需几行代码即可开始使用

SimpleRouter::get('/', function() {
    return 'Hello world';
});

支持项目

如果您喜欢simple-router，并希望看到项目的持续开发和维护，请考虑通过购买咖啡来支持我。支持者将在本文档的致谢部分列出。

您可以通过此处捐赠任意金额。

入门

这是一个从skipperbent/simple-php-router分支出来的项目，因为原始项目的最后提交是在2年前，所以我决定将其分支出来，并将那里最新的PR合并进来。

运行此命令添加simple-router项目的最新版本。

composer require eightsystems/simple-router

注意事项

本项目的目标是创建一个与Laravel文档基本100%兼容的路由器，同时尽可能简单，便于集成和修改，不会牺牲速度或复杂性。轻量级是首要任务。

我们提供了一个简单的路由器示例项目，可以在demo-project文件夹中找到。该项目应能帮助您了解如何设置和使用simple-php-router项目。

请注意，demo-project仅涵盖如何在没有现有框架的项目中集成simple-php-router。如果您的项目中使用了框架，实现方式可能会有所不同。

您可以在这里找到demo-project： https://github.com/skipperbent/simple-router-demo

我们不涉及的内容

如何设置满足您需求解决方案。这是一个基本示例，帮助您开始。
MVC的理解；包括控制器、中间件或异常处理器。
如何集成到第三方框架中。

我们涉及的内容

如何快速启动 - 从零开始。
如何使异常处理器、中间件和控制器工作。
如何设置您的Web服务器。

要求

PHP 7.1或更高版本（版本3.x及以下支持PHP 5.5+）
启用PHP JSON扩展。

特性

基本路由（GET、POST、PUT、PATCH、UPDATE、DELETE）支持自定义多个动词。
正则表达式参数约束。
命名路由。
生成路由URL。
路由分组。
中间件（拦截路由渲染之前的类）。
命名空间。
路由前缀。
CSRF保护。
可选参数
子域路由。
自定义引导管理器以将URL重写为更“优雅”的URL。
输入管理器；轻松管理GET、POST和FILE值。

安装

在终端导航到您的项目文件夹，并运行以下命令

composer require pecee/simple-router

设置Nginx

如果您使用Nginx，请确保已启用url-rewriting。

您可以通过添加以下配置到Nginx配置文件来轻松启用url-rewriting（针对demo-project）。

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

设置Apache

对于Apache，无需特殊设置。我们在public文件夹中包含了.htaccess文件。如果重写不起作用，请检查Apache配置中是否已启用mod_rewrite模块（htaccess支持）。

.htaccess示例

以下是simple-php-router使用的有效.htaccess文件示例。

只需在项目的public目录中创建一个新的.htaccess文件，并将以下内容粘贴到您新创建的文件中。这将使所有请求重定向到您的index.php文件（参见配置部分）。

RewriteEngine on
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-l
RewriteRule ^(.*)$ index.php/$1

设置IIS

在IIS中，您需要在public文件夹中的web.config文件中添加一些行或创建一个新文件。如果重写不起作用，请检查您的IIS版本是否已包含url rewrite模块，或者从Microsoft网站下载并安装它们。

web.config示例

以下是simple-php-router使用的有效web.config文件示例。

只需在项目的public目录中创建一个新的web.config文件，并将以下内容粘贴到您新创建的文件中。这将使所有请求重定向到您的index.php文件（参见配置部分）。如果已存在web.config文件，请在<system.webServer>分支内部添加<rewrite>部分。

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
	<rewrite>
	  <rules>
		<!-- Remove slash '/' from the en of the url -->
		<rule name="RewriteRequestsToPublic">
		  <match url="^(.*)$" />
		  <conditions logicalGrouping="MatchAll" trackAllCaptures="false">
		  </conditions>
		  <action type="Rewrite" url="/{R:0}" />
		</rule>

		<!-- When requested file or folder don't exists, will request again through index.php -->
		<rule name="Imported Rule 1" stopProcessing="true">
		  <match url="^(.*)$" ignoreCase="true" />
		  <conditions logicalGrouping="MatchAll">
			<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
			<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
		  </conditions>
		  <action type="Rewrite" url="/index.php/{R:1}" appendQueryString="true" />
		</rule>
	  </rules>
	</rewrite>
    </system.webServer>
</configuration>

故障排除

如果您的项目中没有favicon.ico文件，您将收到NotFoundHttpException（404 - 未找到）。

要将favicon.ico添加到IIS忽略列表中，请向<conditions>组中添加以下行

<add input="{REQUEST_FILENAME}" negate="true" pattern="favicon.ico" ignoreCase="true" />

您还可以为具有某些扩展名的文件设置一个例外

<add input="{REQUEST_FILENAME}" pattern="\.ico|\.png|\.css|\.jpg" negate="true" ignoreCase="true" />

如果您使用$_SERVER['ORIG_PATH_INFO']，您将得到返回值中的\index.php\部分。

示例

/index.php/test/mypage.php

配置

创建一个新文件，命名为 routes.php 并将其放置在您的库文件夹中。这将是你定义项目所有路由的文件。

警告：永远不要将您的 routes.php 放在公共文件夹中！

在您的 index.php 中，引入您新创建的 routes.php 并调用 SimpleRouter::start() 方法。这将触发并执行实际的请求路由。

这不是必需的，但您可以将 SimpleRouter::setDefaultNamespace('\Demo\Controllers'); 设置为在所有路由前加上控制器的命名空间。这将简化一些事情，因为您不需要在每个路由上指定控制器的命名空间。

以下是一个基本 index.php 文件的示例

<?php
use Pecee\SimpleRouter\SimpleRouter;

/* Load external routes file */
require_once 'routes.php';

/**
 * The default namespace for route-callbacks, so we don't have to specify it each time.
 * Can be overwritten by using the namespace config option on your routes.
 */

SimpleRouter::setDefaultNamespace('\Demo\Controllers');

// Start the routing
SimpleRouter::start();

辅助函数

我们建议您将以下辅助函数添加到您的项目中。这些将使您更容易访问路由器的功能。

要实现以下功能，只需将代码复制到一个新文件，并在初始化路由器之前引入该文件或复制我们在此库中包含的 helpers.php。

<?php

use Pecee\SimpleRouter\SimpleRouter as Router;
use Pecee\Http\Url;
use Pecee\Http\Response;
use Pecee\Http\Request;

/**
 * Get url for a route by using either name/alias, class or method name.
 *
 * The name parameter supports the following values:
 * - Route name
 * - Controller/resource name (with or without method)
 * - Controller class name
 *
 * When searching for controller/resource by name, you can use this syntax "route.name@method".
 * You can also use the same syntax when searching for a specific controller-class "MyController@home".
 * If no arguments is specified, it will return the url for the current loaded route.
 *
 * @param string|null $name
 * @param string|array|null $parameters
 * @param array|null $getParams
 * @return \Pecee\Http\Url
 * @throws \InvalidArgumentException
 */
function url(?string $name = null, $parameters = null, ?array $getParams = null): Url
{
    return Router::getUrl($name, $parameters, $getParams);
}

/**
 * @return \Pecee\Http\Response
 */
function response(): Response
{
    return Router::response();
}

/**
 * @return \Pecee\Http\Request
 */
function request(): Request
{
    return Router::request();
}

/**
 * Get input class
 * @param string|null $index Parameter index name
 * @param string|null $defaultValue Default return value
 * @param array ...$methods Default methods
 * @return \Pecee\Http\Input\InputHandler|array|string|null
 */
function input($index = null, $defaultValue = null, ...$methods)
{
    if ($index !== null) {
        return request()->getInputHandler()->value($index, $defaultValue, ...$methods);
    }

    return request()->getInputHandler();
}

/**
 * @param string $url
 * @param int|null $code
 */
function redirect(string $url, ?int $code = null): void
{
    if ($code !== null) {
        response()->httpCode($code);
    }

    response()->redirect($url);
}

/**
 * Get current csrf-token
 * @return string|null
 */
function csrf_token(): ?string
{
    $baseVerifier = Router::router()->getCsrfVerifier();
    if ($baseVerifier !== null) {
        return $baseVerifier->getTokenProvider()->getToken();
    }

    return null;
}

路由

记住您在 index.php 中引入的 routes.php 文件？这个文件将用于放置您所有的自定义路由规则。

基本路由

以下是一个设置路由的非常基本的示例。第一个参数是要匹配的路由的 URL - 下一个参数是当路由匹配时将被触发的 Closure 或回调函数。

SimpleRouter::get('/', function() {
    return 'Hello world';
});

可用方法

您可以看到所有可用路由的列表

SimpleRouter::get($url, $callback, $settings);
SimpleRouter::post($url, $callback, $settings);
SimpleRouter::put($url, $callback, $settings);
SimpleRouter::patch($url, $callback, $settings);
SimpleRouter::delete($url, $callback, $settings);
SimpleRouter::options($url, $callback, $settings);

多个HTTP动词

有时您可能需要创建一个接受多个 HTTP-verbs 的路由。如果您需要匹配所有 HTTP-verbs，可以使用 any 方法。

SimpleRouter::match(['get', 'post'], '/', function() {
    // ...
});

SimpleRouter::any('foo', function() {
    // ...
});

我们已经创建了一个简单的方法来匹配 GET 和 POST，这最常使用。

SimpleRouter::form('foo', function() {
    // ...
});

路由参数

必需参数

您现在可能想知道如何从 URL 中解析参数。例如，您可能希望从 URL 中捕获用户的 ID。您可以通过定义路由参数来实现这一点。

SimpleRouter::get('/user/{id}', function ($userId) {
    return 'User with id: ' . $userId;
});

您可以定义与您的路由所需数量相匹配的路由参数

SimpleRouter::get('/posts/{post}/comments/{comment}', function ($postId, $commentId) {
    // ...
});

注意：路由参数始终用 {} 括起来，并且应仅由字母字符组成。路由参数不得包含 - 字符。请使用下划线 (_) 代替。

可选参数

有时您可能需要指定一个路由参数，但使该路由参数的存在是可选的。您可以通过在参数名称后放置一个 ? 标记来做到这一点。确保给路由的相应变量提供一个默认值。

SimpleRouter::get('/user/{name?}', function ($name = null) {
    return $name;
});

SimpleRouter::get('/user/{name?}', function ($name = 'Simon') {
    return $name;
});

正则表达式约束

您可以使用路由实例上的 where 方法来限制路由参数的格式。where 方法接受参数的名称和定义如何限制参数的正则表达式。

SimpleRouter::get('/user/{name}', function ($name) {
    
    // ... do stuff
    
})->where('name', '[A-Za-z]+');

SimpleRouter::get('/user/{id}', function ($id) {
    
    // ... do stuff
    
})->where('id', '[0-9]+');

SimpleRouter::get('/user/{id}/{name}', function ($id, $name) {
    
    // ... do stuff
    
})->where(['id' => '[0-9]+', 'name' => '[a-z]+']);

正则表达式路由匹配

如果您希望对整个路由定义正则表达式匹配，可以这样做。

这对于例如创建一个模型框，该模型框从 AJAX 加载 URL 非常有用。

以下示例使用以下正则表达式：/ajax/([\w]+)/?([0-9]+)?/?，它基本上只匹配 /ajax/ 并期望下一个参数是一个字符串 - 下一个是一个数字（但可选）。

匹配： /ajax/abc/，/ajax/abc/123/

不匹配： /ajax/

正则表达式中指定的匹配组将被作为参数传递。

SimpleRouter::all('/ajax/abc/123', function($param1, $param2) {
	// param1 = abc
	// param2 = 123
})->setMatch('/\/ajax\/([\w]+)\/?([0-9]+)?\/?/is');

自定义正则表达式匹配参数

默认情况下，simple-php-router 使用 \w 正则表达式来匹配参数。这个决定是考虑到速度和可靠性，因为这个匹配将匹配字母、数字和互联网上使用的大多数符号。

然而，有时添加一个自定义正则表达式来匹配更复杂的字符，如 - 等等，是必要的。

而不是将自定义正则表达式添加到所有参数中，您可以简单地添加一个全局正则表达式，该表达式将用于路由上所有参数。

注意：如果您希望正则表达式在多个地方可用，我们建议使用以下示例中演示的组的全局参数。

示例

本例将确保在解析时，所有参数都使用 [\w\-]+ 正则表达式。

SimpleRouter::get('/path/{parameter}', 'VideoController@home', ['defaultParameterRegex' => '[\w\-]+']);

如果需要多个路由在解析参数时使用自定义正则表达式，您也可以将此设置应用于一组。

SimpleRouter::group(['defaultParameterRegex' => '[\w\-]+'], function() {

    SimpleRouter::get('/path/{parameter}', 'VideoController@home');

});

命名路由

命名路由允许方便地生成特定路由的 URL 或重定向。

SimpleRouter::get('/user/profile', function () {
    // Your code here
})->name('profile');

您还可以指定控制器-操作的名称。

SimpleRouter::get('/user/profile', 'UserController@profile')->name('profile');

生成命名路由的URL

一旦为某个路由分配了名称，您可以通过全局的 url 辅助函数（见辅助部分）来生成 URL 或重定向时使用该路由的名称。

// Generating URLs...
$url = url('profile');

如果命名路由定义了参数，您可以将参数作为 url 函数的第二个参数传递。给定的参数将自动插入到 URL 的正确位置。

SimpleRouter::get('/user/{id}/profile', function ($id) {
    //
})->name('profile');

$url = url('profile', ['id' => 1]);

有关 URL 的更多信息，请参阅URLs部分。

路由分组

路由组允许您在不为每个单独的路由定义属性的情况下，跨大量路由共享路由属性，如中间件或命名空间。共享属性以数组格式指定为 SimpleRouter::group 方法的第一个参数。

中间件

要为组内的所有路由分配中间件，您可以使用组属性数组中的中间件键。中间件按数组中的顺序执行。

SimpleRouter::group(['middleware' => \Demo\Middleware\Auth::class], function () {
    SimpleRouter::get('/', function ()    {
        // Uses Auth Middleware
    });

    SimpleRouter::get('/user/profile', function () {
        // Uses Auth Middleware
    });
});

命名空间

路由组的另一个常见用途是使用组数组中的 namespace 参数将相同的 PHP 命名空间分配给一组控制器。

注意

组命名空间仅添加到具有相对回调的路由。例如，如果您的路由具有绝对回调如 \Demo\Controller\DefaultController@home，则不会添加路由的命名空间。要修复此问题，您可以通过从回调的开头移除 \ 来使回调相对。

SimpleRouter::group(['namespace' => 'Admin'], function () {
    // Controllers Within The "App\Http\Controllers\Admin" Namespace
});

子域名路由

路由组还可以用于处理子域路由。子域可以像路由 URL 一样分配路由参数，允许您捕获子域的一部分以在路由或控制器中使用。可以使用组属性数组中的 domain 键指定子域。

SimpleRouter::group(['domain' => '{account}.myapp.com'], function () {
    SimpleRouter::get('/user/{id}', function ($account, $id) {
        //
    });
});

路由前缀

可以使用 prefix 组属性为组中的每个路由添加给定的 URL 前缀。例如，您可能希望将组内的所有路由 URL 前缀设置为 admin。

SimpleRouter::group(['prefix' => '/admin'], function () {
    SimpleRouter::get('/users', function ()    {
        // Matches The "/admin/users" URL
    });
});

部分分组

部分路由组具有与正常组相同的优点，但支持参数，并且仅在 URL 匹配后才会渲染。

这在某些情况下非常有用，例如，您只想在满足某些标准或逻辑时添加特殊路由。

注意：谨慎使用部分组，因为其中添加的路由仅在部分组 URL 匹配后才会渲染和可用。这可能会导致 url() 无法找到其中添加的路由的 URL。

示例

SimpleRouter::partialGroup('/admin/{applicationId}', function ($applicationId) {

    SimpleRouter::get('/', function($applicationId) {

        // Matches The "/admin/applicationId" URL

    });

});

表单方法欺骗

HTML 表单不支持 PUT、PATCH 或 DELETE 操作。因此，在定义从 HTML 表单调用的 PUT、PATCH 或 DELETE 路由时，您需要向表单添加一个隐藏的 _method 字段。与 _method 字段一起发送的值将用作 HTTP 请求方法。

<input type="hidden" name="_method" value="PUT" />

访问当前路由

您可以使用以下方法访问当前加载的路由的信息。

SimpleRouter::request()->getLoadedRoute();
request()->getLoadedRoute();

依赖注入

simple-router 支持使用 php-di 库进行依赖注入。

依赖注入允许框架自动“注入”（加载）作为参数添加的类。这可以简化您的代码，因为您可以在 Controllers 等地方避免创建经常使用的对象的新实例。

以下是一个使用依赖注入的基本控制器类示例。

namespace Demo\Controllers;

class DefaultController {
    
    public function login(User $user): string 
    {
        // ...
    }
    
}

上面的示例将自动从$user参数创建一个新的User实例。这意味着$user类包含了一个新的User类实例，我们不需要自己创建一个新实例。

警告：依赖注入可能会对性能产生一些负面影响。如果您遇到任何性能问题，我们建议禁用此功能。

启用依赖注入

依赖注入默认是禁用的，以避免任何性能问题。

在启用依赖注入之前，我们建议您阅读php-di文档中的容器配置部分。本节介绍了如何配置php-di以适应不同的环境并提高性能。

为开发环境启用

以下示例应仅在开发环境中使用。

// Create our new php-di container
$container = (new \DI\ContainerBuilder())
            ->useAutowiring(true)
            ->build();

// Add our container to simple-router and enable dependency injection
SimpleRouter::enableDependencyInjection($container);

请查阅文档中的更多阅读部分，获取有用的php-di链接和教程。

为生产环境启用

以下示例编译注入，这有助于提高性能。

注意：您应将$cacheDir更改为项目中的缓存存储。

// Cache directory
$cacheDir = sys_get_temp_dir('simple-router');

// Create our new php-di container
$container = (new \DI\ContainerBuilder())
            ->enableCompilation($cacheDir)
            ->writeProxiesToFile(true, $cacheDir . '/proxies')
            ->useAutowiring(true)
            ->build();

// Add our container to simple-router and enable dependency injection
SimpleRouter::enableDependencyInjection($container);

请查阅文档中的更多阅读部分，获取有用的php-di链接和教程。

其他示例

您可以在下面的routes.php示例文件中找到更多示例。

<?php
use Pecee\SimpleRouter\SimpleRouter;

/* Adding custom csrfVerifier here */
SimpleRouter::csrfVerifier(new \Demo\Middlewares\CsrfVerifier());

SimpleRouter::group(['middleware' => \Demo\Middlewares\Site::class, 'exceptionHandler' => \Demo\Handlers\CustomExceptionHandler::class], function() {


    SimpleRouter::get('/answers/{id}', 'ControllerAnswers@show', ['where' => ['id' => '[0-9]+']]);


    /**
     * Restful resource (see IRestController interface for available methods)
     */

    SimpleRouter::resource('/rest', ControllerRessource::class);


    /**
     * Load the entire controller (where url matches method names - getIndex(), postIndex(), putIndex()).
     * The url paths will determine which method to render.
     *
     * For example:
     *
     * GET  /animals         => getIndex()
     * GET  /animals/view    => getView()
     * POST /animals/save    => postSave()
     *
     * etc.
     */

    SimpleRouter::controller('/animals', ControllerAnimals::class);

});

SimpleRouter::get('/page/404', 'ControllerPage@notFound', ['as' => 'page.notfound']);

CSRF保护

向POST、PUT或DELETE路由提交表单时应包含CSRF-token。我们强烈建议您在网站上启用CSRF-验证以最大化安全性。

您可以使用BaseCsrfVerifier在所有请求上启用CSRF-验证。如果您需要禁用特定URL的验证，请参阅下面的“自定义CSRF-verifier”部分。

默认情况下，simple-php-router将使用CookieTokenProvider类。此提供程序将在客户端机器的cookie中存储安全令牌。如果您想将令牌存储在其他地方，请参阅下面的“创建自定义Token Provider”部分。

添加CSRF验证器

您需要告诉simple-php-router它应该使用您创建的CSRF-verifier。您可以在routes.php文件中添加以下行来完成此操作

Router::csrfVerifier(new \Demo\Middlewares\CsrfVerifier());

获取CSRF令牌

在向启用CSRF-验证的任何URL提交时，您需要提交CSRF-token，否则请求将被拒绝。

您可以通过调用辅助方法来获取CSRF-token。

csrf_token();

您也可以直接获取令牌。

return Router::router()->getCsrfVerifier()->getTokenProvider()->getToken();

默认输入字段的名称/键为csrf_token，并在BaseCsrfVerifier类的POST_KEY常量中定义。您可以通过在您自己的CSRF-verifier类中重写常量来更改键。

示例

以下示例将在当前URL中提交一个隐藏字段"csrf_token"。

<form method="post" action="<?= url(); ?>">
    <input type="hidden" name="csrf_token" value="<?= csrf_token(); ?>">
    <!-- other input elements here -->
</form>

自定义CSRF验证器

创建一个新的类，并扩展simple-php-router库提供的默认BaseCsrfVerifier中间件类。

将属性except添加到要排除/白名单的URL数组中，您希望从中排除CSRF验证的路由。使用*在URL末尾将匹配整个URL。

以下是一个CSRF-verifier类的示例。

namespace Demo\Middlewares;

use Pecee\Http\Middleware\BaseCsrfVerifier;

class CsrfVerifier extends BaseCsrfVerifier
{
	/**
	 * CSRF validation will be ignored on the following urls.
	 */
	protected $except = ['/api/*'];
}

自定义Token Provider

默认情况下，BaseCsrfVerifier将使用CookieTokenProvider在客户端机器的cookie中存储令牌。

如果您需要将令牌存储在其他地方，您可以创建自己的类并实现ITokenProvider类。

class SessionTokenProvider implements ITokenProvider
{

    /**
     * Refresh existing token
     */
    public function refresh(): void
    {
        // Implement your own functionality here...
    }

    /**
     * Validate valid CSRF token
     *
     * @param string $token
     * @return bool
     */
    public function validate($token): bool
    {
        // Implement your own functionality here...
    }
    
    /**
     * Get token token
     *
     * @param string|null $defaultValue
     * @return string|null
     */
    public function getToken(?string $defaultValue = null): ?string 
    {
        // Implement your own functionality here...
    }

}

接下来，您需要在路由文件中将自定义的ITokenProvider实现设置到您的BaseCsrfVerifier类中。

$verifier = new \dscuz\Middleware\CsrfVerifier();
$verifier->setTokenProvider(new SessionTokenProvider());

Router::csrfVerifier($verifier);

中间件

中间件是渲染路由之前加载的类。中间件可以用来验证用户是否已登录 - 或为当前请求/路由设置特定参数。中间件必须实现 IMiddleware 接口。

示例

namespace Demo\Middlewares;

use Pecee\Http\Middleware\IMiddleware;
use Pecee\Http\Request;

class CustomMiddleware implements IMiddleware {

    public function handle(Request $request): void 
    {
    
        // Authenticate user, will be available using request()->user
        $request->user = User::authenticate();

        // If authentication failed, redirect request to user-login page.
        if($request->user === null) {
            $request->setRewriteUrl(url('user.login'));
        }

    }
}

异常处理程序

异常处理器是处理所有异常的类。异常处理器必须实现 IExceptionHandler 接口。

处理404、403和其他错误

如果您只想捕获404（页面未找到）等错误，您可以使用 Router::error($callback) 静态辅助方法。

这将添加一个回调方法，当所有路由上发生错误时将触发。

以下基本示例在发生 NotFoundHttpException（404）错误时将页面重定向到 /not-found。应将此代码放在包含您的路由的文件中。

Router::get('/not-found', 'PageController@notFound');

Router::error(function(Request $request, \Exception $exception) {

    if($exception instanceof NotFoundHttpException && $exception->getCode() === 404) {
        response()->redirect('/not-found');
    }
    
});

使用自定义异常处理程序

这是一个异常处理器实现的示例（请参阅 "轻松覆盖即将加载的路由" 了解如何更改回调的示例）。

namespace Demo\Handlers;

use Pecee\Http\Request;
use Pecee\SimpleRouter\Handlers\IExceptionHandler;
use Pecee\SimpleRouter\Exceptions\NotFoundHttpException;

class CustomExceptionHandler implements IExceptionHandler
{
	public function handleError(Request $request, \Exception $error): void
	{

		/* You can use the exception handler to format errors depending on the request and type. */

		if ($request->getUrl()->contains('/api')) {

			response()->json([
				'error' => $error->getMessage(),
				'code'  => $error->getCode(),
			]);

		}

		/* The router will throw the NotFoundHttpException on 404 */
		if($error instanceof NotFoundHttpException) {

			// Render custom 404-page
			$request->setRewriteCallback('Demo\Controllers\PageController@notFound');
			return;
			
		}

		throw $error;

	}

}

URLs

默认情况下，所有控制器和资源路由都会使用其url的简化版本作为名称。

您可以使用 url() 短路辅助函数轻松获取路由的url或操作当前url。

url() 将返回一个 Url 对象，当渲染时返回一个 string，因此可以在模板等地方安全使用，但它包含所有有用的 Url 类方法，如 contains、indexOf 等。请参阅以下有用的url技巧。

获取当前URL

获取和/或操作当前url从未如此简单。

以下示例展示了如何获取当前url

# output: /current-url
url();

按名称获取（单个路由）

SimpleRouter::get('/product-view/{id}', 'ProductsController@show', ['as' => 'product']);

# output: /product-view/22/?category=shoes
url('product', ['id' => 22], ['category' => 'shoes']);

# output: /product-view/?category=shoes
url('product', null, ['category' => 'shoes']);

按名称获取（控制器路由）

SimpleRouter::controller('/images', ImagesController::class, ['as' => 'picture']);

# output: /images/view/?category=shows
url('picture@getView', null, ['category' => 'shoes']);

# output: /images/view/?category=shows
url('picture', 'getView', ['category' => 'shoes']);

# output: /images/view/
url('picture', 'view');

按类获取

SimpleRouter::get('/product-view/{id}', 'ProductsController@show', ['as' => 'product']);
SimpleRouter::controller('/images', 'ImagesController');

# output: /product-view/22/?category=shoes
url('ProductsController@show', ['id' => 22], ['category' => 'shoes']);

# output: /images/image/?id=22
url('ImagesController@getImage', null, ['id' => 22]);

为控制器/资源路由上的方法使用自定义名称

SimpleRouter::controller('gadgets', GadgetsController::class, ['names' => ['getIphoneInfo' => 'iphone']]);

url('gadgets.iphone');

# output
# /gadgets/iphoneinfo/

获取REST/资源控制器URL

SimpleRouter::resource('/phones', PhonesController::class);

# output: /phones/
url('phones');

# output: /phones/
url('phones.index');

# output: /phones/create/
url('phones.create');

# output: /phones/edit/
url('phones.edit');

操作URL

您可以通过添加get参数来轻松操作查询字符串。

# output: /current-url?q=cars

url(null, null, ['q' => 'cars']);

您可以通过将值设置为 null 来删除查询字符串参数。

以下示例将从url中删除任何名为 q 的查询字符串参数，但保留所有其他查询字符串参数

$url = url()->removeParam('q');

有关更多信息，请参阅文档中的有用的url技巧部分。

有用的URL技巧

调用 url 总是返回一个 Url 对象。渲染时，它将返回一个相对 url 的 string，因此可以在模板等地方安全使用。

然而，这允许我们使用 Url 对象的有用方法，如 indexOf 和 contains 或检索url的特定部分，如路径、查询字符串参数、主机等。您还可以像删除或添加参数、更改主机等一样操作url。

以下示例中，我们检查当前url是否包含 /api 部分。

if(url()->contains('/api')) {
    // ... do stuff
}

如前所述，您还可以使用 Url 对象来显示url的特定部分或控制您想要的url部分。

# Grab the query-string parameter id from the current-url.
$id = url()->getParam('id');

# Get the absolute url for the current url.
$absoluteUrl = url()->getAbsoluteUrl();

有关更多可用方法，请参阅 Pecee\Http\Url 类。

输入 & 参数

simple-router 提供了库和辅助工具，使管理输入参数（如 $_POST、$_GET 和 $_FILE）变得容易。

使用Input类管理参数

您可以使用 InputHandler 类轻松访问和管理请求中的参数。InputHandler 类提供了扩展功能，例如直接在对象上复制/移动上传的文件，获取文件扩展名、MIME类型等。

获取单个参数值

input($index, $defaultValue, ...$methods);

要快速获取参数的值，您可以使用 input 辅助函数。

这将自动修剪值并确保它不为空。如果它为空，则返回 $defaultValue。

注意：此函数返回一个 string，除非参数分组在一起，在这种情况下，它将返回值值的 array。

示例

此示例同时匹配 POST 和 GET 请求方法，如果名称为空，则返回默认值“Guest”。

$name = input('name', 'Guest', 'post', 'get');

获取参数对象

处理文件上传时，检索原始参数对象可能很有用。

在多个或特定请求方法中搜索具有默认值的对象

以下示例如果找到参数，将返回 InputItem 对象，否则返回 $defaultValue。如果参数分组，它将返回 InputItem 对象的数组。

$object = input()->find($index, $defaultValue = null, ...$methods);

以 InputItem 对象获取特定的 $_GET 参数

以下示例如果找到参数，将返回 InputItem 对象，否则返回 $defaultValue。如果参数分组，它将返回 InputItem 对象的数组。

$object = input()->get($index, $defaultValue = null);

以 InputItem 对象获取特定的 $_POST 参数

以下示例如果找到参数，将返回 InputItem 对象，否则返回 $defaultValue。如果参数分组，它将返回 InputItem 对象的数组。

$object = input()->post($index, $defaultValue = null);

以 InputFile 对象获取特定的 $_FILE 参数

以下示例如果找到参数，将返回 InputFile 对象，否则返回 $defaultValue。如果参数分组，它将返回 InputFile 对象的数组。

$object = input()->file($index, $defaultValue = null);

管理文件

/**
 * Loop through a collection of files uploaded from a form on the page like this
 * <input type="file" name="images[]" />
 */

/* @var $image \Pecee\Http\Input\InputFile */
foreach(input()->file('images', []) as $image)
{
    if($image->getMime() === 'image/jpeg') 
    {
        $destinationFilname = sprintf('%s.%s', uniqid(), $image->getExtension());
        $image->move(sprintf('/uploads/%s', $destinationFilename));
    }
}

获取所有参数

# Get all
$values = input()->all();

# Only match specific keys
$values = input()->all([
    'company_name',
    'user_id'
]);

所有对象都实现了 IInputItem 接口，并始终包含以下方法

getIndex() - 返回输入的索引/键。
getName() - 返回输入的人性化名称（例如，company_name 将是公司名称等）。
getValue() - 返回输入的值。

InputFile 具有与上述相同的方法，以及一些其他文件特定方法，如

getFilename - 获取文件名。
getTmpName() - 获取文件临时名称。
getSize() - 获取文件大小。
move($destination) - 将文件移动到目的地。
getContents() - 获取文件内容。
getType() - 获取文件的 mime-type。
getError() - 获取文件上传错误。
hasError() - 如果在上传过程中发生错误（如果 getError 不是 0），则返回 bool。
toArray() - 返回原始数组

事件

本节将帮助您了解如何将您自己的回调注册到路由器的事件中。它还将涵盖事件处理程序的基本知识；如何使用路由器提供的事件处理程序以及如何创建您自己的自定义事件处理程序。

可用事件

本节包含所有可以使用 EventHandler 注册的事件。

所有事件回调都将检索一个作为参数的 EventArgument 对象。此对象包含对事件名称、路由器和请求实例以及与给定事件相关的任何特殊事件参数的轻松访问。您可以在下面的列表中查看每个事件返回的特殊事件参数。

注册新事件

要注册新事件，您需要创建一个新的 EventHandler 对象实例。在此对象上，您可以通过调用 registerEvent 方法添加任意数量的回调。

注册事件后，请确保通过调用 SimpleRouter::addEventHandler() 将其添加到路由器中。我们建议您在 routes.php 中添加您的事件处理程序。

示例

use Pecee\SimpleRouter\Handlers\EventHandler;
use Pecee\SimpleRouter\Event\EventArgument;

// --- your routes goes here ---

$eventHandler = new EventHandler();

// Add event that fires when a route is rendered
$eventHandler->register(EventHandler::EVENT_RENDER_ROUTE, function(EventArgument $argument) {
   
   // Get the route by using the special argument for this event.
   $route = $argument->route;
   
   // DO STUFF...
    
});

SimpleRouter::addEventHandler($eventHandler);

自定义事件处理程序

EventHandler 是管理事件并必须从 IEventHandler 接口继承的类。处理程序知道如何处理给定处理程序的类型的事件。

大多数情况下，基本的 \Pecee\SimpleRouter\Handler\EventHandler 类将足以满足大多数人，因为您只需注册一个在触发时引发的事件。

让我们来了解一下如何创建您自己的事件处理程序类。

以下是一个名为 DatabaseDebugHandler 的自定义事件处理程序的示例。以下示例的目的是在触发时将所有事件记录到数据库中。希望这足以让您了解事件处理程序的工作原理。

namespace Demo\Handlers;

use Pecee\SimpleRouter\Event\EventArgument;
use Pecee\SimpleRouter\Router;

class DatabaseDebugHandler implements IEventHandler
{

    /**
     * Debug callback
     * @var \Closure
     */
    protected $callback;

    public function __construct()
    {
        $this->callback = function (EventArgument $argument) {
            // todo: store log in database
        };
    }

    /**
     * Get events.
     *
     * @param string|null $name Filter events by name.
     * @return array
     */
    public function getEvents(?string $name): array
    {
        return [
            $name => [
                $this->callback,
            ],
        ];
    }

    /**
     * Fires any events registered with given event-name
     *
     * @param Router $router Router instance
     * @param string $name Event name
     * @param array ...$eventArgs Event arguments
     */
    public function fireEvents(Router $router, string $name, ...$eventArgs): void
    {
        $callback = $this->callback;
        $callback(new EventArgument($router, $eventArgs));
    }

    /**
     * Set debug callback
     *
     * @param \Closure $event
     */
    public function setCallback(\Closure $event): void
    {
        $this->callback = $event;
    }

}

高级

URL重写

更改当前路由

有时操纵即将加载的路由很有用。simple-php-router 允许您轻松操纵和更改即将渲染的路由。关于当前路由的所有信息都存储在 \Pecee\SimpleRouter\Router 实例的 loadedRoute 属性中。

为了便于访问，您可以使用快捷助手函数 request() 来代替直接调用类 \Pecee\SimpleRouter\SimpleRouter::router()。

request()->setRewriteCallback('Example\MyCustomClass@hello');

// -- or you can rewrite by url --

request()->setRewriteUrl('/my-rewrite-url');

Bootmanager：动态加载路由

有时可能需要在数据库、文件或类似的地方存储 URL。在这个例子中，我们希望 URL /my-cat-is-beatiful 加载路由 /article/view/1，这是路由器知道的，因为它在 routes.php 文件中定义。

为了干扰路由器，我们创建了一个实现 IRouterBootManager 接口的类。这个类将在 routes.php 中的任何其他规则之前被加载，并允许我们在满足我们的任何标准（如来自 URL /my-cat-is-beatiful）的情况下“更改”当前路由。

use Pecee\Http\Request;
use Pecee\SimpleRouter\IRouterBootManager;
use Pecee\SimpleRouter\Router;

class CustomRouterRules implement IRouterBootManager 
{

    /**
     * Called when router is booting and before the routes is loaded.
     *
     * @param \Pecee\SimpleRouter\Router $router
     * @param \Pecee\Http\Request $request
     */
    public function boot(\Pecee\SimpleRouter\Router $router, \Pecee\Http\Request $request): void
    {

        $rewriteRules = [
            '/my-cat-is-beatiful' => '/article/view/1',
            '/horses-are-great'   => '/article/view/2',
        ];

        foreach($rewriteRules as $url => $rule) {

            // If the current url matches the rewrite url, we use our custom route

            if($request->getUrl()->getPath() === $url) {
                $request->setRewriteUrl($rule);
            }
        }

    }

}

上面的内容应该相当容易理解，并且可以轻松地更改以遍历存储在数据库、文件或缓存中的 URL。

发生的事情是，如果当前路由与我们的 $rewriteRules 数组索引中定义的路由匹配，我们将路由设置为该数组值。

通过这种方式，路由现在将加载 URL /article/view/1 而不是 /my-cat-is-beatiful。

最后，我们需要在 routes.php 文件中添加我们的自定义启动管理器。您可以根据需要创建尽可能多的启动管理器，并轻松地将它们添加到您的 routes.php 文件中。

SimpleRouter::addBootManager(new CustomRouterRules());

手动添加路由

前一个例子中引用的 SimpleRouter 类只是一个简单的助手类，它知道如何与 Router 类通信。如果您想接受挑战、想要完全控制或只是想创建自己的 Router 助手类，这个例子就是为您准备的。

use \Pecee\SimpleRouter\Router;
use \Pecee\SimpleRouter\Route\RouteUrl;

/* Create new Router instance */
$router = new Router();

$route = new RouteUrl('/answer/1', function() {

    die('this callback will match /answer/1');

});

$route->addMiddleware(\Demo\Middlewares\AuthMiddleware::class);
$route->setNamespace('\Demo\Controllers');
$route->setPrefix('v1');

/* Add the route to the router */
$router->addRoute($route);

参数

本节包含有关扩展参数使用的高级技巧和窍门。

扩展

这是将简单示例集成到框架中的方法。

该框架有一个自己的继承自 SimpleRouter 类的 Router 类。这允许框架添加自定义功能，例如加载自定义 routes.php 文件或添加调试信息等。

namespace Demo;

use Pecee\SimpleRouter\SimpleRouter;

class Router extends SimpleRouter {

    public static function start() {

        // change this to whatever makes sense in your project
        require_once 'routes.php';

        // change default namespace for all routes
        parent::setDefaultNamespace('\Demo\Controllers');

        // Do initial stuff
        parent::start();

    }

}

帮助和支持

本节将详细介绍如何调试路由器，并回答一些常见问题和问题。

常见问题和解决方案

本节将介绍常见问题及其解决方法。

参数不匹配或特殊字符导致路由不工作

当参数包含特殊字符时，人们经常遇到这个问题。路由器使用一个稀疏的正则表达式来匹配字母 a-z 以及数字，以匹配参数，以提高性能。

所有其他字符都必须通过您的路由上的 defaultParameterRegex 选项进行定义。

您可以通过点击这里了解有关为匹配参数添加自己的自定义正则表达式的更多信息。

多个路由匹配？哪个优先级最高？

路由器将按照它们添加的顺序匹配路由。

可以渲染多个路由。

如果要让路由器在匹配到路由时停止，您只需在回调中返回一个值或手动停止执行（使用 response()->json() 等）。

任何实现了 __toString() 魔法方法的返回对象也将阻止其他路由的渲染。

在子路径上使用路由器

在类似 localhost/project/ 的子路径上使用库官方不支持，但可以相当容易地让它工作。

添加一个事件，在添加新的可加载路由时附加您的子路径。

示例

// ... your routes.php file

if($isRunningLocally) {

    $eventHandler = new EventHandler();
    $eventHandler->register(EventHandler::EVENT_ADD_ROUTE, function (EventArgument $arg) use (&$status) {

        if ($arg->route instanceof \Pecee\SimpleRouter\Route\LoadableRoute) {
            $arg->route->prependUrl('/local-path');
        }

    });

    TestRouter::addEventHandler($eventHandler);

}

调试

本节将向您展示如何为路由器编写单元测试，查看有用的调试信息，并回答一些经常问的问题。

它还将涵盖如何报告您可能遇到的问题。

创建单元测试

调试路由器问题的最简单、最快方法是创建一个代表您所遇到问题的单元测试。

单元测试使用一个特殊的 TestRouter 类，该类模拟浏览器的请求方法和请求 URL。

TestRouter 类可以直接返回输出或静默渲染路由。

public function testUnicodeCharacters()
{
    // Add route containing two optional paramters with special spanish characters like "í".
    TestRouter::get('/cursos/listado/{listado?}/{category?}', 'DummyController@method1', ['defaultParameterRegex' => '[\w\p{L}\s-]+']);
    
    // Start the routing and simulate the url "/cursos/listado/especialidad/cirugía local".
    TestRouter::debugNoReset('/cursos/listado/especialidad/cirugía local', 'GET');
    
    // Verify that the url for the loaded route matches the expected route.
    $this->assertEquals('/cursos/listado/{listado?}/{category?}/', TestRouter::router()->getRequest()->getLoadedRoute()->getUrl());
    
    // Start the routing and simulate the url "/test/Dermatología" using "GET" as request-method.
    TestRouter::debugNoReset('/test/Dermatología', 'GET');

    // Another route containing one parameter with special spanish characters like "í".
    TestRouter::get('/test/{param}', 'DummyController@method1', ['defaultParameterRegex' => '[\w\p{L}\s-\í]+']);

    // Get all parameters parsed by the loaded route.
    $parameters = TestRouter::request()->getLoadedRoute()->getParameters();

    // Check that the parameter named "param" matches the exspected value.
    $this->assertEquals('Dermatología', $parameters['param']);

    // Add route testing danish special characters like "ø".
    TestRouter::get('/category/økse', 'DummyController@method1', ['defaultParameterRegex' => '[\w\ø]+']);
    
    // Start the routing and simulate the url "/kategory/økse" using "GET" as request-method.
    TestRouter::debugNoReset('/category/økse', 'GET');
    
    // Validate that the URL of the loaded-route matches the expected url.
    $this->assertEquals('/category/økse/', TestRouter::router()->getRequest()->getLoadedRoute()->getUrl());

    // Reset the router, so other tests wont inherit settings or the routes we've added.
    TestRouter::router()->reset();
}

使用 TestRouter 辅助工具

根据您的测试，您可以在单元测试中渲染路由时使用以下方法。

调试信息

该库可以输出调试信息，其中包含诸如已加载的路由、解析的请求 URL 等信息。它还包含在报告新问题时重要的信息，例如 PHP 版本、库版本、服务器变量、路由调试日志等。

您可以通过调用替代的启动方法来激活调试信息。

下面的示例将启动路由并返回包含调试信息的数组

示例

$debugInfo = SimpleRouter::startDebug();
echo sprintf('<pre>%s</pre>', var_export($debugInfo));
exit;

上面的示例将提供包含以下内容的输出

基准和日志

您可以通过在 Router 实例上调用 setDebugEnabled 方法来激活基准调试/日志记录。

您必须在启动路由之前启用调试。

示例

SimpleRouter::router()->setDebugEnabled(true);
SimpleRouter::start();

路由完成后，您可以通过在 Router 实例上调用 getDebugLog() 来获取调试日志。这将返回一个包含执行时间、跟踪信息和调试信息的日志消息的 array。

示例

$messages = SimpleRouter::router()->getDebugLog();

报告新问题

在报告您的问题之前，请确保您所遇到的问题在常见错误部分或 GitHub 上的已关闭问题页面上已有答案。

为了减少混淆并尽快解决您的问题，您应提供关于您遇到的问题的详细说明。

报告新问题的程序

前往此页面创建新问题。
尽可能用最少的词语添加标题描述您的问题。
将以下模板复制并粘贴到您问题的描述中，并用您自己的信息替换每个步骤。如果步骤与您的问题无关，您可以删除它。

问题模板

将以下模板复制并粘贴到您新问题的描述中，并用您自己的信息替换它。

您可以在调试信息部分查看如何生成调试信息。

### Description

The library fails to render the route `/user/æsel` which contains one parameter using a custom regular expression for matching special foreign characters. Routes without special characters like `/user/tom` renders correctly.

### Steps to reproduce the error

1. Add the following route:

```php
SimpleRouter::get('/user/{name}', 'UserController@show')->where(['name' => '[\w]+']);
```

2. Navigate to `/user/æsel` in browser.

3. `NotFoundHttpException` is thrown by library.

### Route and/or callback for failing route

*Route:*

```php
SimpleRouter::get('/user/{name}', 'UserController@show')->where(['name' => '[\w]+']);
```

*Callback:*

```php
public function show($username) {
    return sprintf('Username is: %s', $username);
}
```

### Debug info

```php

[PASTE YOUR DEBUG-INFO HERE]

```

请记住，更详细的 issue 描述和调试信息可能难以编写，但它们将帮助他人理解和解决您的问题，而无需询问信息。

注意：在创建新问题时，请尽可能详细地描述。这将帮助他人更容易地理解和解决您的问题。在描述中提供重现错误的必要步骤、添加有用的调试信息等将帮助他人快速解决您报告的问题。

反馈和发展

如果库缺少您在项目中需要的功能，或者如果您有反馈，我们非常愿意听取您的意见。请通过创建新问题向我们留下反馈。

遇到问题了吗？

在报告新问题之前，请先参阅文档中的帮助和支持部分。

贡献开发指南

请尝试遵循 PSR-2 代码风格指南。
请将您的拉取请求创建到与您要更改的版本号匹配的开发基础。例如，当推送更改到版本 3 时，拉取请求应使用 v3-development 基础/分支。
为您的提交创建详细的描述，因为这些将用于新版本发布时的变更日志。
修改现有功能时，请确保单元测试仍在工作。
添加新内容时，请记得为该功能添加新的单元测试。

致谢

网站

以下是一些在生产环境中使用simple-router项目的网站。

许可

MIT许可（MIT）

特此授予任何获得此软件及其相关文档文件（以下简称“软件”）副本的人，在不受限制的情况下使用软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本，并允许向软件提供者提供软件的人进行此类操作，前提是遵守以下条件

eightsystems / simple-router

维护者

详细信息

README

支持项目

目录

入门

注意事项

要求

特性

安装

设置Nginx

设置Apache

.htaccess示例

设置IIS

web.config示例

故障排除

配置

辅助函数

路由

基本路由

可用方法

多个HTTP动词

路由参数

必需参数

可选参数

正则表达式约束

正则表达式路由匹配

自定义正则表达式匹配参数

示例

命名路由

生成命名路由的URL

路由分组

中间件

命名空间

注意

子域名路由

路由前缀

部分分组

表单方法欺骗

访问当前路由

依赖注入

启用依赖注入

为开发环境启用

为生产环境启用

更多阅读

有用链接

其他示例

CSRF保护

添加CSRF验证器

获取CSRF令牌

自定义CSRF验证器

自定义Token Provider

中间件

示例

异常处理程序

处理404、403和其他错误

使用自定义异常处理程序

URLs

获取当前URL

按名称获取（单个路由）

按名称获取（控制器路由）

按类获取

为控制器/资源路由上的方法使用自定义名称

获取REST/资源控制器URL

操作URL

有用的URL技巧

输入 & 参数

使用Input类管理参数

获取单个参数值

获取参数对象

管理文件

获取所有参数

事件

可用事件

注册新事件

自定义事件处理程序

高级

URL重写

更改当前路由