README

Wrench 是一个 CakePHP 3.X 插件，旨在提供一个简单的方式来为您的 CakePHP 网站/应用程序实现维护模式。

需求

PHP >= 5.5.9
CakePHP >= 3.3.0

关于插件版本

安装

您可以使用 composer 将此插件安装到您的 CakePHP 应用程序中。

安装 composer 包的推荐方法是

composer require havokinspiration/wrench

加载插件

您可以使用以下 shell 命令加载插件

bin/cake plugin load Wrench

或者，您可以在应用程序的 boostrap.php 文件中手动添加加载语句

Plugin::load('Wrench');

用法

此插件围绕一个 中间件 构建，该中间件将拦截当前请求并返回一个定制的响应，以警告用户网站/应用程序正在维护中。

要使用维护模式，您需要在应用程序文件中将 MaintenanceMiddleware 添加到 MiddlewareStack 中，添加以下元素

use Wrench\Middleware\MaintenanceMiddleware;

// ...

public function middleware($middleware)
{
    $middleware->add(new MaintenanceMiddleware());

    // Other middleware configuration

    return $middleware;
}

由于此中间件的作用是防止应用程序响应，它应该是第一个被分配器处理的，因此应将其配置为第一个，无论是通过在方法开始处使用 push() 方法添加它，还是使用 prepend() 方法在中间件配置中的任何位置添加它。

默认情况下，仅添加上一行将启用 重定向 模式。有关维护模式的更多信息，请参阅下文。

当 Configure 键 Wrench.enable 等于 true 时，中间件才处于活动状态。要启用维护模式，请在您的 bootstrap.php 文件中使用以下语句

Configure::write('Wrench.enable', true);

模式

此插件围绕“模式”的概念构建。模式是具有处理请求并返回适当的响应以警告用户网站/应用程序正在维护的特殊类。

此插件包含四个维护模式：重定向、输出、回调和视图。

您可以通过将参数传递给中间件构造函数，在将中间件添加到中间件堆栈时配置它以使用特定的模式。这会产生如下调用

