README

一个灵活的、框架无关的cron作业调度器，使用可读表达式。

• 许可证
• 作者
• 需求
• 安装
• 用法

许可证

此项目为开源，可在 MIT 许可证 下使用。

作者

• Bayfront Media 主页
• Bayfront Media GitHub

需求

• PHP ^8.0

安装

composer require bayfrontmedia/cron-scheduler

用法

开始使用Cron Scheduler

首先，创建一个用于安排作业的文件，例如 cron.php。文件可以命名为你喜欢的任何名字。

然后，向你的crontab中添加一个新的条目，每分钟运行该文件

* * * * * path/to/php/bin path/to/cron.php > /dev/null 2>&1

或者，为了将作业的输出保存到日志文件中，指定一个文件路径，例如

* * * * * path/to/php/bin path/to/cron.php >> /path/to/cron-`date +\%Y-\%m-\%d`.log 2>&1

现在，你的服务器将每分钟检查该文件，Cron Scheduler将根据它们的安排仅运行到期的作业。

创建实例

注意：所有由Cron Scheduler抛出的异常都扩展了 Bayfront\CronScheduler\CronException，因此你可以根据需要选择宽泛或严格地捕获异常。

构造函数接受两个字符串参数： $lock_file_path 和 $output_file。

为了防止作业重叠，Cron Scheduler创建临时“锁”文件。这些文件在每次作业开始时创建，完成时删除。如果存在锁文件，即使作业应该运行，也会跳过作业。如果 $lock_file_path === NULL，则不会创建锁文件，所有作业都可以重叠。

当指定了 $output_file 时，运行作业的任何输出都将保存到该文件，除非为该作业指定了特定的自定义文件（见 saveOutput）。这与在crontab中指定日志文件的效果相同（见上面）。

构造函数可能会抛出 Bayfront\CronScheduler\FilesystemException 异常。

示例 cron.php

use Bayfront\CronScheduler\Cron;
use Bayfront\CronScheduler\FilesystemException;

try {

    $cron = new Cron('path/to/temp/dir', 'path/to/output/file.log');

} catch (FilesystemException $e) {
    die($e->getMessage());
}

公共方法

• getJobs
• getPreviousDate
• getNextDate
• run
• raw
• php
• call
• always
• when
• saveOutput

作业计划

• at
• everyMinutes
• hourly
• everyHours
• daily
• weekly
• monthly
• everyMonths
• annually
• sunday
• monday
• tuesday
• wednesday
• thursday
• friday
• saturday
• january
• february
• march
• april
• may
• june
• july
• august
• september
• october
• november
• december

getJobs

描述

返回计划中的cron作业。

参数

• (None)

返回

• (array)

示例

print_r($cron->getJobs());

getPreviousDate

描述

获取给定作业上次计划运行的日期。

参数

• $label (string)
• $date_format = 'Y-m-d H:i:s' (string): 返回的日期格式

查看： https://php.ac.cn/manual/en/datetime.format.php

返回

• (string)

抛出

• Bayfront\CronScheduler\LabelExistsException
• Bayfront\CronScheduler\SyntaxException

示例

try {
    echo $cron->getPreviousDate('job-name');
    
} catch (CronException $e) {
    die($e->getMessage());
}

getNextDate

描述

获取给定作业下次计划运行的日期。

参数

• $label (string)
• $date_format = 'Y-m-d H:i:s' (string): 返回的日期格式

查看： https://php.ac.cn/manual/en/datetime.format.php

返回

• (string)

抛出

• Bayfront\CronScheduler\LabelExistsException
• Bayfront\CronScheduler\SyntaxException

示例

try {
    echo $cron->getNextDate('job-name');
    
} catch (CronException $e) {
    die($e->getMessage());
}

run

描述

运行所有到期的排队作业。

参数

• $current_time = 'now' (DateTimeInterface): 通过传递一个带有给定时间的 DateTime 实例来覆盖当前时间。

返回

• (数组): 完成任务相关的数据数组

抛出

• Bayfront\CronScheduler\FilesystemException

返回的数组将包含以下键

