README

Janitor

PSR7的轻松维护管理。

Janitor是一个可立即使用的PSR7包，它以易于配置和扩展的方式提供了一种处理项目维护模式的方法，因为维护处理不仅仅是向用户返回HTTP 503代码和简单消息。

设置几个条件，以确定是否应触发维护处理程序。这些条件有两种类型，'激活'条件（命名为watchers）和绕过正常执行的条件（命名为excluders）。

已经内置的watchers和excluders允许您覆盖广泛的场景，因此您可以快速将Janitor放入并开始使用，但与此同时，如果需要，创建自己的条件也非常容易，只需实现相应的接口即可。

一旦Janitor确定维护模式已激活，它允许您使用自己的处理程序获取为用户准备好的响应，或者您可以让Janitor自行处理（一个格式良好的503响应）。

在Janitor的页面上了解更多信息

安装

最佳安装方法是使用Composer

composer require juliangut/janitor

然后要求自动加载文件

require_once './vendor/autoload.php';

用法

use Janitor\Excluder\IP as IPExcluder;
use Janitor\Excluder\Path as PathExcluder;
use Janitor\Runner as Janitor;
use Janitor\Watcher\WatcherInterface;
use Janitor\Watcher\File as FileWatcher;
use Janitor\Watcher\Cron as CronWatcher;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Zend\Diactoros\Response;
use Zend\Diactoros\ServerRequestFactory;

$watchers = [
    new FileWatcher('/tmp/maintenance'),
    new CronWatcher('0 0 * * 0', new \DateInterval('PT2H')),
];
$excluders = [
    new IPExcluder('127.0.0.1'),
    new PathExcluder(['/maintenance', '/^\/admin/']),
];

$handler = function (ServerRequestInterface $request, ResponseInterface $response, WatcherInterface $watcher) {
    $response->getBody()->write('This page is in maintenance mode!');

    return $response;
}

$activeWatcherAttributeName = 'maintenance_watcher'; // Default is 'active_watcher'
$janitor = new Janitor($watchers, $excluders, $handler, $activeWatcherAttributeName);

$response = $janitor(
    ServerRequestFactory::fromGlobals(),
    new Response('php://temp'),
    function ($request, $response) use ($activeHandlerAttributeName) {
        $activeHandler = $request->getAttribute($activeHandlerAttributeName);
        // ...
    }
);

如果在任何给定时间点激活了任何watcher（因此维护模式也是），则它将被附加到请求对象上，以便在执行过程中检索。

关注者

watchers通过验证条件来激活不同的维护模式。

• 手动将其设置为激活。与配置参数一起使用很有用。
• 文件检查提供的文件是否存在。
• 环境检查环境变量是否设置为特定值。

$manualWatcher = new \Janitor\Watcher\Manual(true);
// Always active
$manualWatcher->isActive();

$fileWatcher = new \Janitor\Watcher\File('/tmp/maintenance');
// Active if /tmp/maintenance file exists
$fileWatcher->isActive();

$envWatcher = new \Janitor\Watcher\Environment('maintenance', 'ON');
// Active if 'maintenance' environment variable value is 'ON'
$envWatcher->isActive();

计划好的watchers

计划好的watchers是特殊类型的watchers，它们标识未来的某个时间点进行维护的时间段。

• 固定为计划维护时间段设置固定的开始和/或结束时间。
• Cron使用cron表达式语法设置维护时间段。

$fixedWatcher = new \Janitor\Watcher\Fixed('2026/01/01 00:00:00', '2026/01/01 01:00:00');
// Active only 1st January 2026 at midnight for exactly 1 hour
$fixedWatcher->isActive();

$cronWatcher = new \Janitor\Watcher\Cron('0 0 1 * *', new \DateInterval('PT2H'));
// Active the first day of each month at midnight during 2 hours
$cronWatcher->isActive();

从计划好的watcher中，您可以获取即将到来的维护时间段列表

$cronWatcher = new \Janitor\Watcher\Cron('0 0 1 * *', new \DateInterval('PT2H'));
// Array of ['start' => \DateTime, 'end' => \DateTime] of next maintenance periods
$scheduledPeriods = $cronWatcher->getScheduledTimes(10);

watchers将按照添加的顺序进行检查，一旦激活了一个watcher，其余的将不再进行检查。

如果您定期执行维护任务（可能在每周的同一天），您可能希望使用Cron watcher来标识日期和时间段，或者使用文件 watcher来监视系统中的文件，并将维护过程设置为touch和rm该文件作为维护过程的一部分。

Cron watcher使用Michael Dowling的cron-expression。

Excluders

