README

Laravel 的任务调度

Cron 可以轻松地在 Laravel 中执行 cron 任务。如果您想从互联网或只是从本地计算机运行任务，Cron 可以帮您。有关 Cron 如何简化任务调度的更多信息，请参阅 raison d'être。

主页: https://liebig.github.io/cron/
Github: https://github.com/liebig/cron/
API: http://liebig.github.io/cron/docs/api/classes/Liebig.Cron.Cron.html

Raison d’être
安装
配置
示例
API
常见问题解答
更新日志

Raison d’être

简单性

目标是创建一种简单的方法来使用 Laravel 定义 cron 任务。使用 Cron 创建 cron 任务很简单，因为这个工具提供了大量您可以使用的事件来管理所有任务。要创建一个任务，您只需要一个任务名称、一个 cron 表达式以及一个将在时间到来时被调用的函数。当然，只有当您调用它时，PHP 才会运行，所以您需要一些额外的启动 Cron 的东西。

可访问性

Cron 启动调用可以从您的 Laravel 所在的同一台机器上执行（例如，使用 crontab）或从互联网上的任何地方（例如，使用 Web cron 服务）- 它只是一个命令执行或路由调用。

集中化

Cron 管理在您的应用程序的单一位置集中。您在 PHP 中定义所有任务，无需使用其他工具。禁用或删除 Cron 任务仅需要调用一个 PHP 函数。

平台独立性

Laravel 是构建小型和大型 Web 应用程序的好方法。但并非每个应用程序平台都运行在允许 unix shell 访问的服务器上。对于这些应用程序，Cron 提供了使用外部 Web cron 服务启动 Cron 的可能性。如果您有 shell 访问权限 - 那太好了，您可以使用 Cron 的命令来管理作业。

监控

如果您的任务出现错误，Cron 会通知您。除了记录到 Monolog、Laravel 日志记录设施和数据库之外，您还可以添加事件监听器以获取有关错误任务或成功执行的任务的信息。执行后，您将收到有关 Cron 运行的详细报告。利用 PHP 和事件的力量，如果您遇到任何问题，您可以发送邮件、通知或其他任何东西。Cron 就像您的祖母一样健谈。

我的个人舒适区

最后，Cron 是我管理作业调度的个人方式。我是一个Web应用开发者，而不是一个基础设施人员。我喜欢用PHP而不是shell来处理事情。我希望将我的应用部署到另一台服务器，而不用担心我是否有权限访问crontab或其他Linux工具。我非常喜欢Laravel的事件功能，但不喜欢Laravel的命令。Cron管理应该是简单而强大的。最后，我喜欢在应用程序的一个地方处理所有事情，而不使用shell或为每个任务编写一个PHP文件。Cron试图无烦恼地管理cron作业。

安装

Laravel 5

将 "liebig/cron": "dev-master" 添加到您的 /path/to/laravel/composer.json 文件中的 "require": 部分（有关Composer的更多信息，请参阅http://getcomposer.org/）
从您的 /path/to/laravel/ 目录中运行 composer update liebig/cron --no-dev 命令
如果您使用的是Laravel 5.4或更早版本，请将 'Liebig\Cron\Laravel5ServiceProvider' 添加到 /path/to/laravel/config/app.php 文件中的 'providers' 数组中
运行命令 php artisan migrate --path=vendor/liebig/cron/src/migrations 来迁移数据库
使用命令 php artisan vendor:publish 发布配置文件 - 现在您可以在 /path/to/laravel/config/liebigCron.php 找到Cron配置文件，该文件在任何更新中都不会被覆盖
现在您可以在任何地方免费使用 Cron

Laravel 4

将 "liebig/cron": "dev-master" 添加到您的 /path/to/laravel/composer.json 文件中的 "require": 部分（有关Composer的更多信息，请参阅http://getcomposer.org/）
从您的 /path/to/laravel/ 目录中运行 composer update liebig/cron --no-dev 命令
将 'Liebig\Cron\CronServiceProvider' 添加到 /path/to/laravel/app/config/app.php 文件中的 'providers' 数组中
运行命令 php artisan migrate --package="liebig/cron" 来迁移数据库
使用命令 php artisan config:publish liebig/cron 发布配置文件 - 现在您可以在 /path/to/laravel/app/config/packages/liebig/cron 找到Cron配置文件，该文件在任何更新中都不会被覆盖
现在您可以在任何地方免费使用 Cron

配置

Cron设计为开箱即用，无需配置。为了启用此功能，设置了一些默认值。要更改Cron的默认设置，有两种可能性。

