云策 WordPress 开发者社区

钩子文档

cron_schedules

查看官方原文 ↗
💡 云策文档标注

概述

cron_schedules 是一个 WordPress 过滤器，用于添加自定义的 cron 时间间隔到非默认的 cron 计划中。它允许开发者扩展 WordPress 内置的 cron 调度选项，以便在插件或主题中定义自己的重复执行频率。

关键要点

  • cron_schedules 过滤器接受一个数组参数 $schedules，用于添加或修改非默认的 cron 计划。
  • 每个自定义计划需要包含 'interval'（以秒为单位的间隔时间）和 'display'（显示名称）两个键。
  • 添加自定义计划时，必须将新计划合并到传入的 $schedules 数组中，以避免覆盖其他插件添加的计划。
  • WordPress 默认提供 'hourly'、'twicedaily' 和 'daily' 等内置计划，此过滤器用于扩展这些选项。

代码示例

function my_add_weekly( $schedules ) {
    $schedules['weekly'] = array(
        'interval' => 604800,
        'display' => __('Once Weekly')
    );
    return $schedules;
}
add_filter( 'cron_schedules', 'my_add_weekly' );

注意事项

  • 在添加自定义计划时，建议在主要动作（如 init 或 wp_loaded）中注册 cron_schedules 过滤器，以确保在使用 wp_schedule_event 之前计划已存在。
  • 避免直接返回仅包含自定义计划的数组，应使用数组合并操作来保留其他插件添加的计划。
📄 原文内容

Filters the non-default cron schedules.

Parameters

$new_schedulesarray
An array of non-default cron schedules keyed by the schedule name. Default empty array.

  • ...$0 array
    Cron schedule information.

    • interval int
      The schedule interval in seconds.
    • display string
      The schedule display name.

More Information

The filter accepts an array of non-default cron schedules in arrays (an array of arrays). The outer array has a key that is the name of the schedule (for example, ‘weekly’). The value is an array with two keys, one is ‘interval’ and the other is ‘display’.

The ‘interval’ is a number in seconds of when the cron job shall run. So, for a hourly schedule, the ‘interval’ value would be 3600 or 60*60. For for a weekly schedule, the ‘interval’ value would be 60*60*24*7 or 604800.

The ‘display’ is the description of the non-default cron schedules. For the ‘weekly’ key, the ‘display’ may be __(‘Once Weekly’).

Why is this important?

When scheduling your own actions to run using the WordPress Cron service, you have to specify which interval WordPress should use. WordPress has its own, limited, default set of intervals, or “schedules”, including ‘hourly’, ‘twicedaily’, and ‘daily’. This filter allows you to add your own intervals to the default set.

For your plugin, you will be passed an array, you can easily add a weekly schedule by doing something like:

function my_add_weekly( $schedules ) {
// add a 'weekly' schedule to the existing set
$schedules['weekly'] = array(
'interval' => 604800,
'display' => __('Once Weekly')
);
return $schedules;
}
add_filter( 'cron_schedules', 'my_add_weekly' );

Adding multiple intervals works similarly:

function my_add_intervals($schedules) {
// add a 'weekly' interval
$schedules['weekly'] = array(
'interval' => 604800,
'display' => __('Once Weekly')
);
$schedules['monthly'] = array(
'interval' => 2635200,
'display' => __('Once a month')
);
return $schedules;
}
add_filter( 'cron_schedules', 'my_add_intervals');

Be sure to add your schedule to the passed array, as shown in the example. If you simply return only your own schedule array then you will potentially delete schedules created by other plugins.

Source

return array_merge( apply_filters( 'cron_schedules', array() ), $schedules );

View all references View on Trac View on GitHub

Used by Description
wp_get_schedules()wp-includes/cron.php

Retrieves supported event recurrence schedules.

Changelog

Version Description
2.1.0 Introduced.

