任務調度 · Laravel 5.4 完全開發手冊

* * * * * [TOC] ## 簡介在過去，開發者必須為每個需要調度的任務生成單獨的 Cron 項目。然而令人頭疼的是任務調度不受版本控制，并且需要 SSH 到服務器上來增加 Cron 條目。 Laravel 命令調度器允許你在 Laravel 中對命令調度進行清晰流暢的定義，并且僅需要在服務器上增加一條 Cron 項目即可。你的調度已經定義在?`app/Console/Kernel.php`?文件的?`schedule`?方法中。為了方便你開始，在該方法內包含了一個簡單的例子。你可以隨意增加調度到?`Schedule`?對象中。 ### 啟動調度器使用調度器時，你只需要把 Cron 添加到你的服務器，如果你不知道如何添加到服務器，你可以使用?[Laravel Forge](https://forge.laravel.com/)?服務來管理你的 Cron 。 ~~~ * * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1 ~~~ 該 Cron 將于每分鐘調用一次 Laravel 命令調度器，當?`schedule:run`?命令執行時， Laravel 會評估你的計劃任務并運行預定任務。 ## 定義調度你可以將所有的計劃任務定義在?`App\Console\Kernel`?類的?`schedule`?方法中。在開始之前，先讓我們來看看一個任務的調度示例。在該例子中，我們計劃了一個會在每天午夜被調用的?`閉包`。該?`閉包`?將運行數據庫查詢語句來清除某個數據表： ~~~ <?php namespace App\Console; use DB; use Illuminate\Console\Scheduling\Schedule; use Illuminate\Foundation\Console\Kernel as ConsoleKernel; class Kernel extends ConsoleKernel { /** * 應用提供的 Artisan 命令 * * @var array */ protected $commands = [ \App\Console\Commands\Inspire::class, ]; /** * 定義應用的命令調度 * * @param \Illuminate\Console\Scheduling\Schedule $schedule * @return void */ protected function schedule(Schedule $schedule) { $schedule->call(function () { DB::table('recent_users')->delete(); })->daily(); } } ~~~ 除了計劃?`閉包`?調用，你還能計劃?[Artisan 命令](https://laravel-china.org/docs/laravel/5.4/artisan)以及系統命令操作。舉個例子，你可以使用?`command`?方法傳參命令名稱或者命令類名稱來計劃一個?`Artisan`?命令： ~~~ $schedule->command('emails:send --force')->daily(); $schedule->command(EmailsCommand::class, ['--force'])->daily(); ~~~ `exec`?命令可發送命令到操作系統上： ~~~ $schedule->exec('node /home/forge/script.js')->daily(); ~~~ ### 調度頻率設置當然，你可以針對你的任務來分配多種調度計劃： | 方法 | 描述 | | --- | --- | | `->cron('* * * * * *');` | 自定義調度任務 | | `->everyMinute();` | ?每分鐘執行一次任務 | | `->everyFiveMinutes();` | 每五分鐘執行一次任務 | | `->everyTenMinutes();` | 每十分鐘執行一次任務 | | `->everyThirtyMinutes();` | 每半小時執行一次任務 | | `->hourly();` | 每小時執行一次任務 | | `->hourlyAt(17);` | 每一個小時的第 17 分鐘運行一次 | | `->daily();` | 每到午夜執行一次任務 | | `->dailyAt('13:00');` | 每天的 13:00 執行一次任務 | | `->twiceDaily(1, 13);` | 每天的 1:00 和 13:00 分別執行一次任務 | | `->weekly();` | 每周執行一次任務 | | `->monthly();` | 每月執行一次任務 | | `->monthlyOn(4, '15:00');` | 在每個月的第四天的 15:00 執行一次任務 | | `->quarterly();` | 每季度執行一次任務 | | `->yearly();` | 每年執行一次任務 | | `->timezone('America/New_York');` | 設置時區 | 這些方法可以合并其它限制條件以生成更精確的調度。例如在某周的某幾天運行調度。舉個例子，計劃一個每周周一的調度： ~~~ // 每周一的下午一點鐘運行 $schedule->call(function () { // })->weekly()->mondays()->at('13:00'); // 工作日中從早上 8 點鐘運行到下午 5 點 $schedule->command('foo') ->weekdays() ->hourly() ->timezone('America/Chicago') ->between('8:00', '17:00'); ~~~ 下方列出其它額外限制條件： | 方法 | 描述 | | --- | --- | | `->weekdays();` | 限制任務在工作日 | | `->sundays();` | 限制任務在星期日 | | `->mondays();` | 限制任務在星期一 | | `->tuesdays();` | 限制任務在星期二 | | `->wednesdays();` | 限制任務在星期三 | | `->thursdays();` | 限制任務在星期四 | | `->fridays();` | 限制任務在星期五 | | `->saturdays();` | 限制任務在星期六 | | `->between($start, $end);` | 限制任務運行在開始到結束時間范圍內 | | `->when(Closure);` | 限制任務基于一個為真的驗證 | #### 時間范圍限制 `between`?方法可以用來限制一天中某個時間范圍內： ~~~ $schedule->command('reminders:send') ->hourly() ->between('7:00', '22:00'); ~~~ 類似的，`unlessBetween`?方法可以用來排除時間段： ~~~ $schedule->command('reminders:send') ->hourly() ->unlessBetween('23:00', '4:00'); ~~~ #### 為真驗證限制條件 `when`?方法可以用來判斷是否要運行任務，主要基于一個指定的為真驗證的運行結果。如果指定的?`閉包`?返回?`true`，且沒有其它限制條件存在，那么這個任務將會被繼續運行。 ~~~ $schedule->command('emails:send')->daily()->when(function () { return true; }); ~~~ `skip`?是?`when`?的顛倒意味。`skip`?方法返回?`true`?的話，計劃就不會運行。 ~~~ $schedule->command('emails:send')->daily()->skip(function () { return true; }); ~~~ 當鏈式調用了?`when`?方法時，計劃命令只有在所有的?`when`?條件返回?`true`?時才運行。 ### 避免任務重復默認情況，即便之前相同的任務主體仍未結束，現有計劃任務依舊會被運行。為了避免這個問題，你可以使用?`withoutOverlapping`?方法： ~~~ $schedule->command('emails:send')->withoutOverlapping(); ~~~ 在這個例子中，如果沒有其它?`emails:send`?[Artisan 命令](https://laravel-china.org/docs/laravel/5.4/artisan)?在運行的話，此任務將于每分鐘被運行一次。當你有些任務運行時間過長，且無法預測出具體所需時間時，?`withoutOverlapping`?方法將會特別有幫助。 ### 維護模式當應用進入?[維護模式](https://laravel-china.org/docs/laravel/5.4/configuration#maintenance-mode)?時，默認情況下 Laravel 的調度功能將會停止運行。這是因為我們考慮到你可能在維護模式下做一些破壞性的維護工作，我們不想讓任務調度對這些工作造成干擾。然而，如果你想強制某個任務在維護模式下運行的話，你可以使用?`evenInMaintenanceMode`?方法： ~~~ $schedule->command('emails:send')->evenInMaintenanceMode(); ~~~ ## 任務輸出 Laravel 調度器為任務調度輸出提供多種便捷方法。首先，通過?`sendOutputTo`?你可以發送輸出到單個文件上以便后續檢查： ~~~ $schedule->command('emails:send') ->daily() ->sendOutputTo($filePath); ~~~ 如果想將輸出附加到指定的文件上，則可以使用?`appendOutputTo`?方法： ~~~ $schedule->command('emails:send') ->daily() ->appendOutputTo($filePath); ~~~ 通過?`emailOutputTo`?方法，你可以發送輸出到你所指定的電子郵件上。注意，你必須先通過?`sendOutputTo`?方法將其輸出到一個文件。同時，在郵件發出之前，你需要先設置 Laravel 的?[電子郵件服務](https://laravel-china.org/docs/laravel/5.4/mail): ~~~ $schedule->command('foo') ->daily() ->sendOutputTo($filePath) ->emailOutputTo('foo@example.com'); ~~~ > {note}?`emailOutputTo`，`sendOutputTo`?和?`appendOutputTo`?方法只適用于?`command`方法，不支持?`call`方法。 ## 任務鉤子通過?`before`?與?`after`?方法，你能讓特定的代碼在任務完成之前及之后運行： ~~~ $schedule->command('emails:send') ->daily() ->before(function () { // Task is about to start... }) ->after(function () { // Task is complete... }); ~~~ #### Ping 網址通過?`pingBefore`?與?`thenPing`?方法，調度器能自動的在一個任務完成之前或之后 ping 一個指定的網址。該方法在你計劃的任務進行或完成時，可用來有效的通知一個外部服務，例如?[Laravel Envoyer](https://envoyer.io/)： ~~~ $schedule->command('emails:send') ->daily() ->pingBefore($url) ->thenPing($url); ~~~ 使用?`pingBefore($url)`?或?`thenPing($url)`?功能需要 Guzzle HTTP 函數庫的支持。可在?`composer.json`?文件中加入以下代碼來安裝 Guzzle： ~~~ composer require guzzlehttp/guzzle ~~~