设置方法

您可以使用Cron的设置方法（例如 setDatabaseLogging、setRunInterval）来更改Cron的行为。这些更改是临时的，并且每次都必须调用设置方法。

配置文件

行为值将从配置文件中加载。您可以通过编辑Laravel 5中的 /path/to/laravel/app/config/liebigCron.php 文件和在Laravel 4中的 /path/to/laravel/app/config/packages/liebig/cron/config.php 文件来轻松更改这些值。这是一种更永久的方法。如果您只想在具有条件的情况下更改一次设置，我们建议使用设置方法。

注意：通过方法设置的所有值将覆盖从配置文件加载的值。

示例

Cron

如果您使用Cron的集成路由或命令，您只需要监听 cron.collectJobs 事件。在Laravel 5中，最佳位置是在 /path/to/laravel5/app/Providers/AppServiceProvider.php 文件的 boot 方法中，在Laravel 4中是在 /path/to/laravel/app/start/global.php 文件中。

Laravel 5 - AppServiceProvider.php

<?php namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider {

    //...

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot() {
        // Please note the different namespace
        // and please add a \ in front of your classes in the global namespace
        \Event::listen('cron.collectJobs', function() {

            \Cron::add('example1', '* * * * *', function() {
                // Do some crazy things unsuccessfully every minute
                return 'No';
            });

            \Cron::add('example2', '*/2 * * * *', function() {
                // Do some crazy things successfully every two minute
                return null;
            });

            \Cron::add('disabled job', '0 * * * *', function() {
                // Do some crazy things successfully every hour
            }, false);
        });
    }
}

Laravel 4 - global.php

Event::listen('cron.collectJobs', function() {
    Cron::add('example1', '* * * * *', function() {
                    // Do some crazy things unsuccessfully every minute
                    return 'No';
                });

    Cron::add('example2', '*/2 * * * *', function() {
        // Do some crazy things successfully every two minute
        return null;
    });

    Cron::add('disabled job', '0 * * * *', function() {
        // Do some crazy things successfully every hour
    }, false);
});

在匿名函数内部，您可以使用所有的Laravel和Cron函数。在下一步中，您必须配置将启动Cron的路由或命令。

使用Cron的集成路由

如果您无法访问服务器的shell，您可以使用在线cron作业服务（Google知道一些好的提供商）。此提供商将在定义的间隔内运行Cron的路由。Cron路由必须受保护，因为如果除服务提供商外还有其他人调用它，我们的作业将被执行得太频繁。因此，我们需要一个安全密钥，除了路由路径外还需要设置此密钥。此密钥可以通过调用 php artisan cron:keygen 命令来生成，并且必须在Cron配置文件中设置在键 cronKey 下。

    // Cron application key for securing the integrated Cron run route - if the value is empty, the route is disabled
    'cronKey' => '1PBgabAXdoLTy3JDyi0xRpTR2qNrkkQy'

现在您需要在您的在线cronjob服务提供商处配置地址和运行间隔。集成Cron路由的地址始终是 http://yourdomain.com/cron.php?key=securitykey。对于上面的示例，这个地址可以是 http://exampledomain.com/cron.php?key=1PBgabAXdoLTy3JDyi0xRpTR2qNrkkQy，运行间隔必须每分钟运行一次（由于名为“example1”的任务）。现在，任务已添加，路由密钥已生成，服务提供商已配置。

使用Cron的集成命令

如果您的托管提供商授予您shell访问权限，或者您可以使用控制面板软件（例如cPanel或Plesk）管理cron任务，那么运行Cron的最佳方式是使用集成的 artisan cron:run 命令。对于上面的示例，crontab或控制面板软件命令可以是 * * * * * /usr/bin/php /var/www/laravel/artisan cron:run。

注意：如果您想使用Cron的时间检查，这将测试两次Cron运行方法调用之间的时间是否正确，请配置密钥 runInterval。在我们的示例中，我们每分钟调用一次路由，因此值应该是 1。

API

添加 cron 任务

通过使用静态的 add 函数，添加到Cron的cron任务非常简单。作为参数需要cron任务的名称、cron 表达式 和一个匿名函数。布尔 isEnabled 是可选的，可以启用或禁用此cron任务执行（默认为启用）。

