WordPress.org
Get WordPress

Make WordPress Core

Changeset 61639


Ignore:
Timestamp:
02/13/2026 08:25:57 PM (3 weeks ago)
Author:
westonruter
Message:

Cron API: Improve documentation on matching event arguments to avoid duplicate entries.

This harmonizes and clarifies the documentation for the $args parameter in wp_schedule_event(), wp_schedule_single_event(), wp_reschedule_event(), wp_unschedule_event(), wp_clear_scheduled_hook(), and wp_next_scheduled(), to emphasize the requirement for matching arguments and the risks of mismatching them.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10890

Props manishxdp, westonruter, ovidiul, digamberpradhan.
Fixes #43801.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/cron.php

    r61387 r61639  
    3434 *                           is passed to the callback as an individual parameter.
    3535 *                           The array keys are ignored. Default empty array.
     36 *
     37 *                           These arguments are used to uniquely identify the
     38 *                           scheduled event and must match those used when the
     39 *                           event was originally scheduled. If the arguments
     40 *                           do not match exactly, WordPress will treat the
     41 *                           event as different, which can lead to duplicate
     42 *                           cron events being scheduled unintentionally,
     43 *                           excessive growth of the 'cron' option, and
     44 *                           database performance issues.
    3645 * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
    3746 * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
    … …  
    229238 *                           is passed to the callback as an individual parameter.
    230239 *                           The array keys are ignored. Default empty array.
     240 *
     241 *                           These arguments are used to uniquely identify the
     242 *                           scheduled event and must match those used when the
     243 *                           event was originally scheduled. If the arguments
     244 *                           do not match exactly, WordPress will treat the
     245 *                           event as different, which can lead to duplicate
     246 *                           cron events being scheduled unintentionally,
     247 *                           excessive growth of the 'cron' option, and
     248 *                           database performance issues.
    231249 * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
    232250 * @return bool|WP_Error True if event successfully scheduled. False or WP_Error on failure.
    … …  
    335353 *                           is passed to the callback as an individual parameter.
    336354 *                           The array keys are ignored. Default empty array.
     355 *
     356 *                           These arguments are used to uniquely identify the
     357 *                           scheduled event and must match those used when the
     358 *                           event was originally scheduled. If the arguments
     359 *                           do not match exactly, WordPress will treat the
     360 *                           event as different, which can lead to duplicate
     361 *                           cron events being scheduled unintentionally,
     362 *                           excessive growth of the 'cron' option, and
     363 *                           database performance issues.
    337364 * @param bool   $wp_error   Optional. Whether to return a WP_Error on failure. Default false.
    338365 * @return bool|WP_Error True if event successfully rescheduled. False or WP_Error on failure.
    … …  
    455482 * @param array  $args      Optional. Array containing each separate argument to pass to the hook's callback function.
    456483 *                          Although not passed to a callback, these arguments are used to uniquely identify the
    457  *                          event, so they should be the same as those used when originally scheduling the event.
    458  *                          Default empty array.
     484 *                          event, so they must match those used when originally scheduling the event. If the
     485 *                          arguments do not match exactly, the event will not be found. Default empty array.
    459486 * @param bool   $wp_error  Optional. Whether to return a WP_Error on failure. Default false.
    460487 * @return bool|WP_Error True if event successfully unscheduled. False or WP_Error on failure.
    … …  
    540567 * @param array  $args     Optional. Array containing each separate argument to pass to the hook's callback function.
    541568 *                         Although not passed to a callback, these arguments are used to uniquely identify the
    542  *                         event, so they should be the same as those used when originally scheduling the event.
    543  *                         Default empty array.
     569 *                         event, so they must match those used when originally scheduling the event. If the
     570 *                         arguments do not match exactly, the event will not be found. Default empty array.
    544571 * @param bool   $wp_error Optional. Whether to return a WP_Error on failure. Default false.
    545572 * @return int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no
    … …  
    826853 * @param array  $args Optional. Array containing each separate argument to pass to the hook's callback function.
    827854 *                     Although not passed to a callback, these arguments are used to uniquely identify the
    828  *                     event, so they should be the same as those used when originally scheduling the event.
    829  *                     Default empty array.
     855 *                     event, so they must match those used when originally scheduling the event. If the
     856 *                     arguments do not match exactly, the event will not be found. Default empty array.
    830857 * @return int|false The Unix timestamp (UTC) of the next time the event will occur. False if the event doesn't exist.
    831858 */
Note: See TracChangeset for help on using the changeset viewer.