コンテンツへスキップ

Cron

cronシステムでは、バックグラウンドで定期的に実行するタスクを定義できます。ブロックディレクトリにcron.phpファイルを追加すると、BlockstudioがジョブをWordPress Cronに登録し、そのライフサイクルを管理します。単独でインストールされたプラグインは、無効化時にジョブをクリーンアップします。テーマや別のプラグインに組み込まれたComposerインストールでは、ホストを無効化、切り替え、または削除する前に、ホスト側でクリーンアップを行うかwp bs teardownを実行する必要があります。

これはフルスタックブロックのパターンを完成させる要素です。ブロックにUI(index.twig)、サーバーロジック(rpc.php)、永続データ(db.php)、そしてバックグラウンド処理(cron.php)を持たせられます。

仕組み

  1. ブロックディレクトリにcron.phpを作成します
  2. 名前付きジョブを含む連想配列が返されます
  3. ページが読み込まれるたびに、Blockstudioがジョブのスケジュールを確認します
  4. 未登録のスケジュールはwp_schedule_event()に登録されます
  5. WordPress Cronが定義された間隔でコールバックを実行します
  6. 単独のBlockstudioプラグインを無効化すると、すべてのBlockstudio cronイベントのスケジュールが解除されます。組み込みインストールでは、以下のクリーンアップ手順を使用します
コード
blocks/my-block/
├── block.json
├── index.twig
├── rpc.php       ← custom endpoints
├── db.php        ← data model
├── cron.php      ← background tasks
└── style.css

ジョブの定義

ジョブの連想配列を返します。各ジョブには、直接コールバック(デフォルトはdaily)またはscheduleとcallbackを含む配列を指定できます。

PHP
return [
    // Expanded format with custom schedule
    'cleanup' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // runs every hour
        },
    ],

    // Shorthand: just a callback, defaults to daily
    'heartbeat' => function () {
        update_option('my_block_last_heartbeat', time());
    },
];

PHPネイティブの定義

cron.phpは、属性付きメソッドを持つオブジェクトも返せます。既存の配列構文を維持しながら、よりPHPネイティブな記述ができます。

PHP
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
        update_option('my_block_last_heartbeat', time());
    }

    #[Cron]
    public function cleanupOldEntries(): void {
        // defaults to daily
    }
};

デフォルトでは、メソッド名は小文字のスネークケースに正規化されます。そのため、cleanupOldEntries()はcleanup_old_entriesになります。明示的にジョブ名を指定する場合はname:を使います。

スケジュール

組み込み

WordPressには次のスケジュールが標準で用意されています。

スケジュール 間隔
hourly 1時間ごと
twicedaily 12時間ごと
daily 24時間ごと
weekly 7日ごと

カスタム間隔

WordPresscron_schedulesフィルターでカスタム間隔を登録し、cron.phpで参照します。

PHP
add_filter('cron_schedules', function ($schedules) {
    $schedules['every_five_minutes'] = [
        'interval' => 300,
        'display'  => 'Every 5 Minutes',
    ];
    $schedules['every_fifteen_minutes'] = [
        'interval' => 900,
        'display'  => 'Every 15 Minutes',
    ];
    return $schedules;
});
PHP
return [
    'check_external_api' => [
        'schedule' => 'every_five_minutes',
        'callback' => function () { /* ... */ },
    ],
];

よくあるパターン

データのメンテナンス

古いレコードの削除、試用期間の終了、非アクティブなエントリーのアーカイブに使えます。

PHP
use Blockstudio\Db;

return [
    'expire_trials' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db     = Db::get('my-theme/app', 'subscribers');
            $trials = $db->list(['plan' => 'trial']);

            foreach ($trials as $trial) {
                if (strtotime($trial['created_at']) < strtotime('-14 days')) {
                    $db->update((int) $trial['id'], ['plan' => 'expired']);
                }
            }
        },
    ],
    'purge_old_logs' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'activity_log');
            $logs = $db->list();

            foreach ($logs as $log) {
                if (strtotime($log['created_at']) < strtotime('-90 days')) {
                    $db->delete((int) $log['id']);
                }
            }
        },
    ],
];

