README

Yii 2 的 Crontab 扩展

此扩展添加了对 Crontab 设置的支持。

有关许可证信息，请查看 LICENSE 文件。

要求

此扩展需要 Linux 操作系统。应安装 'crontab' 并运行 cron 守护进程。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令

php composer.phar require --prefer-dist yii2tech/crontab

或将其添加到您的 composer.json 文件的要求部分。

"yii2tech/crontab": "*"

使用

您可以使用 [[yii2tech\crontab\CronTab]] 来设置 cron tab，例如

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->setJobs([
    [
        'min' => '0',
        'hour' => '0',
        'command' => 'php /path/to/project/yii some-cron',
    ],
    [
        'line' => '0 0 * * * php /path/to/project/yii another-cron'
    ]
]);
$cronTab->apply();

您也可以使用 [[yii2tech\crontab\CronJob]] 实例指定特定的 cron 作业，例如

use yii2tech\crontab\CronJob;
use yii2tech\crontab\CronTab;

$cronJob = new CronJob();
$cronJob->min = '0';
$cronJob->hour = '0';
$cronJob->command = 'php /path/to/project/yii some-cron';

$cronTab = new CronTab();
$cronTab->setJobs([
    $cronJob
]);
$cronTab->apply();

提示：[[yii2tech\crontab\CronJob]] 是 [[yii\base\Model]] 的后代，并为每个参数内置了验证规则，因此可以用于在网页表单中创建 cron 设置界面。

解析 cron 作业

[[yii2tech\crontab\CronJob]] 组合 cron 作业行，如下所示

0 0 * * * php /path/to/my/project/yii some-cron

但是，它也可以解析这样的行，填充自己的内部属性。例如

use yii2tech\crontab\CronJob;

$cronJob = new CronJob();
$cronJob->setLine('0 0 * * * php /path/to/my/project/yii some-cron');

echo $cronJob->min; // outputs: '0'
echo $cronJob->hour; // outputs: '0'
echo $cronJob->day; // outputs: '*'
echo $cronJob->month; // outputs: '*'
echo $cronJob->command; // outputs: 'php /path/to/my/project/yii some-cron'

合并 cron 作业

方法 [[yii2tech\crontab\CronTab::apply()]] 将所有指定的 cron 作业添加到 crontab，同时保持现有的 cron 作业不变。例如，如果当前的 crontab 如下所示

0 0 * * * php /path/to/my/project/yii daily-cron

运行以下代码

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->setJobs([
    [
        'min' => '0',
        'hour' => '0',
        'weekDay' => '5',
        'command' => 'php /path/to/project/yii weekly-cron',
    ],
]);
$cronTab->apply();

将产生以下 crontab

0 0 * * * php /path/to/my/project/yii daily-cron
0 0 * * 5 php /path/to/my/project/yii weekly-cron

当合并 crontab 行时，[[yii2tech\crontab\CronTab::apply()]] 避免重复，因此相同的 cron 作业永远不会被添加两次。然而，在执行此操作时，行是通过 精确 匹配来比较的，包括命令和时间模式。如果相同的命令被添加两次，但时间模式不同，则将存在两个 crontab 记录。例如，如果当前的 crontab 如下所示

0 0 * * * php /path/to/my/project/yii some-cron

运行以下代码

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->setJobs([
    [
        'min' => '15',
        'hour' => '2',
        'command' => 'php /path/to/project/yii some-cron',
    ],
]);
$cronTab->apply();

将产生以下 crontab

0 0 * * * php /path/to/my/project/yii some-cron
15 2 * * * php /path/to/my/project/yii some-cron

您可以使用 [[yii2tech\crontab\CronTab::$mergeFilter]] 来干扰合并过程，该属性允许指示在合并时应删除的现有 cron 作业。它的值可以是纯字符串 - 在这种情况下，将删除包含此字符串子串的所有行，或者是一个具有以下签名的 PHP 可调用函数：bool function (string $line) - 如果函数返回 true，则应删除该行。例如，如果当前的 crontab 如下所示

0 0 * * * php /path/to/my/project/yii some-cron

运行以下代码

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->mergeFilter = '/path/to/project/yii'; // filter all invocation of Yii console
$cronTab->setJobs([
    [
        'min' => '15',
        'hour' => '2',
        'command' => 'php /path/to/project/yii some-cron',
    ],
]);
$cronTab->apply();

将产生以下 crontab

15 2 * * * php /path/to/my/project/yii some-cron

额外的行设置

Crontab 文件可能包含作业规范之外的其他行。它可以包含注释或额外的 shell 配置。例如

# this crontab created by my application
SHELL=/bin/sh
PATH=/usr/bin:/usr/sbin

0 0 * * * php /path/to/my/project/yii some-cron

您可以将这些额外的行添加到 crontab 中，使用 [[yii2tech\crontab\CronTab::$headLines]]。例如

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->headLines = [
    '# this crontab created by my application',
    'SHELL=/bin/sh',
    'PATH=/usr/bin:/usr/sbin',
];
$cronTab->setJobs([
    [
        'min' => '0',
        'hour' => '0',
        'command' => 'php /path/to/project/yii some-cron',
    ],
]);
$cronTab->apply();

注意：在合并crontab与现有配置时，使用headLines可能会产生预期之外的结果。

用户设置

每个Linux系统用户都有自己的crontab。受此扩展影响的crontab所有权由运行PHP脚本的用户决定。对于Web应用通常是'apache'，对于控制台应用则是当前本地用户或root。因此，Web应用和控制台应用的crontab应用将分别生成针对两个不同系统用户的两个独立的cron作业列表。

您可以通过[[yii2tech\crontab\CronTab::$username]]显式设置受影响的crontab所属用户的名称。例如

use yii2tech\crontab\CronTab;

$cronTab = new CronTab();
$cronTab->username = 'www-data'; // apply crontab for 'www-data' user
$cronTab->setJobs([
    [
        'min' => '0',
        'hour' => '0',
        'command' => 'php /path/to/project/yii some-cron',
    ],
]);
$cronTab->apply();

但是，这仅在PHP脚本由特权用户（例如'root'）运行时才有效。