wp_schedule_single_event() の使い方｜説明・引数・注意点

説明

基本構文

wp_schedule_single_event( int $timestamp, string $hook, array $args = array(), bool $wp_error = false ): bool|WP_Error

引数

• $timestamp：実行する時刻
• $hook：実行するフック名
• $args：フックに渡す引数
• $wp_error：失敗時に WP_Error を返すか

戻り値

登録できたら true。

使い方（サンプル）

wp_schedule_single_event( time() + 3600, 'my_one_time_event' );

注意点

• 10分以内に同じフック・引数のイベントがあると、登録されません。

実務での使いどころ

• 一定時間後に、1回だけ実行する処理を、登録するとき（メール送信の遅延、後片付けなど）。
• フォーム送信後に、重い処理を、あとで実行するとき。

よくあるミスと対処

• 登録しただけで、実行する処理を、add_action() で用意していない。
• 同じフックと引数の、イベントが、短時間（10分以内）にすでにあると、登録されない。
• WP-Cronは、サイトにアクセスがあったときに、動く。正確な時刻の実行は、保証されない。

NG例

wp_schedule_single_event( time() + 60, 'my_task' ); // 実行する処理が、用意されていない

OK例

add_action( 'my_task', 'my_task_callback' );
wp_schedule_single_event( time() + 60, 'my_task', array( $post_id ) );

使い分け早見表

関連項目

wp_schedule_event()、wp_next_scheduled()

公式リファレンス：wp_schedule_single_event() | Function | WordPress Developer Resources