外部APIの同期

スケジュールに従って、サードパーティーサービスからデータを取得します。

PHP
return [
    'sync_products' => [
        'schedule' => 'hourly',
        'callback' => function () {
            $response = wp_remote_get('https://api.example.com/products');

            if (is_wp_error($response)) {
                return;
            }

            $products = json_decode(wp_remote_retrieve_body($response), true);
            $db       = \Blockstudio\Db::get('my-theme/shop', 'products');

            foreach ($products as $product) {
                $existing = $db->list(['external_id' => $product['id']]);

                if (empty($existing)) {
                    $db->create($product);
                } else {
                    $db->update((int) $existing[0]['id'], $product);
                }
            }
        },
    ],
];

通知とダイジェスト

定期レポートや通知メールを送信します。

PHP
use Blockstudio\Db;

return [
    'weekly_digest' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db   = Db::get('my-theme/app', 'subscribers');
            $new  = count($db->list(['status' => 'active']));
            $admin = get_option('admin_email');

            wp_mail($admin, 'Weekly Digest', "Active subscribers: $new");
        },
    ],
];

無効化

Blockstudioを独立したプラグインとしてインストールした場合、そのプラグインを無効化すると、すべてのBlockstudio cronイベントのスケジュールが自動的に解除されます。

Composerをテーマや別のプラグインに組み込んだ場合、独自の無効化フックはありません。ホストプラグインを無効化する、ホストテーマから切り替える、または組み込みコードを削除すると、ホスト側でクリーンアップしない限り、イベントのスケジュールが残ります。次の操作を行う前に、ティアダウンコマンドを実行してください:

シェル
wp bs teardown

Blockstudio cronのイベントをすべてスケジュール解除し、インストールが所有する静的なプリレンダー状態を削除します。詳しくはCLIをご覧ください。

Blockstudioがまだ読み込まれている間だけ、このコマンドを使用できます。代わりに、ホストプラグインのメインファイルからクリーンアップを登録できます:

PHP
register_deactivation_hook(__FILE__, function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

組み込み先のテーマでは、switch_themeで同じコールバックを使用できます。次のテーマのafter_switch_themeフックではなく、旧テーマが読み込まれている間に登録してください:

PHP
add_action('switch_theme', function () {
    if (class_exists(\Blockstudio\Cron::class)) {
        \Blockstudio\Cron::unschedule_all();
    }
});

Cron::unschedule_all()は、1つのブロックやホストのジョブだけでなく、すべてのBlockstudio cronイベントを削除します。これらのフックでは静的なプリレンダー状態は削除されません。インストール全体を廃止する場合はwp bs teardownを使用してください。クリーンアップしないと、定期イベントはWordPressに残り、ブロックコードを再びインストールしたときに再開する可能性があります。

フィルター

ジョブをプログラムで変更または無効化します。

PHP
add_filter('blockstudio/cron', function (array $jobs): array {
    // Disable a specific job
    unset($jobs['my-theme/app']['cleanup']);

    // Change a schedule
    if (isset($jobs['my-theme/app']['sync'])) {
        $jobs['my-theme/app']['sync']['schedule'] = 'twicedaily';
    }

    return $jobs;
});

デバッグ

WordPress Cronはシステムレベルのスケジューラーではなく、ページへのアクセスによって実行されます。アクセスの少ないサイトでは、ジョブが予定どおりに実行されないことがあります。確実なタイミングで実行するには、実際のシステムcronを設定し、wp-cron.phpにアクセスさせてください。

シェル
*/5 * * * * curl -s https://yoursite.com/wp-cron.php > /dev/null 2>&1

次に、wp-config.phpでWordPress組み込みのcronトリガーを無効にします。

PHP
define('DISABLE_WP_CRON', true);

スケジュールされたイベントを確認するには、WP-CLIを使います。

シェル
wp cron event list | grep blockstudio