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

説明

基本構文

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

引数

• $timestamp：最初に実行する時刻（UNIXタイムスタンプ）
• $recurrence：間隔（hourly / twicedaily / daily など）
• $hook：実行するフック名
• $args：フックに渡す引数
• $wp_error：失敗時に WP_Error を返すか

戻り値

登録できたら true。

使い方（サンプル）

if ( ! wp_next_scheduled( 'my_daily_event' ) ) {
	wp_schedule_event( time(), 'daily', 'my_daily_event' );
}
add_action( 'my_daily_event', 'my_daily_task' );

注意点

• 登録前に wp_next_scheduled() で重複登録を防ぎます。
• WP-Cronは、サイトへのアクセスがあったときに実行されます。アクセスが少ないサイトでは、サーバーのcronから wp-cron.php を呼ぶ設定にします。
• プラグインの無効化時に wp_clear_scheduled_hook() で解除します。

実務での使いどころ

• 毎時・毎日など、定期的な処理（集計、掃除、同期）を、登録するとき。
• プラグインの有効化時に、定期実行を、設定するとき。

よくあるミスと対処

• 毎回のリクエストで、登録している。登録済みかを、wp_next_scheduled() で確認してから、登録する。
• 登録しただけで、実行する処理を、add_action() で用意していない。
• 無効化のときに、登録を解除していない。wp_clear_scheduled_hook() で解除する。
• WP-Cronは、サイトにアクセスがあったときに、動く。正確な時刻の実行は、保証されない。

NG例

add_action( 'init', function () {
	wp_schedule_event( time(), 'daily', 'my_daily_task' ); // 毎回登録される
} );

OK例

add_action( 'my_daily_task', 'my_daily_callback' );
register_activation_hook( __FILE__, function () {
	if ( ! wp_next_scheduled( 'my_daily_task' ) ) {
		wp_schedule_event( time(), 'daily', 'my_daily_task' );
	}
} );
register_deactivation_hook( __FILE__, function () {
	wp_clear_scheduled_hook( 'my_daily_task' );
} );

使い分け早見表

関連項目

wp_next_scheduled()、wp_clear_scheduled_hook()、wp_schedule_single_event()、wp_get_schedules()

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