$middleware->add(new MaintenanceMiddleware([
    'mode' => [
        'className' => 'Full\Namespace\To\Mode',
        'config' => [
            // Specific configuration parameters for the Mode
        ]
    ]
]);

如果需要，您可以直接将 Mode 的实例传递给过滤器的配置数组中的 mode 数组键

$middleware->add(new MaintenanceMiddleware([
    'mode' => new \Wrench\Mode\Redirect([
        'url' => 'http://example.com/maintenance'
    ])
]);

IP 白名单

当您将应用程序置于维护状态时，作为项目管理员或开发人员，您可能希望能够访问应用程序。您可以使用 IP 白名单功能来实现这一点。在配置 MaintenanceMiddleware 时，只需将允许的 IP 地址数组传递给中间件配置数组中的 whitelist 键即可。所有这些 IP 都将被允许访问应用程序，即使维护模式处于开启状态

$middleware->add(new MaintenanceMiddleware([
    'whitelist' => ['1.2.3.4', '5.6.7.8'],
]));

在上面的示例中，使用 IP 地址 1.2.3.4 或 5.6.7.8 连接的客户端将能够访问项目，即使维护模式处于开启状态。

重定向模式

重定向模式是默认模式。它将执行到特定URL的重定向。重定向模式接受以下参数

url：重定向应指向的URL。默认为应用基本路径指向一个maintenance.html页面。
code：重定向响应的HTTP状态码。状态码应在3XX范围内，否则可能会被覆盖。默认为307。
headers：传递给重定向响应的额外头信息数组。默认为空。

您可以自定义所有这些参数

$middleware->add(new MaintenanceMiddleware([
    'mode' => [
        'className' => 'Wrench\Mode\Redirect',
        'config' => [
            'url' => 'http://example.com/maintenance',
            'code' => 303,
            'headers' => ['someHeader' => 'someValue']
        ]
    ]
]);

输出模式

输出模式允许您将静态文件的内容作为维护状态的响应显示。它接受多个参数

path：要服务的文件的绝对路径。默认为{ROOT}/maintenance.html。
code：重定向响应的HTTP状态码。默认为503。
headers：传递给重定向响应的额外头信息数组。默认为空。

您可以自定义所有这些参数

$middleware->add(new MaintenanceMiddleware([
    'mode' => [
        'className' => 'Wrench\Mode\Output',
        'config' => [
            'path' => '/path/to/my/file',
            'code' => 404,
            'headers' => ['someHeader' => 'someValue']
        ]
    ]
]);

回调模式

回调模式允许您使用自定义的可调用函数。它仅接受一个参数callback，该参数应是一个可调用函数。可调用函数将接受两个参数

request：一个\Psr\Http\Message\ServerRequestInterface实例
response：一个\Psr\Http\Message\ResponseInterface实例

如果请求需要停止，可调用函数应返回一个\Psr\Http\Message\ResponseInterface。

$middleware->add(new MaintenanceMiddleware([
    'mode' => [
        'className' => 'Wrench\Mode\Callback',
        'config' => [
            'callback' => function($request, $response) {
                $string = 'Some content from a callback';

                $stream = new Stream(fopen('php://memory', 'r+'));
                $stream->write($string);
                $response = $response->withBody($stream);
                $response = $response->withStatus(503);
                $response = $response->withHeader('someHeader', 'someValue');
                return $response;
            }
        ]
    ]
]);

视图模式

视图模式允许您使用视图来渲染维护页面。这使您能够利用辅助器和框架的布局/模板系统。它接受多个参数

code：重定向响应的HTTP状态码。默认为503。
headers：传递给重定向响应的额外头信息数组。默认为空。
view：传递给视图类构造函数的参数数组。仅支持以下选项
- className：要使用的视图类的完全限定类名。默认为AppView
- templatePath：要显示的模板的路径（相对于您的src/Template目录）。您可以使用插件点表示法。
- template：要使用的模板名称。默认为"maintenance"。
- plugin：要查找布局和模板的主题
- theme：与插件相同
- layout：要使用的布局名称。默认为"default"。
- layoutPath：要显示的布局的路径（相对于您的src/Template目录）。您可以使用插件点表示法。默认为"Layout"。

// Will load a template ``src/Template/Maintenance/maintenance.ctp``
// in a layout ``src/Template/Layout/Maintenance/maintenance.ctp``
$middleware->add(new MaintenanceMiddleware([
    'mode' => [
        'className' => 'Wrench\Mode\View',
        'config' => [
            'view' => [
                 'templatePath' => 'Maintenance',
                 'layout' => 'maintenance',
                 'layoutPath' => 'Maintenance'
            ]
        ]
    ]
]);

创建自定义模式

如果您有特殊需求，您可以创建自己的维护模式。要快速入门，您可以使用bake控制台工具生成一个骨架

bin/cake bake maintenance_mode MyCustomMode

这将生成位于App\Maintenance\Mode命名空间下的MyCustomMode类文件（以及一个测试文件）。您的骨架将只包含一个方法process()，返回一个\Psr\Http\Message\ResponseInterface对象。这是维护模式逻辑的地方。您可以选择使该方法返回一个ResponseInterface对象，这将简化请求周期并使用返回的ResponseInterface对象来响应请求。任何其他返回值都将使维护模式无效，请求周期将继续。如果您需要在特定条件下仅显示维护状态，这很有用。

模式实现了InstanceConfigTrait，这使得您能够轻松地定义默认配置参数，并让您轻松访问它们。

请记住，您需要返回的ResponseInterface必须遵守PSR-7规范。您可以在PHP-FIG网站以及CakePHP文档上获取有关实现和如何与之交互的更多详细信息。

您可以查看已实现的模式以获取一些示例。

有条件地应用维护模式

由于目前 CakePHP 3.3 中中间件栈的实现，有条件地应用中间件目前不可行。当且仅当此功能在核心中实现时，将会添加相关的文档。

贡献

如果您发现了一个错误或者想要请求一个功能，请使用 GitHub 问题追踪器。如果您想要提交一个修复或功能，请fork仓库并提交一个拉取请求。

编码规范

由于此插件与 CakePHP 核心的功能纠缠在一起，为了提供一致性，它遵循 CakePHP 编码规范。在提交拉取请求时，请确保您的代码遵循这些规范。您可以通过安装代码嗅探器来检查。

composer require cakephp/cakephp-codesniffer:dev-master

然后运行嗅探器

./vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP ./src ./tests

许可证

版权（c）2015 - 2017，Yves Piquel，并许可在 MIT 许可证下。请参阅 LICENSE.txt 文件。

havokinspiration / wrench

维护者

详细信息