README

Kirby Middleware

Kirby Middleware 提供了一种强大的机制，用于检查和过滤进入您的 Kirby 网站的请求。

概述

• 1. 安装
• 2. 使用
• 3. 中间件
• 4. 选项
• 5. 门面
• 6. 插件
• 7. 路线图
• 8. 许可证
• 9. 致谢

安装

下载

下载并将此存储库复制到 /site/plugins/kirby-middleware。

Composer

composer require beebmx/kirby-middleware

使用

开箱即用，您无需进行任何操作即可开始使用（除了安装）。当您安装 Kirby Middleware 包时，它提供了两种管理中间件的方式，即 global 中间件和 groups 中间件。

全局中间件

此中间件将在每个 Page 上通过 Middleware 处理程序始终触发。开箱即用附带一个 TrimStrings 中间件，该中间件将删除请求中的空格。

注意

要访问此请求，您应调用 Beebmx\KirbyMiddleware\Request 实例。

Kirby\Http\Request 实例将不会被修改。

您可以使用以下方式访问经过转换的 Request 实例：

use Beebmx\KirbyMiddleware\Request;

$request = Request::instance();

您可以在您的 config.php 文件中添加 global 中间件的特性

'beebmx.kirby-middleware' => [
    'global' => [
        MyOwnGlobalMiddleware::class,
    ],
],

注意

您可以添加所需的任何中间件数量。

它们可以是 class 或 Closure。

TrimStrings

TrimStrings 清除请求中的所有输入，但有时您需要跳过一些要修剪的 inputs；您可以使用以下方式跳过它：

'beebmx.kirby-middleware' => [
    'exceptions' => [
        'trim' => [
            'password',
            'password_confirmation',
        ],
    ],
],

并且您可以使用 Request 实例在您的控制器、模型或任何需要的地方恢复这些 inputs

use Beebmx\KirbyMiddleware\Request;

Request::instance()->get('yourInput')

或者为了方便，您可以使用门面

use Beebmx\KirbyMiddleware\Facades\Request;

Request::get('yourInput')

组中间件

组中间件将依赖于路由来触发。默认情况下，组中间件附带 web、auth 和 guest 中间件，它包含一个 ValidateCsrfToken 中间件。

您可以通过在 config.php 文件中添加 routes 值来设置路由

'beebmx.kirby-middleware' => [
    'routes' => [
        'web' => [
            'blog/(:any)',
            'content/(:alpha)',
            'page/(:num)',
        ]
    ],
],

注意

您可以在 config.php 文件中添加一个与任何 Kirby 路由类似的 pattern

默认情况下，web 组附带 (:all) 路由。

auth 和 guest 中间件默认不活动，但您可以自定义路由来启用它们。

当然，您可以在您的 config.php 文件中添加更多功能到 web 中间件

'beebmx.kirby-middleware' => [
    'web' => [
        MyOwnMiddleware::class,
    ],
],

如果 web 组不是您需要的，您可以在 config.php 文件中添加新的中间件组。您可以在 config.php 文件中添加它

'beebmx.kirby-middleware' => [
    'groups' => [
        MyOwnMiddlewareGroup::class,
    ],
],

中间件组应如下所示

use Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup;

class MyOwnMiddlewareGroup extends MiddlewareGroup
{
    public string $name = 'review';

    public string|array|null $routes = [
        'blog/(:any)',
        'content/(:alpha)',
    ];

    public array $group = [
        ReviewBlogMiddleware::class,
        ReviewContentMiddleware::class,
        ReviewByAuthorMiddleware::class,
    ];
}

重要

所有组中间件类都应该扩展 Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup 类。

ValidateCsrfToken

当您在模板中使用 HTML 表单进行 POST、PUT、PATCH 或 DELETE 时，您应在表单中包含一个隐藏的 CSRF _token 字段，以便 CSRF 保护中间件可以验证请求。

<form method="POST" action="myPage">
    <input type="hidden" name="_token" value="<?= csrf() ?>" />
</form>

注意

为了方便起见，您也可以使用 csrf、csrf-token 或 _token。

有时您需要忽略一些来自CSRF验证的路由；您可以使用安全中间件来跳过它。

'beebmx.kirby-middleware' => [
    'exceptions' => [
        'csrf' => [
            'payment',
            'test',
        ],
    ],
],

安全中间件

Kirby Middleware自带两个中间件（auth和guest），可以根据用户认证来提高您的安全流程。

认证中间件

auth中间件提供了一个起点来验证用户是否认证，以及用户是否有权访问给定的路由。如果没有，它将重定向到某个URL进行适当的登录。

以下是一个示例

'beebmx.kirby-middleware' => [
    'routes' => [
      'auth' => [
            'dashboard',
            'dashboard/(:all)',
            'logout',
        ],
    ],
    'redirections' => [
        'guest' => 'login',
    ],
],

注意

如果用户未认证，中间件将重定向到guest页面。

访客中间件

guest中间件提供了一个起点来验证访客是否为访客且未认证。如果用户已认证，它将重定向到某个URL进入一个受保护的欢迎页面或仪表板。

以下是一个示例

'beebmx.kirby-middleware' => [
    'routes' => [
        'guest' => [
            'login',
        ],
    ],
    'redirections' => [
        'auth' => 'dashboard',
    ],
],

注意

如果用户已认证，中间件将重定向到auth页面。

中间件

当您创建中间件时，您可以使用一个类或一个闭包；它将取决于您的需求和复杂性。

中间件类

当您创建自己的中间件类时，它应该看起来像

use Beebmx\KirbyMiddleware\Request;
use Closure;

class ValidateSomeInformation
{
    public function handle(Request $request, Closure $next)
    {
        // Perform action

        return $next($request);
    }
}

