△スケジューラー

Grav スケジューラーは Grav1.6 で追加された新機能で、定期的にジョブを実行させることができます。根本的な処理はサーバの cron スケジューラーに依存しますが、cron サービスに一度でもエントリを追加すれば、すべてのジョブや特定のスケジュールを Grav から設定することが可能です。

スケジューラーを利用してタスクを処理する主な利点の 1 つは、ユーザーの操作なしで、フロントエンドから独立して実行できることです。定期的なキャッシュクリア、バックアップ、同期、検索インデックス作成などのタスクは、すべてスケジュールジョブの有力な利用方法です。

インストール

The first step in getting the scheduler setup and ready for tasks, is to add the bin/grav scheduler command to the cron service. The simplest approach is to utilize the CLI command itself to output the appropriate command to run for installation:

$ bin/grav scheduler -i

Install Scheduler
=================

 [ERROR] You still need to set up Grav's Scheduler in your crontab

 ! [NOTE] To install, run the following command from your terminal:

 (crontab -l; echo "* * * * * cd /Users/andym/grav;/usr/local/bin/php bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

私の Mac だと、必要なコマンドはすべて表示されるので、表示されたコマンドをすべてコピーしてターミナルに貼り付け、リターンキーを押すだけです。

(crontab -l; echo "* * * * * cd /Users/andym/grav;/usr/local/bin/php bin/grav scheduler 1>> /dev/null 2>&1") | crontab -

応答は得られませんが、エラーも出ないはずです。その後、bin/grav scheduler -i コマンドを再実行することで、正常に動作していることが確認できます。

bin/grav scheduler -i

Install Scheduler
=================

 [OK] All Ready! You have already set up Grav's Scheduler in your crontab

You can also get the needed command from the admin plugin by simply navigating to Tools → Scheduler.

スケジューリングの基本

ジョブをスケジュールする場合、柔軟なフォーマットで実行頻度をコントロールできます。

* * * * * *
| | | | | |
| | | | | +-- Year              (range: 1900-3000)
| | | | +---- Day of the Week   (range: 1-7, 1 standing for Monday)
| | | +------ Month of the Year (range: 1-12)
| | +-------- Day of the Month  (range: 1-31)
| +---------- Hour              (range: 0-23)
+------------ Minute            (range: 0-59)

例:

0 * * * * 1 時間に 1 回実行 (毎時 0 分に実行)
0 0 * * * 1 日に 1 回実行 (毎日 0 時 0分に実行)
0 0 1 * * 1 月に 1 回実行 (毎月 1 日 0 時 0分に実行)
0 0 1 1 * 1 年に 1 回実行 (毎年 1 月 1 日 0 時 0分に実行)

高度なオプション:

*/5 * * * * 5分毎に実行

設定ファイル

bin/grav scheduler -j コマンドを実行すると、スケジューラーに登録されている利用可能なジョブを確認することができます。

bin/grav scheduler -j

Scheduler Jobs Listing
======================

┌─────────────────────┬────────────────────────────────────┬───────────┬─────────┬──────────────────┬─────────┐
│ Job ID              │ Command                            │ Run At    │ Status  │ Last Run         │ State   │
├─────────────────────┼────────────────────────────────────┼───────────┼─────────┼──────────────────┼─────────┤
│ cache-purge         │ Grav\Common\Cache::purgeJob        │ * * * * * │ Success │ 2019-02-21 11:23 │ Enabled │
│ cache-clear         │ Grav\Common\Cache::clearJob        │ * * * * * │ Success │ 2019-02-21 11:23 │ Enabled │
│ default-site-backup │ Grav\Common\Backup\Backups::backup │ 0 3 * * * │ Ready   │ Never            │ Enabled │
│ pages-backup        │ Grav\Common\Backup\Backups::backup │ * 3 * * * │ Success │ 2018-09-20 09:55 │ Enabled │
│ ls-job              │ ls                                 │ * * * * * │ Success │ 2019-02-21 11:23 │ Enabled │
└─────────────────────┴────────────────────────────────────┴───────────┴─────────┴──────────────────┴─────────┘

 ! [NOTE] For error details run "bin/grav scheduler -d"

Grav スケジューラは、user/config/scheduler.yaml ファイルでコントロールされます。ジョブを実行するためには、設定を enabled にしておく必要があります。

以下のように設定され、実行を停止するには disabled に設定するだけです。

status:
  ls-job: enabled
  cache-purge: enabled
  cache-clear: enabled
  default-site-backup: enabled
  pages-backup: enabled

エラーの詳細や、次に実行されるジョブを確認するには、/bin/grav scheduler -d コマンドを使用します。

bin/grav scheduler -d

Job Details
===========

┌─────────────────────┬──────────────────┬──────────────────┬────────┐
│ Job ID              │ Last Run         │ Next Run         │ Errors │
├─────────────────────┼──────────────────┼──────────────────┼────────┤
│ cache-purge         │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
│ cache-clear         │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
│ default-site-backup │ Never            │ 2019-02-22 03:00 │ None   │
│ pages-backup        │ 2018-09-20 09:55 │ 2019-02-22 03:00 │ None   │
│ ls-job              │ 2019-02-21 11:29 │ 2019-02-21 11:31 │ None   │
└─────────────────────┴──────────────────┴──────────────────┴────────┘

手動でジョブを実行

The CLI command provides an simple way to manually run any jobs. In fact this is what the scheduler is doing when it runs periodically.

bin/grav scheduler

This will silently run the jobs, but you can also see details of what run using:

bin/grav scheduler -v

Grav System Jobs

The Grav core provides a few jobs out-of-the-box. These include some useful maintenance type tasks:

• cache-purge - This task is useful if you use Grav's file caching because it clears out old files that have expired. This is a great task to schedule as otherwise it would require a user to manually clear the old caches. If you don't keep up on this, and your file space is limited, you could run out of space and crash the server.

• cache-clear - The cache clear is the job that works the same way as the bin/grav clear command that you would manually run. You can configure if you want to use a standard cache clearing, or the all variant that deletes all the files and folders in the cache/ folder for a more thorough cache clearing.

• default-site-backup - The default backup job available via the new Grav Backup configuration. You can create custom backup configurations, and these will also be available to run as a scheduled job.

Custom Jobs

The Grav Scheduler can be manually configured with any number of custom jobs. These can be setup in the same scheduler.yaml configuration file referenced above. For example, the ls-job referenced above would be configured:

custom_jobs:
  ls-job:
    command: ls
    args: '-lah'
    at: '* * * * *'
    output: logs/cron-ls.out
    output_mode: overwrite
    email: user@email.com

The command should be any local script that can be run from the command line/terminal. Only the command and the at attributes are required.

Plugin-provided Jobs

One of the most powerful feature of the Grav Scheduler, is the ability for 3rd party plugins to provide their own jobs. A great example of this is provided by the TNTSearch plugin. TNTSearch is a full-featured text search engine that requires content to be indexed before it can be searched. This indexing job can be performed in a variety of ways, but the Grav Scheduler allows you to reindex your content periodically rather than having to do so manually.

The first step is for your plugin to subscribe to the onSchedulerInitialized() event. And then create a method in your plugin file that can add a custom job when called:

public function onSchedulerInitialized(Event $e): void
{
    $config = $this->config();

    if (!empty($config['scheduled_index']['enabled'])) {
        $scheduler = $e['scheduler'];
        $at = $config['scheduled_index']['at'] ?? '* * * * *';
        $logs = $config['scheduled_index']['logs'] ?? '';
        $job = $scheduler->addFunction('Grav\Plugin\TNTSearchPlugin::indexJob', [], 'tntsearch-index');
        $job->at($at);
        $job->output($logs);
        $job->backlink('/plugins/tntsearch');
    }
}

Here, you can see how some relevant scheduler configuration is obtained from the TNTSearch plugin's configuration settings, and then a new Job is created with a static function called indexJob().