• jobs: 运行任务的数组，每个任务都有自己的 start、end、elapsed 和 output 键。
• start: 任务开始的时间戳。
• end: 任务结束的时间戳。
• elapsed: 完成任务所用的总秒数。
• count: 运行的任务数量。

抛出

• Bayfront\CronScheduler\FilesystemException

示例

try {

    $result = $cron->run();

} catch (FilesystemException $e) {
    die($e->getMessage());
}

另一个例子，这次是覆盖（或，“欺骗”）当前时间

$current_time = new DateTime('2020-09-08 10:55:00');

try {

    $result = $cron->run($current_time)

} catch (FilesystemException $e) {
    die($e->getMessage());
}

raw

描述

将一个原始命令添加为一个任务。

默认情况下，任务将每分钟运行一次。

参数

• $label (字符串): 为此任务分配的唯一标签
• $command (字符串)

返回

• (self)

抛出

• Bayfront\CronScheduler\LabelExistsException

示例

try {

    $cron->raw('job-name', 'php -v');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

php

描述

将一个PHP文件添加为一个任务。

默认情况下，任务将每分钟运行一次。

参数

• $label (字符串): 为此任务分配的唯一标签
• $file (字符串): 文件的完整路径

返回

• (self)

抛出

• Bayfront\CronScheduler\LabelExistsException

示例

try {

    $cron->php('job-name', 'path/to/php/file.php');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

call

描述

将一个可调用的函数添加为一个任务。

注意：函数应该 返回 输出，而不是 echo 输出。

默认情况下，任务将每分钟运行一次。

参数

• $label (字符串): 为此任务分配的唯一标签
• $callable (可调用)
• $params = [] (数组): 传递给可调用的参数

返回

• (self)

抛出

• Bayfront\CronScheduler\LabelExistsException

示例

try {

    $cron->call('job-name', function($name) {
        return "Hello, " . $name . "\n\n";
    }, [
        'name' => 'John'
    ]);

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

always

描述

始终运行任务，即使之前的执行仍在进行。

这可以防止为该任务创建锁文件。

参数

• (None)

返回

• (self)

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->always();

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

when

描述

为任务添加一个运行条件，即使它已到期。

只有当 $callable 的返回值为 TRUE 时，任务才会运行。

参数

• $callable (可调用)
• $params = [] (数组)

返回

• (self)

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->when(function($return) {
        
        return $return;
       
    }, [
        'return' => true
    ]);

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

saveOutput

描述

将任务的输出保存到指定的文件。

如果构造函数中指定了 $output_file，则这将覆盖它。

参数

• $output_file (字符串)

返回

• (self)

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->saveOutput('path/to/save/output.log');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

at

描述

使用有效的cron表达式安排任务运行。

参数

• $at (字符串)

返回

• (self)

示例

try {

    // 10:00pm Monday-Friday

    $cron->php('job-name', 'path/to/php/file.php')->at('0 22 * * 1-5');

} catch (LabelExistsException $e) {
    die($e->getMessage());
}

everyMinutes

描述

安排任务每x分钟运行一次。

参数

• $minutes = 1 (整数)

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->everyMinutes(5);

} catch (CronException $e) {
    die($e->getMessage());
}

hourly

描述

安排任务在每个小时的指定分钟运行。

参数

• $minute = 0 (整数)

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->hourly(15);

} catch (CronException $e) {
    die($e->getMessage());
}

everyHours

描述

安排任务在每个小时的指定时间运行。

参数

• $hours = 1 (整数)

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->everyHours(2);

} catch (CronException $e) {
    die($e->getMessage());
}

daily

描述

安排任务在每天的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    $cron->php('job-name', 'path/to/php/file.php')->daily('16:30');

} catch (CronException $e) {
    die($e->getMessage());
}

weekly

描述

安排任务在每个星期的指定星期和指定时间运行。

参数

• $weekday = 0 (整数): 0-6代表星期日-星期六
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 4:30pm every Friday

    $cron->php('job-name', 'path/to/php/file.php')->weekly(5, '16:30');

} catch (CronException $e) {
    die($e->getMessage());
}

monthly

描述