如您所见，handle需要两个参数：一个名为$request的Request和一个名为$next的闭包。该$request包含通过钩子route:before在Kirby中执行的当前请求。

第二个参数$next，您应在处理过程结束时调用它以继续到下一个中间件验证，使用$request。

如果您需要，一些验证可以阻止继续进行其他验证；您可以抛出一个错误或进行响应重定向

use Beebmx\KirbyMiddleware\Request;
use Closure;
use Kirby\Http\Response;

class UserShouldBeAuthenticated
{
    public function handle(Request $request, Closure $next)
    {
        if(empty($request->user())) {
            return Response::redirect('login')
        }

        return $next($request);
    }
}

或者用一个异常

use Beebmx\KirbyMiddleware\Request;
use Closure;
use Kirby\Exception\ErrorPageException;

class UserShouldBeAuthenticated
{
    public function handle(Request $request, Closure $next)
    {
        if(empty($request->user())) {
            return throw new ErrorPageException([
                'fallback' => 'Unauthorized',
                'httpCode' => 401,
            ]);
        }

        return $next($request);
    }
}

闭包中间件

添加global、web、auth或guest中间件的最简单方法是使用一个闭包；当您添加一个闭包时，它应该看起来像

use Beebmx\KirbyMiddleware\Request;
use Closure;

'beebmx.kirby-middleware' => [
    'web' => [
        function (Request $request, Closure $next) {
            // Perform action

            return $next($request);
        },
    ],
],

重要

请记住调用$next闭包以继续使用$request进行下一个验证。

选项

禁用中间件

您可以通过更新config.php文件中的enable值完全禁用所有中间件验证

'beebmx.kirby-middleware' => [
    'enabled' => false,
],

外观

有一些外观可以简化此插件的使用

插件

如果您正在创建自己的插件，并且需要使用某些类型的需求请求操作，Kirby Middleware也适合您。

安装

首先，您需要通知Kirby Middleware您有一些global中间件或group中间件要注册。

最简单的方法是使用钩子

use Kirby\Cms\App as Kirby;
use Beebmx\KirbyMiddleware\Facades\Middleware;

Kirby::plugin('beebmx/kirby-security', [
    'hooks' => [
        'system.loadPlugins:after' => function () {
            Middleware::appendToGroup('security', [
                ValidateUser::class,
                ValidateUserRole::class,
                ValidateUserTeam::class,
            ]);
        },
    ],
]);

全局方法

您可以将自己的验证添加到global中间件。为此，您有几种方法。

追加

append方法将中间件添加到global中间件的末尾。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::append(ValidateVisitor::class);

前置

prepend方法将中间件添加到global中间件的开头。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::prepend(ValidateVisitor::class);

getGlobalMiddleware

getGlobalMiddleware方法返回已注册的所有global中间件的数组。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::getGlobalMiddleware();

组方法

您可以将自己的验证添加到groups中间件。为此，您有几种方法。

追加

appendToGroup方法将中间件添加到groups中间件的末尾。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::appendToGroup('security', [
    ValidateUser::class,
    ValidateUserRole::class,
    ValidateUserTeam::class,
]);

prependToGroup

prependToGroup方法将中间件添加到groups中间件的开头。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::prependToGroup('security', [
    ValidateUser::class,
    ValidateUserRole::class,
    ValidateUserTeam::class,
]);

removeFromGroup

removeFromGroup方法从一个特定的group中间件中删除某些中间件。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::removeFromGroup('security', ValidateVisitor::class);

addClassToGroup

addClassToGroup 方法将 Middleware Group 类添加到 groups 中间件中。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::addClassToGroup(SecurityMiddlewareGroup::class);

getMiddlewareGroups

getMiddlewareGroups 方法返回所有已注册的 groups 中间件的数组。

use Beebmx\KirbyMiddleware\Facades\Middleware;

Middleware::getMiddlewareGroups();

认证中间件

您可以在不使用选项的情况下自定义 Authenticate 中间件，但需要挂钩到 system.loadPlugins:after。

redirectUsing

设置路由，如果用户未认证则进行重定向。

use Beebmx\KirbyMiddleware\Middlewares\Authenticate;

Authenticate::redirectUsing('login');

setRoutes

如果您想为 AuthMiddlewareGroup 设置路由。

use Beebmx\KirbyMiddleware\MiddlewareGroups\AuthMiddlewareGroup;

AuthMiddlewareGroup::setRoutes([
    'dashboard',
    'logout',
]);

RedirectIfAuthenticated 中间件

您可以在不使用选项的情况下自定义 RedirectIfAuthenticated 中间件，但需要挂钩到 system.loadPlugins:after。

redirectUsing

设置路由，如果用户已认证则进行重定向。

use Beebmx\KirbyMiddleware\Middlewares\RedirectIfAuthenticated;

RedirectIfAuthenticated::redirectUsing('dashboard');

setRoutes

如果您想为 GuestMiddlewareGroup 设置路由。

use Beebmx\KirbyMiddleware\MiddlewareGroups\GuestMiddlewareGroup;

GuestMiddlewareGroup::MiddlewareGroup::setRoutes([
    'login',
]);

重要

请记住，所有的组中间件类都应该扩展 Beebmx\KirbyMiddleware\MiddlewareGroups\MiddlewareGroup 类。

路线图

• 自定义挂钩
• 默认情况下更多 global 中间件
• 默认情况下更多 web 中间件
• 一个 auth 中间件组。
• 一个 guest 中间件组。

许可证

根据 MIT 许可证发布。

致谢

• Fernando Gutierrez @beebmx
• 所有贡献者