![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
#43801 closed enhancement (fixed)
Need better documentation to show importance of checking for args while using wp_schedule_event and wp_next_scheduled
| Reported by: | digamberpradhan | Owned by: | westonruter |
|---|---|---|---|
| Priority: | normal | Milestone: | 7.0 |
| Component: | Cron API | Version: | |
| Severity: | normal | Keywords: | good-first-bug has-patch |
| Cc: | Focuses: | docs |
Description
While the user notes https://developer.wordpress.org/reference/functions/wp_next_scheduled/#user-contributed-notes do relay the importance. I believe it is important that the documentation also be more clear about the issue.
When coded incorrectly something like
function schedule_my_event(){
if ( ! wp_next_scheduled( 'myevent' ) ) { // This will always be false
wp_schedule_event( time(), 'daily', 'myevent', array( false ) );
}
}
add_action('init','schedule_my_event');
It's potentially disastrous for a site. The cron value in the options would keep on increasing until the database could no longer withstand it.
So keeping that in mind I feel the documentation for both wp_next_scheduled and wp_schedule_event should highlight this point more.
Attachments (1)
Change History (18)
#2
@
6 years ago
- Keywords needs-patch good-first-bug added
- Milestone Awaiting Review → Future Release
- Type defect (bug) → enhancement
This ticket was mentioned in PR #7055 on WordPress/wordpress-develop by @roshniahuja14.
2 years ago
#4
Trac ticket: [](https://core.trac.wordpress.org/ticket/43801)
This ticket was mentioned in PR #10890 on WordPress/wordpress-develop by @manishxdp.
5 months ago
#5
### Summary
Improves inline documentation for wp_schedule_event() and wp_next_scheduled() to clarify that the $args parameter is part of the unique identifier for scheduled cron events.
### Problem
If developers schedule an event with arguments but later check for existing events without passing the same arguments, WordPress treats them as different events. This can result in duplicate cron entries being created on every page load, potentially causing excessive growth of the cron option and database performance issues.
### Solution
This patch enhances the DocBlocks for both functions to:
- Clarify that event arguments must match exactly when checking or unscheduling events
- Explain how mismatched arguments can lead to duplicate scheduled events
- Add a usage example demonstrating correct and incorrect patterns
### Notes
This is a documentation-only change. No functional behavior is modified.
### Trac Ticket
@manishxdp commented on PR #10890:
5 months ago
#6
@westonruter changes done here
@manishxdp commented on PR #10890:
5 months ago
#7
@westonruter can you please review this i have updated the changes
@westonruter commented on PR #10890:
5 months ago
#9
@manishdhorepatil-art I've added 31d0167 with an assist from Gemini CLI. Please review.
@manishxdp commented on PR #10890:
5 months ago
#10
@westonruter yes it is better but we can be precise like this below this seems better
Docs: Add clarification about argument matching for cron event identification.
This commit adds a clarifying paragraph to wp_schedule_single_event() and
wp_reschedule_event() to emphasize that arguments must match exactly when
checking for or unscheduling events, as they are used to uniquely identify
scheduled events.
Changes:
- Added explanatory paragraph to wp_schedule_single_event() about argument matching for unique event identification
- Added explanatory paragraph to wp_reschedule_event() about argument matching for unique event identification
- Maintained original parameter description format with "Default empty array." at the end of the first paragraph
@westonruter commented on PR #10890:
5 months ago
#11
@manishdhorepatil-art I don't understand. Be more precise like what below? You copied the commit message from my commit. I'm not sure what you're saying.
@manishxdp commented on PR #10890:
5 months ago
#12
@westonruter Sorry for the confusion! I meant that I've updated the commit message to be more precise and focused on just the two functions that were changed (wp_schedule_single_event() and wp_reschedule_event()), rather than describing a broader harmonization across the entire Cron API. The new commit message accurately reflects that we maintained the original parameter description format and only added the clarifying paragraph about argument matching.
@westonruter commented on PR #10890:
5 months ago
#13
@manishdhorepatil-art Still not understanding. Are you proposing an SVN commit message with your above comment?
Note the docblocks were updated for these functions:
-
wp_schedule_single_event() -
wp_schedule_event() -
wp_reschedule_event() -
wp_unschedule_event() -
wp_clear_scheduled_hook() -
wp_next_scheduled()
@manishxdp commented on PR #10890:
5 months ago
#14
@westonruter You're absolutely right. Thank you for the correction!
@westonruter commented on PR #10890:
5 months ago
#15
Did I correct anything? I'm still having a hard time fully understanding your comments.
(If you're using AI for contributing, please note that you need to disclose this.)
@manishxdp commented on PR #10890:
5 months ago
#17
@westonruter Sorry for the confusion! I meant that I've updated the commit message to be more precise and focused on just the two functions that were changed (wp_schedule_single_event() and wp_reschedule_event()), rather than describing a broader harmonization across the entire Cron API. The new commit message accurately reflects that we maintained the original parameter description format and only added the clarifying paragraph about argument matching.
adding missing documentation text for
wp_schedule_eventandwp_next_scheduledfunctions