Excluders设置条件以绕过维护模式，以便允许某些人员通过或允许访问某些页面。

• IP验证用户的IP以允许访问。
• 路径排除某些URL路径的维护。
• 基本认证基于请求的授权头进行排除。
• 头部基于请求头的值进行排除。

$ipExcluder = new \Janitor\Excluder\IP('127.0.0.1');
// Users accessing from IP 127.0.0.1 are excluded
$ipExcluder->isExcluded($request);

$pathExcluder = new \Janitor\Excluder\Path('/maintenance');
// Users accessing 'http://yourdomain.com/maintenance' are excluded
$pathExcluder->isExcluded($request);

$pathExcluderRegex = new \Janitor\Excluder\Path('/^\/admin/');
// Can also be a regex
$pathExcluderRegex->isExcluded($request);

$basicAuthExcluder = new \Janitor\Excluder\BasicAuth(['root' => 'secret']);
// Users accessing with basic authorization 'root' user are excluded
$basicAuthExcluder->isExcluded($request);

$headerExcluder = new \Janitor\Excluder\Header('X-Custom-Header', 'custom');
// Users accessing with 'X-Custom-Header' header's value 'custom' are excluded
$headerExcluder->isExcluded($request);

$headerExcluderRegex = new \Janitor\Excluder\Header('X-Custom-Header', '/^custom/');
// Again a regex can be used
$headerExcluderRegex->isExcluded($request);

在添加excluders时，请考虑它们将按照添加的顺序进行检查，因此当一个excluder条件满足时，其余的excluders将不再测试。首先添加更通用的excluders，然后添加更具体的excluders。

通常，您需要排除团队的IP地址以及某些页面，例如维护或管理区域。

处理器

为了处理维护模式，任何可调用对象都可以提供给setHandler方法，前提是它遵循此签名：

function (\Psr\Http\Message\ServerRequestInterface $request, \Psr\Http\Message\ResponseInterface $response, \Janitor\Watcher\WatcherInterface $watcher);

默认提供了两个非常基本的处理器来应对维护模式。

• Render通过设置响应为503代码，并基于请求的Accept头添加基本的格式化维护输出。
• Redirect准备将响应设置为302重定向到配置的URL（通常是维护页面）。

在这两个中，如果没有提供，则自动创建并使用Render。

计划维护服务

如果使用计划监视器，则可以打开显示未来维护时间表的选择，例如在专门用于通知用户未来维护操作的页面上。

use Janitor\Runner as Janitor;
use Janitor\Watcher\Cron;
use Zend\Diactoros\Response;
use Zend\Diactoros\ServerRequestFactory;

$watchers = [new Cron('0 0 1 * *', new \DateInterval('PT2H'));];

$janitor = new Janitor($watchers);

$response = $janitor(
    ServerRequestFactory::fromGlobals(),
    new Response('php://temp'),
    function ($request, $response) use ($janitor) {
        // Array of ['start' => \DateTime, 'end' => \DateTime]
        $scheduledPeriods = $janitor->getScheduledTimes();
    }
);

示例

Slim3

use Janitor\Runner as Janitor;
use Slim\App;

$watchers = [];
$excluders = [];

$app = new App();

// Add middleware (using default Render handler)
$app->add(new Janitor($watchers, $excluders));

$app->run();

Zend Expressive

use Janitor\Handler\Redirect;
use Janitor\Runner as Janitor;
use Zend\Expresive\AppFactory;

$watchers = [];
$excluders = [];
$handler = new Redirect('/maintenance');

$app = AppFactory::create();

// Add middleware
$app->pipe(new Janitor($watchers, $excluders, $handler));

$app->run();

Symfony的HttpFoundation

如果您使用的是Symfony的HttpFoundation，您仍然可以通过使用Symfony的PSR HTTP消息桥接器将Janitor添加到您的工具箱中。

使用Silex的一个示例

use Janitor\Runner as Janitor;
use Silex\Application;
use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory;
use Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory;
use Symfony\Component\HttpFoundation\Request;
use Zend\Diactoros\Response;

$janitor = new Janitor();

$app = new Application;

$app->before(function (Request $request, Application $app) use ($janitor) {
    $response = $janitor(
        (new DiactorosFactory)->createRequest($request),
        new Response('php://temp'),
        function ($request, $response) {
            return $response;
        }
    );

    return (new HttpFoundationFactory)->createResponse($response);
});

$app->run();

贡献

发现了一个错误或有一个功能请求？ 请打开一个新的问题。在提出请求之前，请查看现有的问题。

请参阅文件CONTRIBUTING.md

许可

请参阅源代码中包含的文件LICENSE以获取许可条款的副本。