安排任务在每个月的指定日和指定时间运行。

参数

• $day = 1 (整数): 1-31代表月份中的日期
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight on the 15th day of every month

    $cron->php('job-name', 'path/to/php/file.php')->monthly(15);

} catch (CronException $e) {
    die($e->getMessage());
}

everyMonths

描述

安排任务在每个x个月的第一天指定时间运行。

参数

• $months = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 9am on the first day every of every third month

    $cron->php('job-name', 'path/to/php/file.php')->everyMonths(3, '9:00');

} catch (CronException $e) {
    die($e->getMessage());
}

annually

描述

安排任务在每个年份的指定月、日和指定时间运行。

参数

• $month = 1 (整数)
• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every June 20th

    $cron->php('job-name', 'path/to/php/file.php')->annually(6, 20);

} catch (CronException $e) {
    die($e->getMessage());
}

sunday

描述

安排任务在每个星期天的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Sunday

    $cron->php('job-name', 'path/to/php/file.php')->sunday();

} catch (CronException $e) {
    die($e->getMessage());
}

monday

描述

安排任务在每个星期一的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Monday

    $cron->php('job-name', 'path/to/php/file.php')->monday();

} catch (CronException $e) {
    die($e->getMessage());
}

tuesday

描述

安排任务在每个星期二的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Tuesday

    $cron->php('job-name', 'path/to/php/file.php')->tuesday();

} catch (CronException $e) {
    die($e->getMessage());
}

wednesday

描述

安排任务在每个星期三的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Wednesday

    $cron->php('job-name', 'path/to/php/file.php')->wednesday();

} catch (CronException $e) {
    die($e->getMessage());
}

thursday

描述

安排任务在每个星期四的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Thursday

    $cron->php('job-name', 'path/to/php/file.php')->thursday();

} catch (CronException $e) {
    die($e->getMessage());
}

friday

描述

安排任务在每个星期五的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Friday

    $cron->php('job-name', 'path/to/php/file.php')->friday();

} catch (CronException $e) {
    die($e->getMessage());
}

saturday

描述

安排任务在每个星期六的指定时间运行。

参数

• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // Midnight every Saturday

    $cron->php('job-name', 'path/to/php/file.php')->saturday();

} catch (CronException $e) {
    die($e->getMessage());
}

january

描述

安排任务在每个一月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every January 10th

    $cron->php('job-name', 'path/to/php/file.php')->january(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

february

描述

安排任务在每个二月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every February 10th

    $cron->php('job-name', 'path/to/php/file.php')->february(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

march

描述

安排任务在每个三月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every March 10th

    $cron->php('job-name', 'path/to/php/file.php')->march(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

april

描述

安排任务在每个四月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every April 10th

    $cron->php('job-name', 'path/to/php/file.php')->april(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

may

描述

安排任务在每个五月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every May 10th

    $cron->php('job-name', 'path/to/php/file.php')->may(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

june

描述

安排任务在每个六月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every June 10th

    $cron->php('job-name', 'path/to/php/file.php')->june(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

july

描述

安排任务在每个七月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every July 10th

    $cron->php('job-name', 'path/to/php/file.php')->july(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

august

描述

安排任务在每个八月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every August 10th

    $cron->php('job-name', 'path/to/php/file.php')->august(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

september

描述

安排任务在每个九月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every September 10th

    $cron->php('job-name', 'path/to/php/file.php')->sepember(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

october

描述

安排任务在每个十月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every October 10th

    $cron->php('job-name', 'path/to/php/file.php')->october(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

november

描述

安排任务在每个十一月的指定日和指定时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every November 10th

    $cron->php('job-name', 'path/to/php/file.php')->november(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}

december

描述

将作业计划在每年的指定日期和时间运行。

参数

• $day = 1 (整数)
• $time = '00:00' (字符串): 24小时格式的时间，不带前导零

返回

• (self)

抛出

• Bayfront\CronScheduler\SyntaxException

示例

try {

    // 11:30pm every December 10th

    $cron->php('job-name', 'path/to/php/file.php')->december(10, '23:30');

} catch (CronException $e) {
    die($e->getMessage());
}