[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> cron.php (summary)

WordPress Cron API

File Size: 1243 lines (41 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 17 functions

  wp_schedule_single_event()
  wp_schedule_event()
  wp_reschedule_event()
  wp_unschedule_event()
  wp_clear_scheduled_hook()
  wp_unschedule_hook()
  wp_get_scheduled_event()
  wp_next_scheduled()
  spawn_cron()
  wp_cron()
  _wp_cron()
  wp_get_schedules()
  wp_get_schedule()
  wp_get_ready_cron_jobs()
  _get_cron_array()
  _set_cron_array()
  _upgrade_cron_array()

Functions
Functions that are not part of a class:

wp_schedule_single_event( $timestamp, $hook, $args = array()   X-Ref
Schedules an event to run only once.

Schedules a hook which will be triggered by WordPress at the specified time.
The action will trigger when someone visits your WordPress site if the scheduled
time has passed.

Note that scheduling an event to occur within 10 minutes of an existing event
with the same action hook will be ignored unless you pass unique `$args` values
for each scheduled event.

Use wp_next_scheduled() to prevent duplicate events.

Use wp_schedule_event() to schedule a recurring event.

return: bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
since: 2.1.0
since: 5.1.0 Return value modified to boolean indicating success or failure,
since: 5.7.0 The `$wp_error` parameter was added.
param: int    $timestamp  Unix timestamp (UTC) for when to next run the event.
param: string $hook       Action hook to execute when the event is run.
param: array  $args       Optional. Array containing arguments to pass to the
param: bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.

wp_schedule_event( $timestamp, $recurrence, $hook, $args = array()   X-Ref
Schedules a recurring event.

Schedules a hook which will be triggered by WordPress at the specified interval.
The action will trigger when someone visits your WordPress site if the scheduled
time has passed.

Valid values for the recurrence are 'hourly', 'daily', and 'twicedaily'. These can
be extended using the {@see 'cron_schedules'} filter in wp_get_schedules().

Note that scheduling an event to occur within 10 minutes of an existing event
with the same action hook will be ignored unless you pass unique `$args` values
for each scheduled event.

Use wp_next_scheduled() to prevent duplicate events.

Use wp_schedule_single_event() to schedule a non-recurring event.

return: bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
since: 2.1.0
since: 5.1.0 Return value modified to boolean indicating success or failure,
since: 5.7.0 The `$wp_error` parameter was added.
param: int    $timestamp  Unix timestamp (UTC) for when to next run the event.
param: string $recurrence How often the event should subsequently recur.
param: string $hook       Action hook to execute when the event is run.
param: array  $args       Optional. Array containing arguments to pass to the
param: bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.

wp_reschedule_event( $timestamp, $recurrence, $hook, $args = array()   X-Ref
Reschedules a recurring event.

Mainly for internal use, this takes the time stamp of a previously run
recurring event and reschedules it for its next run.

To change upcoming scheduled events, use wp_schedule_event() to
change the recurrence frequency.

return: bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure.
since: 2.1.0
since: 5.1.0 Return value modified to boolean indicating success or failure,
since: 5.7.0 The `$wp_error` parameter was added.
param: int    $timestamp  Unix timestamp (UTC) for when the event was scheduled.
param: string $recurrence How often the event should subsequently recur.
param: string $hook       Action hook to execute when the event is run.
param: array  $args       Optional. Array containing arguments to pass to the
param: bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.

wp_unschedule_event( $timestamp, $hook, $args = array()   X-Ref
Unschedule a previously scheduled event.

The $timestamp and $hook parameters are required so that the event can be
identified.

return: bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure.
since: 2.1.0
since: 5.1.0 Return value modified to boolean indicating success or failure,
since: 5.7.0 The `$wp_error` parameter was added.
param: int    $timestamp Unix timestamp (UTC) of the event.
param: string $hook      Action hook of the event.
param: array  $args      Optional. Array containing each separate argument to pass to the hook's callback function.
param: bool   $wp_error  Optional. Whether to return a WP_Error on failure. Default false.

wp_clear_scheduled_hook( $hook, $args = array()   X-Ref
Unschedules all events attached to the hook with the specified arguments.

Warning: This function may return Boolean FALSE, but may also return a non-Boolean
value which evaluates to FALSE. For information about casting to booleans see the
{@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
the `===` operator for testing the return value of this function.

return: int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
since: 2.1.0
since: 5.1.0 Return value modified to indicate success or failure,
since: 5.7.0 The `$wp_error` parameter was added.
param: string $hook     Action hook, the execution of which will be unscheduled.
param: array  $args     Optional. Array containing each separate argument to pass to the hook's callback function.
param: bool   $wp_error Optional. Whether to return a WP_Error on failure. Default false.

wp_unschedule_hook( $hook, $wp_error = false )   X-Ref
Unschedules all events attached to the hook.

Can be useful for plugins when deactivating to clean up the cron queue.

Warning: This function may return Boolean FALSE, but may also return a non-Boolean
value which evaluates to FALSE. For information about casting to booleans see the
{@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
the `===` operator for testing the return value of this function.

return: int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
since: 4.9.0
since: 5.1.0 Return value added to indicate success or failure.
since: 5.7.0 The `$wp_error` parameter was added.
param: string $hook     Action hook, the execution of which will be unscheduled.
param: bool   $wp_error Optional. Whether to return a WP_Error on failure. Default false.

wp_get_scheduled_event( $hook, $args = array()   X-Ref
Retrieve a scheduled event.

Retrieve the full event object for a given event, if no timestamp is specified the next
scheduled event is returned.

return: object|false The event object. False if the event does not exist.
since: 5.1.0
param: string   $hook      Action hook of the event.
param: array    $args      Optional. Array containing each separate argument to pass to the hook's callback function.
param: int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event

wp_next_scheduled( $hook, $args = array()   X-Ref
Retrieve the next timestamp for an event.

return: int|false The Unix timestamp of the next time the event will occur. False if the event doesn't exist.
since: 2.1.0
param: string $hook Action hook of the event.
param: array  $args Optional. Array containing each separate argument to pass to the hook's callback function.

spawn_cron( $gmt_time = 0 )   X-Ref
Sends a request to run cron through HTTP request that doesn't halt page loading.

return: bool True if spawned, false if no events spawned.
since: 2.1.0
since: 5.1.0 Return values added.
param: int $gmt_time Optional. Unix timestamp (UTC). Default 0 (current time is used).

wp_cron()   X-Ref
Register _wp_cron() to run on the {@see 'wp_loaded'} action.

If the {@see 'wp_loaded'} action has already fired, this function calls
_wp_cron() directly.

Warning: This function may return Boolean FALSE, but may also return a non-Boolean
value which evaluates to FALSE. For information about casting to booleans see the
{@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
the `===` operator for testing the return value of this function.

return: bool|int|void On success an integer indicating number of events spawned (0 indicates no
since: 2.1.0
since: 5.1.0 Return value added to indicate success or failure.
since: 5.7.0 Functionality moved to _wp_cron() to which this becomes a wrapper.

_wp_cron()   X-Ref
Run scheduled callbacks or spawn cron for all scheduled events.

Warning: This function may return Boolean FALSE, but may also return a non-Boolean
value which evaluates to FALSE. For information about casting to booleans see the
{@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
the `===` operator for testing the return value of this function.

return: int|false On success an integer indicating number of events spawned (0 indicates no
since: 5.7.0

wp_get_schedules()   X-Ref
Retrieve supported event recurrence schedules.

The default supported recurrences are 'hourly', 'twicedaily', 'daily', and 'weekly'.
A plugin may add more by hooking into the {@see 'cron_schedules'} filter.
The filter accepts an array of arrays. The outer array has a key that is the name
of the schedule, for example 'monthly'. 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 should run.
So for 'hourly' the time is `HOUR_IN_SECONDS` (60 * 60 or 3600). For 'monthly',
the value would be `MONTH_IN_SECONDS` (30 * 24 * 60 * 60 or 2592000).

The 'display' is the description. For the 'monthly' key, the 'display'
would be `__( 'Once Monthly' )`.

For your plugin, you will be passed an array. You can easily add your
schedule by doing the following.

// Filter parameter variable name is 'array'.
$array['monthly'] = array(
'interval' => MONTH_IN_SECONDS,
'display'  => __( 'Once Monthly' )
);

return: array[]
since: 2.1.0
since: 5.4.0 The 'weekly' schedule was added.

wp_get_schedule( $hook, $args = array()   X-Ref
Retrieve the recurrence schedule for an event.

return: string|false Schedule name on success, false if no schedule.
since: 2.1.0
since: 5.1.0 {@see 'get_schedule'} filter added.
param: string $hook Action hook to identify the event.
param: array  $args Optional. Arguments passed to the event's callback function.

wp_get_ready_cron_jobs()   X-Ref
Retrieve cron jobs ready to be run.

Returns the results of _get_cron_array() limited to events ready to be run,
ie, with a timestamp in the past.

return: array[] Array of cron job arrays ready to be run.
since: 5.1.0

_get_cron_array()   X-Ref
Retrieve cron info array option.

return: array[]|false Array of cron info arrays on success, false on failure.
since: 2.1.0

_set_cron_array( $cron, $wp_error = false )   X-Ref
Updates the cron option with the new cron array.

return: bool|WP_Error True if cron array updated. False or WP_Error on failure.
since: 2.1.0
since: 5.1.0 Return value modified to outcome of update_option().
since: 5.7.0 The `$wp_error` parameter was added.
param: array[] $cron     Array of cron info arrays from _get_cron_array().
param: bool    $wp_error Optional. Whether to return a WP_Error on failure. Default false.

_upgrade_cron_array( $cron )   X-Ref
Upgrade a Cron info array.

This function upgrades the Cron info array to version 2.

return: array An upgraded Cron info array.
since: 2.1.0
param: array $cron Cron info array from _get_cron_array().



Generated: Tue Dec 24 01:00:02 2024 Cross-referenced by PHPXref 0.7.1