任務調度

• 簡介
• 定義調度
  • Artisan 命令調度
  • 隊列任務調度
  • Shell 命令調度
  • 調度頻率設置
  • 時區(qū)
  • 避免任務 重復
  • 任務只運行在一臺服務器上
  • 后臺任務
  • 維護模式
• 任務輸出
• 任務鉤子

簡介

過去，你可能需要在服務器上為每一個調度任務去創(chuàng)建 Cron 入口。但是這種方式很快就會變得不友好，因為這些任務調度不在源代碼中，并且你每次都需要通過 SSH 鏈接登錄到服務器中才能增加 Cron 入口。

Laravel 命令行調度器允許你在 Laravel 中對命令調度進行清晰流暢的定義。且使用這個任務調度器時，你只需要在你的服務器上創(chuàng)建單個 Cron 入口接口。你的任務調度在 app/Console/Kernel.php 的 schedule 方法中進行定義。為了幫助你更好的入門，這個方法中有個簡單的例子。

啟動調度器

當使用這個調度器時，你只需要把下面的 Cron 入口添加到你的服務器中即可。如果你不知道怎么在服務器中添加 Cron 入口，可以考慮使用一些服務來管理 Cron 入口，比如 Laravel Forge：

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

這個 Cron 為每分鐘執(zhí)行一次 Laravel 的命令行調度器。當 schedule:run 命令被執(zhí)行的時候，Laravel 會根據你的調度執(zhí)行預定的程序。

定義調度

你可以在 App\Console\Kernel 類的 schedule 方法中定義所有的調度任務。在開始之前，讓我們來看一個例子。在這個例子中，我們計劃每天午夜調用一個閉包。在閉包中，我們執(zhí)行一個數據庫查詢來清空一張表：

<?php
    namespace App\Console;
    use Illuminate\Support\Facades\DB;
    use Illuminate\Console\Scheduling\Schedule;
    use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
    class Kernel extends ConsoleKernel{    
    /**
     * 應用里的自定義 Artisan 命令
     *
     * @var array
     */   
     protected $commands = [    
         //   
       ];   
    /**
     * 定義計劃任務
     *
     * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
     * @return void
     */  
    protected function schedule(Schedule $schedule) 
       {     
          $schedule->call(function () {       
          DB::table('recent_users')->delete();      
        })->daily();  
      }
   }

除了使用閉包來定義任務調度外，你也可以用 invokable objects。

$schedule->call(new DeleteRecentUsers)->daily();

Artisan 命令調度

除了使用調用閉包這種方式來調度外，你還可以調用  Artisan 命令 和操作系統(tǒng)命令。比如，你可以給 command 方法傳遞命令名稱或者類來調度一個 Artisan 命令。

$schedule->command('emails:send --force')->daily();
$schedule->command(EmailsCommand::class, ['--force'])->daily();

隊列任務調度

job 方法可以用來調度 隊列任務。此方法提供了一種快捷的方式來調度任務，而無需使用 call 方法創(chuàng)建閉包來調度任務。

$schedule->job(new Heartbeat)->everyFiveMinutes();
// 分發(fā)任務到「heartbeats」隊列...
$schedule->job(new Heartbeat, 'heartbeats')->everyFiveMinutes();

Shell 命令調度

exec 方法可用于向操作系統(tǒng)發(fā)送命令：

$schedule->exec('node /home/forge/script.js')->daily();

調度頻率設置

當然了，你可以給你的任務分配多種調度計劃：

結合其他一些特定條件，我們可以生成在一周中特定時間運行的任務。舉個例子，在每周一執(zhí)行命令：

// 每周一 13:00 執(zhí)行...
$schedule->call(function () { 
   //
   })->weekly()->mondays()->at('13:00');
 // 工作日（周一至周五） 8點 至 17 點每小時執(zhí)行一次...
$schedule->command('foo')        
  ->weekdays()          
  ->hourly()          
  ->timezone('America/Chicago')          
  ->between('8:00', '17:00');

額外的限制條件列表如下：

時間范圍限制

使用 between 來限制任務在一天中的某個時間段來執(zhí)行：

$schedule->command('reminders:send')     
               ->hourly()                    
               ->between('7:00', '22:00');

或者使用 unlessBetween 方法來為任務排除一個時間段：

$schedule->command('reminders:send')              
      ->hourly()                    
      ->unlessBetween('23:00', '4:00');

閉包測試限制

使用 when 方法來根據測試結果來執(zhí)行任務。也就是說，如果給定的閉包返回結果為 true，只要沒有其他約束條件阻止任務運行，任務就會一直執(zhí)行下去：

$schedule->command('emails:send')->daily()->when(function () { 
   return true;
 });

skip 方法可以看做是 when 方法的逆過程。如果 skip 方法返回 true，任務就不會執(zhí)行：

$schedule->command('emails:send')->daily()->skip(function () {
    return true;
 });

使用鏈式調用 when 方法時，只有所有的 when 都返回 true 時，任務才會執(zhí)行。

環(huán)境約束

environments 方法可用于僅在給定環(huán)境中執(zhí)行任務：