User Contributed Notes

  1. Skip to note 5 content


    Dominik Schilling


    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Add a custom cron schedule for every 5 minutes:

    /**
 * Adds a custom cron schedule for every 5 minutes.
 *
 * @param array $schedules An array of non-default cron schedules.
 * @return array Filtered array of non-default cron schedules.
 */
function devhub_custom_cron_schedule( $schedules ) {
	$schedules[ 'every-5-minutes' ] = array( 'interval' => 5 * MINUTE_IN_SECONDS, 'display' => __( 'Every 5 minutes', 'devhub' ) );
	return $schedules;
}
add_filter( 'cron_schedules', 'devhub_custom_cron_schedule' );

  2. Skip to note 6 content


    dhl17


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    custom cron schedule for every 10 & 15 Seconds

    function custom_cron_job_recurrence( $schedules ) 
{
	if(!isset($schedules['10sec']))
	{
		$schedules['10sec'] = array(
			'display' => __( 'Every 10 Seconds', 'twentyfifteen' ),
			'interval' => 10,
		);
	}
	
	if(!isset($schedules['15sec']))
	{
		$schedules['15sec'] = array(
		'display' => __( 'Every 15 Seconds', 'twentyfifteen' ),
		'interval' => 15,
		);
	}
	
	return $schedules;
}
add_filter( ‘cron_schedules’, ‘custom_cron_job_recurrence’ );

  3. Skip to note 7 content


    Ihtisham Zahoor


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Add a user-defined interval value:
    Using functinal approach

         add_filter( 'cron_schedules', 'wpdocs_add_cron_interval' );
     function wpdocs_add_cron_interval( $schedules ) {
          $options = get_option( 'wpdocs_custom_interval' );
          $interval = ( ! empty( $options ) ? absint( $options ) * HOUR_IN_SECONDS : DAY_IN_SECONDS );

          $schedules['wpdocs_interval'] = array(
               'interval' => $interval,
               'display' => esc_html__( 'Custom Interval' )
          );

          return $schedules;
    }

    Using class based approach

         add_filter( 'cron_schedules', array( $this, 'add_cron_interval' ) );

    /**
     * Adds custom time intervals for the cron.
     */
    private function add_cron_interval( $schedules ) {
          $options = get_option( 'wpdocs_custom_interval' );
          $interval = ( ! empty( $options ) ? absint( $options ) * HOUR_IN_SECONDS : DAY_IN_SECONDS );

          $schedules['wpdocs_interval'] = array(
               'interval' => $interval,
               'display' => esc_html__( 'Custom Interval' )
          );

          return $schedules;
    }

  4. Skip to note 8 content


    BogdanFix


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    As a handy tip to save your time, I’d suggest to always hook to cron_schedules filter inside a major action that runs on each page load. Like init or wp_loaded. And also hook to that filter before your code using the custom schedule.

    For example:

    // function that registers new custom schedule

function bf_add_custom_schedule( $schedules )
{
    $schedules[ 'every_five_minutes' ] = array(
        'interval' => 300,
        'display'  => 'Every 5 minutes',
    );

    return $schedules;
}

// function that schedules custom event

function bf_schedule_custom_event()
{
    // the actual hook to register new custom schedule

    add_filter( 'cron_schedules', 'bf_add_custom_schedule' );

    // schedule custom event

    if( !wp_next_scheduled( 'bf_your_custom_event' ) )
    {
        wp_schedule_event( time(), 'every_five_minutes', 'bf_your_custom_event' );
    }
}
add_action( 'init', 'bf_schedule_custom_event' );

// fire custom event

function bf_do_something_on_schedule()
{
    // your code...
}
add_action( 'bf_your_custom_event', 'bf_do_something_on_schedule' );

    This approach guarantees that your custom schedule is always registered before it is used in wp_schedule_event function. And saves you from nasty "invalid_schedule":"Event schedule does not exist." error.

    Cheers 🙂

You must log in before being able to contribute a note or feedback.