public static function add($name, $expression, $function, $isEnabled = true) {

需要名称来识别cron任务，如果出现错误，以及用于记录。

表达式是一个字符串，包含五个或可选六个子表达式，描述了计划的详细信息。语法基于Linux cron守护进程定义。

    *    *    *    *    *    *
    -    -    -    -    -    -
    |    |    |    |    |    |
    |    |    |    |    |    + year [optional]
    |    |    |    |    +----- day of week (0 - 7) (Sunday=0 or 7)
    |    |    |    +---------- month (1 - 12)
    |    |    +--------------- day of month (1 - 31)
    |    +-------------------- hour (0 - 23)
    +------------------------- min (0 - 59)

如果表达式详细信息与当前时间戳匹配，则将调用给定的匿名函数。在这种情况下，该函数应该返回null以表示成功，如果执行此任务时出现错误，则返回任何其他内容。默认情况下，错误情况将被记录到数据库和Monolog记录器对象（如果启用了记录器）。

isEnabled 布尔参数使得在不完全删除的情况下可以停用任务执行。稍后，可以通过将方法中的布尔值设置为true来非常容易地启用任务执行。此参数是可选的，默认值为启用。

示例

\Cron::add('example1', '* * * * *', function() {
                    // Do some crazy things successfully every minute
                    return null;
                });
\Cron::add('example2', '*/2 * * * *', function() {
                    // Oh no, this job has errors and runs every two minutes
                    return false;
                }, true);

移除 cron 任务

要删除运行时的设置cron任务，请使用 remove 方法，并将cron任务名称作为字符串参数。

public static function remove($name) {

示例

\Cron::add('example1', '* * * * *', function() {
                    // Do some crazy things successfully every minute
                    return null;
                });
\Cron::remove('example1');

启用或禁用cron任务

添加启用或禁用的cron任务（add方法的调用中的$isEnabled布尔参数）后，您可以通过名称禁用或启用cron任务。为此，请使用 setEnableJob 或 setDisableJob 函数。

public static function setEnableJob($jobname, $enable = true) {

public static function setDisableJob($jobname) {

示例

\Cron::add('example1', '* * * * *', function() {
                    // Do some crazy things successfully every minute
                    return null;
                });
\Cron::setDisableJob('example1');
// No jobs will be called
$report = \Cron::run();
\Cron::setEnableJob('example1');
// One job will be called
$report = \Cron::run();

获取器

要接收任务的启用状态布尔值，请使用静态方法 isJobEnabled($jobname)。

运行 cron 任务

运行cron任务就像添加它们一样简单。只需调用静态 run 方法，并等待检查每个添加的cron任务表达式。一旦表达式的到来时间，相应的cron任务将被调用。这就是Cron的魔力。默认情况下，Cron认为您每分钟调用此方法一次（* * * * *），并且默认情况下，报告（及其cron任务的错误）将被记录到数据库。您可以使用 setRunInterval 函数更改此间隔。

public static function run() {

示例

$report = \Cron::run();

注意：在添加任务、设置间隔、停用数据库记录以及其他函数调用之后，必须调用 run 方法。

设置运行间隔

运行间隔是两次cron任务路由调用之间的时间。一些cron服务提供商仅支持每15分钟或甚至30分钟的调用。在这种情况下，您必须将此值设置为15或30。此值仅用于确定当前运行调用是否及时。如果您已禁用一般数据库记录，则不必担心此。

public static function setRunInterval($minutes) {

注意：如果路由调用间隔不是每分钟，则必须调整您的cron任务表达式以适应此间隔。

示例

// Set the run intervall to 15 minutes
\Cron::setRunInterval(15);
// Or set the run intervall to 30 minutes
\Cron::setRunInterval(30);

获取器

要获取当前运行间隔，请使用静态方法 getRunInterval()。

启用或禁用Laravel日志记录

Laravel日志功能在Monolog之上提供了一层。默认情况下，Laravel配置为为您的应用程序创建每日日志文件，这些文件存储在 app/storage/logs 中。Cron默认会使用Laravel日志功能。您可以通过在配置文件中将 laravelLogging 的值设置为false或在运行时调用 setLaravelLogging 函数来禁用此功能。

public static function setLaravelLogging($bool) {

注意：您可以为Cron添加自定义Monolog日志记录器并启用Laravel日志。在这种情况下，所有消息都将记录到Laravel和您的自定义Monolog日志记录器对象中。

示例

// Laravel logging is enabled by default
\Cron::run();
// Disable Laravel logging
\Cron::setLaravelLogging(false);
// Laravel logging is disabled
\Cron::run();

获取器

要获取启用或禁用的布尔值，请使用静态方法 isLaravelLogging()。

设置 Monolog 日志记录器

如果您想将自定义Monolog日志记录器对象添加到Cron中，请使用静态方法 setLogger。

public static function setLogger(\Monolog\Logger $logger = null) {

注意：如果要删除日志记录器，只需不带参数调用 setLogger 方法。

示例

\Cron::setLogger(new \Monolog\Logger('cronLogger'));
// And remove the logger again
\Cron::setLogger();

获取器

要获取设置的日志记录器对象，请使用静态方法 getLogger()。如果没有设置日志记录器对象，则返回null。

禁用数据库日志

默认情况下，数据库日志记录已启用，每次cron运行后，都会将管理对象和工作对象保存到数据库中。我们强烈建议保持数据库日志记录激活状态，因为只有使用此选项，Cron才能检查当前运行是否准时。在某些情况下，您可以使用 setDatabaseLogging 方法禁用数据库日志记录。

public static function setDatabaseLogging($bool) {

示例

\Cron::setDatabaseLogging(false);

获取器

要接收数据库日志记录变量的当前布尔值，请使用静态函数 isDatabaseLogging()。

只记录数据库中的错误任务

默认情况下，Cron会将所有工作记录到数据库中。有时您可能只想使用静态函数 setLogOnlyErrorJobsToDatabase 将错误工作（不返回null的工作）记录到数据库中。

public static function setLogOnlyErrorJobsToDatabase($bool) {

示例

// Log only error jobs to database
\Cron::setLogOnlyErrorJobsToDatabase(true);

获取器

要接收错误工作日志记录的当前布尔值，请使用静态函数 isLogOnlyErrorJobsToDatabase()。

删除旧数据库条目

Cron可以为您删除旧数据库条目。在每次运行方法调用期间，Cron会检查数据库中是否有旧的管理和工作条目，如果达到参考值，则删除这些条目。您可以通过调用 setDeleteDatabaseEntriesAfter 函数来更改参考值。默认值为240小时（10天）。要将旧条目的删除设置为禁用，请将参考值设置为0。

public static function setDeleteDatabaseEntriesAfter($hours) {

示例

// Set the delete database entries reference value to 10 days (24 hours x 10 days)
\Cron::setDeleteDatabaseEntriesAfter(240);

获取器

要获取当前参考值，请使用静态函数 getDeleteDatabaseEntriesAfter()。

防止重叠

Cron可以防止重叠。如果启用此功能，则一次只能运行一个Cron实例。例如，如果某些工作需要5分钟来执行，但Cron路由每分钟被调用一次，则在不防止重叠的情况下，两个Cron实例将同时执行工作。如果在同一时间运行同一工作两次，可能会出现副作用。Cron可以通过使用简单的锁定技术来避免此类重叠。

public static function setEnablePreventOverlapping() {

示例

// The configuration could be set via config file with the key 'preventOverlapping' or via method
\Cron::setEnablePreventOverlapping();
// Now the Cron run will only run once at the same time

\Cron::setDisablePreventOverlapping();
// Prevent overlapping is disabled and many Cron run executions are possible at the same time

获取器

要获取当前布尔值，请使用静态函数 isPreventOverlapping()。

注意：要使用重叠功能，Cron需要具有对Laravel存储目录的写入权限。在某些Windows机器上，无法删除锁定文件。如果在日志中看到删除错误消息，请禁用此功能。

事件

Cron支持Laravel事件，并提供有关运行状态和工作状态的许多信息。您可以使用此功能来响应错误。Cron支持以下事件。

cron.collectJobs - 在调用运行方法之前触发，用于添加工作和配置Cron。此事件仅在您使用Cron的集成路由或命令时触发。
cron.beforeRun - 在调用运行方法之前触发，通知Cron即将开始。参数： $runDate。
cron.jobError - 在工作执行后触发，如果此工作返回了错误（返回值不等于null）。参数： $name，$return，$runtime，$rundate。
cron.jobSuccess - 在作业执行完成后触发，且此作业没有返回错误（返回值等于null）。参数：$name、$runtime、$rundate。
cron.afterRun - 在Cron运行完成后触发。参数：$rundate、$inTime、$runtime、$errors - 错误作业数量、$crons - 所有已执行作业的数组（包含键 $name、$return、$runtime）、$lastRun - 包含最后一次Cron运行信息的数组（包含键 $rundate 和 $runtime）。如果Cron是第一次调用或数据库日志被禁用，则$lastRun参数是一个空数组，此时$inTime参数等于-1。
cron.locked - 如果找到锁文件，则触发。参数：$lockfile。

要订阅事件，请使用Laravel的Event功能。最佳位置是/path/to/laravel/app/start/global.php文件。

\Event::listen('cron.jobError', function($name, $return, $runtime, $rundate){
    \Log::error('Job with the name ' . $name . ' returned an error.');
});

命令

Cron提供了以下Laravel命令。

cron:run - 触发cron.collectJobs事件并启动Cron。
cron:list - 触发cron.collectJobs事件并列出所有注册的Cron作业。
cron:keygen - 生成32个字符的安全令牌。

重置 Cron

要重置cron管理，调用静态reset方法。它将所有变量重置为默认值。

public static function reset() {

示例

\Cron::add('example1', '* * * * *', function() {
                    // Do some crazy things successfully every minute
                    return null;
                });
\Cron::setLogger(new \Monolog\Logger('cronLogger'));
\Cron::reset();
// \Cron::remove('example1') === false
// \Cron::getLogger() === NULL

常见问题解答

我真的需要crontab或在线cronjob服务吗？

是的，你需要。例如，与Java应用服务器相比，PHP只有在执行时才会运行。如果crontab或在线cronjob服务提供商调用PHP并启动应用程序，Cron可以执行作业并将工作启动。如果PHP没有启动，应用程序将休眠，什么也不会发生。

调用路由或命令的最佳间隔是什么？

最佳间隔取决于你的作业。如果一个作业每分钟执行一次，而另一个每五分钟执行一次，则路由或命令必须每分钟调用一次。一般来说，你需要找到你作业的最大公约数。请不要忘记，如果路由或命令不是每分钟调用（默认值），并且你想使用Cron的in time检查，请更改runInterval配置值。

Cron运行不正常，并返回`runtime`和`inTime`的值为`-1`。

默认情况下，Cron防止重叠。这意味着同一时间只能有一个Cron实例运行。如果另一个实例被调用，Cron将不会运行，并将返回的runtime和inTime参数的值设置为-1。在某些Windows机器上，删除锁文件失败，你必须禁用此功能。请参阅防止重叠部分。

更新日志

2019/05/21 - 1.3

修复错误

2017/09/13 - 1.2

增加对Laravel 5.5的支持
增加对Laravel 5.4的支持

2016/11/15 - 1.1.2

增加对Symfonys 3 Table类在Laravel 5.2中的支持

2016/06/07 - 1.1.1

修复与Laravel 5.2相关的错误

2015/03/02 - 1.1.0

增加对Laravel 5的支持
向'cron_job'表添加索引
删除Eloquent类别名
将'cron_job'表的'cron_manager_id'列更改为无符号
修复'setDisableInTimeCheck'方法

2015/02/02 - 1.0.2

添加cron.locked事件
将Cron标记为稳定
将$function参数类型更改为"callable"，以修复IDE类型提示

2014/10/13 - 1.0.1

在run方法中添加try-catch-finally块，以确保始终删除锁文件
向cron.afterRun事件添加$lastRun参数
添加Laravel 5 composer支持
移除返回字符串截断500个字符后
修复cron.afterRun事件

2014/06/12 - 1.0.0

添加带有安全令牌的Laravel路由
添加生成安全令牌的Artisan命令
添加用于通过例如crontab轻松运行Cron的Artisan命令
添加用于列出通过事件添加的所有作业的Artisan命令
添加事件
添加重叠保护
将配置键'logOnlyErrorJobsToDatabase'的默认值更改为false
修复PHP文档标记
生成API
改进此README文件
小错误修复

2014/02/11 - v0.9.5

错误修复版本
修复PSR0自动加载的bug
修复时间bug - 如果一个任务执行时间超过一分钟，后续的任务将不会被处理

2013/11/12 - v0.9.4

添加Laravel日志功能 - 默认情况下，Cron现在将日志记录到Laravel中
添加异常 - Cron现在将抛出InvalidArgumentExceptions和UnexpectedValueExceptions
小错误修复

2013/11/01 - v0.9.3

添加Cron门面 - 您现在可以使用Cron而不是\Liebig\Cron\Cron
添加门面测试用例

许可证

MIT许可证 (MIT)

本许可证授予任何获得此软件及其相关文档副本（以下简称“软件”）的人免费使用权，不受任何限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许提供软件的人进行上述行为，前提是遵守以下条件

图标版权 (c) Timothy Miller (http://www.iconfinder.com/icondetails/171279/48/alarm_bell_clock_time_icon)，根据Creative Commons（署名-相同方式共享3.0未本地化）许可 - 感谢您拥有这个了不起的图标

vientoquesurcalosmares / liebig-cron-updated

维护者

详细信息