$schedule->command('emails:send')         
   ->daily()            
   ->environments(['staging', 'production']);

時區(qū)

使用 timezone 方法，你可以指定任務在給定的時區(qū)內執(zhí)行：

$schedule->command('report:generate')      
   ->timezone('America/New_York')        
   ->at('02:00')

如果要為所有計劃任務分配相同的時區(qū)，則可能希望在 app/Console/Kernel.php 文件中定義 scheduleTimezone 方法。 此方法應返回應分配給所有計劃任務的默認時區(qū)：

/**
 * 獲取默認情況下應為預定事件使用的時區(qū)。
 *
 * @return \DateTimeZone|string|null
 */
 protected function scheduleTimezone(){  
   return 'America/Chicago';
 }

{note} 請記住，有些時區(qū)會使用夏令時。當夏時制時間發(fā)生更改時，你的任務可能會執(zhí)行兩次，甚至根本不會執(zhí)行。所以我們建議盡可能避免使用時區(qū)來安排計劃任務。

避免任務重復

默認情況下，即使之前的任務還在執(zhí)行，調度內任務也會執(zhí)行。你可以使用 withoutOverlapping 方法來避免這種情況：

$schedule->command('emails:send')->withoutOverlapping();

在這個例子中，如果 emails:send Artisan 命令 沒有正在運行，它將會每分鐘執(zhí)行一次。如果你的任務執(zhí)行時間不確定，且你又不能準確預估出任務的執(zhí)行時間，那么  withoutOverlapping 方法會顯得特別有用。

如果有需要，你可以指定「without overlapping」鎖指定的時間范圍。默認情況下，鎖將在 24 小時后過期。

$schedule->command('emails:send')->withoutOverlapping(10);

任務只運行在一臺服務器上

{note} 要使用這個特性，你的應用默認緩存驅動必須是 memcached 或者 redis。除此之外，所有的服務器必須使用同一個中央緩存服務器通信。

如果你的應用在多個服務器上運行，你可能需要限制你的調度任務只在單個服務器上運行。假設你有一個調度任務：每周五晚生成一份新報告。如果這個任務調度器在三個服務器上運行，那么這個任務會在三臺服務器上運行且生成三份報告。這樣不好！

為了說明任務應該在單個服務器上運行，在定義調度任務時使用 onOneServer 方法。第一個獲取到任務的服務器會生成一個原子鎖，用來防止其他服務器在同一時刻執(zhí)行相同任務。

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

后臺任務

默認情況下，同時調度的多個命令將按順序執(zhí)行。如果你有長時間運行的命令，這可能會導致后續(xù)命令的啟動時間比預期的要晚。因此，你想在后臺同時運行命令，可以使用 runInBackground 方法：

$schedule->command('analytics:report')      
   ->daily()         
   ->runInBackground();

維護模式

Laravel 的隊列任務在 維護模式 下不會運行。因為我們不想你的調度任務干擾到你服務器上可能還未完成的項目。不過，如果你確實是想在維護模式下強制調度任務執(zhí)行，你可以使用 evenInMaintenanceMode 方法：

$schedule->command('emails:send')->evenInMaintenanceMode();

任務輸出

Laravel 調度器提供了一些方便的方法來處理調度任務輸出。首先，你可以使用 sendOutputTo 方法來輸出到文件以便于后續(xù)檢查：

$schedule->command('emails:send')    
     ->daily()         
     ->sendOutputTo($filePath);

如果希望將輸出 附加 到給定文件，可以使用 appendOutputTo 方法

$schedule->command('emails:send')     
    ->daily()         
    ->appendOutputTo($filePath);

使用 emailOutputTo 方法，你可以將輸出發(fā)送到指定郵箱。在使用郵件發(fā)送之前，你需要配置 Laravel 的 郵件服務：

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

{note} emailOutputTo，sendOutputTo 和 appendOutputTo 方法是  command 和 exec 獨有的。

任務鉤子

使用 before 和 after 方法，你可以在調度任務執(zhí)行前或者執(zhí)行后來執(zhí)行特定代碼：

$schedule->command('emails:send')   
      ->daily()         
      ->before(function () {         
          // Task is about to start...      
            })      
      ->after(function () {       
           // Task is complete...      
         });

Ping 網址

使用 pingBefore 和 thenPing 方法，你可以在任務執(zhí)行前或者執(zhí)行后來 ping 指定的 URL。這個方法在通知外部服務（比如 Laravel Envoyer）時將會特別有用：

$schedule->command('emails:send')      
   ->daily()         
   ->pingBefore($url)         
   ->thenPing($url);

只有在給定條件為 true 時，才能使用 pingBeforeIf 和 thenPingIf 方法 ping 指定的 URL：

$schedule->command('emails:send')      
   ->daily()         
   ->pingBeforeIf($condition, $url)         
   ->thenPingIf($condition, $url);

所有 ping 方法都需要 Guzzle HTTP 庫。你可以使用 Composer 來添加 Guzzle 到你的項目中：

composer require guzzlehttp/guzzle