ワードプレスのwp_schedule_single_event関数の使用方法・解説

概要

wp_schedule_single_event 関数は、一度だけ実行するアクションをスケジュールに登録するための関数です。主に、特定の時間にジョブを実行したい場合に利用されます。この関数は、定期的なタスクや一回限りの処理をスケジュールする際に良く使用されます。以下は、この関数がよく使われるシチュエーションの例です。

1. バッチ処理の実行
2. データベースのクリーニング
3. ジョブの依存関係処理
4. メール通知の送信
5. 定期的な統計情報の収集
6. アクションのデバッグログ作成
7. 外部APIとの同期処理
8. ユーザーアカウントの定期的なチェック

構文

wp_schedule_single_event( int $timestamp, string $hook, array $args = array() )

パラメータ

• $timestamp: イベントが発生するタイムスタンプ（UNIX時間）
• $hook: イベントが発火する際に呼び出されるアクションフックの名前
• $args: フックに渡す引数の配列（オプション）

戻り値

• 成功した場合、スケジュールされたイベントのIDを返し、失敗した場合は false を返します。

関連する関数

• wp_clear_scheduled_hook
• wp_next_scheduled
• wp_unschedule_event

使用可能なワードプレスのバージョン

wp_schedule_single_event 関数は WordPress 2.1.0 以降で使用可能です。

コアファイルのパス

wp-includes/cron.php

この関数のアクションでの使用可能性

アクション	使用例
mu_plugin_loaded
registered_post_type
plugins_loaded	〇
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init	〇
register_sidebar
wp_loaded	〇
send_headers
parse_query
pre_get_posts
wp	〇
template_redirect
get_header
wp_head

サンプルコード

1. 単純なアクションスケジューリング

   function my_custom_event() {
       error_log('My custom event triggered!');
   }
   $timestamp = time() + 3600; // 1時間後
   wp_schedule_single_event($timestamp, 'my_custom_event');
   

   説明：1時間後に my_custom_event を実行し、エラーログにメッセージを記録します。

2. 引数付きのアクション設定

   function my_custom_event_with_args($arg1, $arg2) {
       error_log("Event called with args: $arg1, $arg2");
   }
   $timestamp = time() + 7200; // 2時間後
   wp_schedule_single_event($timestamp, 'my_custom_event_with_args', array('arg1_value', 'arg2_value'));
   

   説明：2時間後に引数を持ってイベントをトリガーし、引数値をエラーログに記録します。

3. イベントのキャンセル

   $timestamp = time() + 1800; // 30分後
   wp_schedule_single_event($timestamp, 'my_cancelable_event');
   $event_hook = 'my_cancelable_event';
   wp_clear_scheduled_hook($event_hook);
   

   説明：30分後に実行される予定のイベントをキャンセルします。

4. 既にスケジュールされたイベントの確認

   $event_hook = 'my_custom_event';
   $next_scheduled = wp_next_scheduled($event_hook);
   if ($next_scheduled) {
       error_log("Event is scheduled for: " . date('Y-m-d H:i:s', $next_scheduled));
   }
   

   説明：既にスケジュールされたイベントの次の実行時間をエラーログに記録します。

5. イベントの再スケジュール

   $event_hook = 'my_custom_event';
   $next_scheduled = wp_next_scheduled($event_hook);
   if ($next_scheduled) {
       wp_unschedule_event($next_scheduled, $event_hook);
   }
   wp_schedule_single_event(time() + 3600, $event_hook);
   

   説明：既存のスケジュールをキャンセルし、1時間後に再スケジュールします。

この内容は、WordPressの wp_schedule_single_event 関数についての簡潔で実用的なガイドを提供するために作成されました。