README

本扩展是Laravel的调度组件（https://laravel.net.cn/docs/master/scheduling#scheduling-artisan-commands）的移植

安装

推荐通过 composer 来安装此扩展。

运行以下命令

php composer.phar require hhsnake/yii2-scheduling "*"

或者在 composer.json 的 require 部分添加以下内容

"hhsnake/yii2-scheduling": "*"

描述

本项目受Laravel的调度组件启发，试图将它的简洁性带到Yii框架中。引用自Laravel文档：基于 omnilight/yii2-scheduling，并从多个仓库中提取更改以支持 symfony/process ^5.0|^6.0

In the past, developers have generated a Cron entry for each console command they wished to schedule.
However, this is a headache. Your console schedule is no longer in source control,
and you must SSH into your server to add the Cron entries. Let's make our lives easier.

安装后，你只需在 crontab 中添加一行即可

* * * * * php /path/to/yii yii schedule/run --scheduleFile=@path/to/schedule.php 1>> /dev/null 2>&1

你可以将调度放入 schedule.php 文件，或者在你扩展或应用的引导过程中添加

调度示例

此扩展支持Laravel调度组件的所有功能，除了环境和维护模式。

调度闭包

$schedule->call(function()
{
    // Do some task...

})->hourly();

调度终端命令

$schedule->exec('composer self-update')->daily();

运行应用命令

$schedule->command('migrate')->cron('* * * * *');

频繁任务

$schedule->command('foo')->everyFiveMinutes();

$schedule->command('foo')->everyTenMinutes();

$schedule->command('foo')->everyThirtyMinutes();

每日任务

$schedule->command('foo')->daily();

每日特定时间（24小时制）的任务

$schedule->command('foo')->dailyAt('15:00');

每天两次的任务

$schedule->command('foo')->twiceDaily();

每周工作日运行的任务

$schedule->command('foo')->weekdays();

每周任务

$schedule->command('foo')->weekly();

// Schedule weekly job for specific day (0-6) and time...
$schedule->command('foo')->weeklyOn(1, '8:00');

每月任务

$schedule->command('foo')->monthly();

特定日期运行的任务

$schedule->command('foo')->mondays();
$schedule->command('foo')->tuesdays();
$schedule->command('foo')->wednesdays();
$schedule->command('foo')->thursdays();
$schedule->command('foo')->fridays();
$schedule->command('foo')->saturdays();
$schedule->command('foo')->sundays();

仅当回调为真时运行任务

$schedule->command('foo')->monthly()->when(function()
{
    return true;
});

将调度任务的输出通过电子邮件发送

$schedule->command('foo')->sendOutputTo($filePath)->emailOutputTo('foo@example.com');

防止任务冲突

$schedule->command('foo')->withoutOverlapping();

默认使用 yii\mutex\FileMutex 或 'mutex' 应用组件（https://yiiframework.cn/doc-2.0/yii-mutex-mutex.html）

在单个服务器上运行任务

要使用此功能，你必须在应用组件中配置 mutex，除了 FileMutex：yii\mutex\MysqlMutex、yii\mutex\PgsqlMutex、yii\mutex\OracleMutex 或 yii\redis\Mutex。另外，所有服务器都必须与同一个中心数据库/缓存服务器通信。

以下显示Redis mutex示例

'components' => [
    'mutex' => [
        'class' => 'yii\redis\Mutex',
        'redis' => [
            'hostname' => 'localhost',
            'port' => 6379,
            'database' => 0,
        ]
    ],
],

$schedule->command('report:generate')
                ->fridays()
                ->at('17:00')
                ->onOneServer();

如何在应用中使用此扩展？

你应该在 @console/config/schedule.php 下创建以下文件（注意：你可以创建任何名称和扩展名的文件，并放在服务器的任何位置，只需简单调整下面命令中的 scheduleFile 名称即可）

<?php
/**
 * @var \hhsnake\scheduling\Schedule $schedule
 */

// Place here all of your cron jobs

// This command will execute ls command every five minutes
$schedule->exec('ls')->everyFiveMinutes();

// This command will execute migration command of your application every hour
$schedule->command('migrate')->hourly();

// This command will call callback function every day at 10:00
$schedule->call(function(\yii\console\Application $app) {
    // Some code here...
})->dailyAt('10:00');

接下来，你应该将以下命令添加到 crontab 中

* * * * * php /path/to/yii yii schedule/run --scheduleFile=@console/config/schedule.php 1>> /dev/null 2>&1

这就完成了！现在，所有你的 cron 作业都将按照你在 schedule.php 文件中配置的方式运行。

如何在自定义扩展中使用此扩展？

首先，你应该在你的 composer.json 中包含对 hhsnake\yii2-scheduling 的依赖

...
'require': {
    "hhsnake/yii2-schedule": "*"
}
...

接下来，你应该为你的扩展创建引导类，如https://yiiframework.cn/doc-2.0/guide-structure-extensions.html#bootstrapping-classes中所述

在你的引导方法中放置以下代码

public function bootstrap(Application $app)
{
    if ($app instanceof \yii\console\Application) {
        if ($app->has('schedule')) {
            /** @var hhsnake\scheduling\Schedule $schedule */
            $schedule = $app->get('schedule');
            // Place all your shedule command below
            $schedule->command('my-extension-command')->dailyAt('12:00');
        }
    }
}

在扩展的 README 中添加用户注册 schedule 组件的信息，并添加 schedule/run 命令到 crontab，如上所述

使用 schedule 组件

如果你仅在应用中使用调度（并且不希望扩展注册它们自己的 cron 作业），你不需要直接使用 schedule 组件或将其定义在应用中。但是，如果你想要给扩展注册 cron 作业的能力，你应该在应用配置中定义 schedule 组件

'schedule' => 'hhsnake\scheduling\Schedule',

使用附加功能

如果您想使用 Event 的 thenPing 方法，您应该将以下字符串添加到您的应用的 composer.json 文件中

"guzzlehttp/guzzle": "~5.0"

关于时区说明

请注意，这是一个 PHP 扩展，因此它使用 PHP 配置文件或您的 Yii 配置文件中定义的时区，所以请正确设置它们。