Docs: Clarify that cron event arguments must match when using wp_sche… by manishdhorepatil-art · Pull Request #10890 · WordPress/wordpress-develop

manishdhorepatil-art · 2026-02-09T12:34:11Z

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

https://core.trac.wordpress.org/ticket/43801

…dule_event() and wp_next_scheduled()

github-actions · 2026-02-09T12:34:23Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props manishxdp, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-02-09T12:44:29Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

src/wp-includes/cron.php

Co-authored-by: Weston Ruter <westonruter@gmail.com>

manishdhorepatil-art · 2026-02-12T12:14:31Z

@westonruter changes done here

manishdhorepatil-art · 2026-02-13T18:01:24Z

@westonruter can you please review this i have updated the changes

westonruter · 2026-02-13T18:05:11Z

src/wp-includes/cron.php

- *                           hook's callback function. Each value in the array
- *                           is passed to the callback as an individual parameter.
- *                           The array keys are ignored. Default empty array.
+ * @param array  $args {


Why the introduction of the brace? This is typically only used when describing the structure of the array itself, not for encapsulating a multi-line description. I believe the braces should be removed and the originally indentation restored.

@westonruter Thanks for the review! You're absolutely right - braces should only be used when describing array structure with @type tags, not for multi-line descriptions. I've removed the braces and restored the proper indentation for both occurrences in the file. can you check now

westonruter · 2026-02-13T18:05:21Z

src/wp-includes/cron.php

- *                           hook's callback function. Each value in the array
- *                           is passed to the callback as an individual parameter.
- *                           The array keys are ignored. Default empty array.
+ * @param array  $args {


Ditto above about the brace.

…ress-develop into 43801

src/wp-includes/cron.php

* trunk: Docs: Add missing `@global` variable descriptions.

This commit improves the documentation for the $args parameter in the Cron API to provide consistent and clear guidance on the importance of matching arguments for unique event identification. Summary of changes: - Unified clarification for scheduling functions: Added a consistent explanatory paragraph to wp_schedule_single_event(), wp_schedule_event(), and wp_reschedule_event(). - Synchronized retrieval and removal functions: Updated wp_unschedule_event(), wp_clear_scheduled_hook(), and wp_next_scheduled() to explicitly state that events will not be found if arguments do not match exactly. - Strictly maintained project standards for line wrapping and indentation. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

westonruter · 2026-02-13T18:56:06Z

@manishdhorepatil-art I've added 31d0167 with an assist from Gemini CLI. Please review.

manishdhorepatil-art · 2026-02-13T19:03:43Z

@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 · 2026-02-13T19:09:33Z

@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.

westonruter · 2026-02-13T19:26:55Z

@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()

manishdhorepatil-art · 2026-02-13T19:31:48Z

@westonruter You're absolutely right. Thank you for the correction!

westonruter · 2026-02-13T19:44:28Z

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.)

…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 #10890 Props manishxdp, westonruter, ovidiul, digamberpradhan. Fixes #43801. git-svn-id: https://develop.svn.wordpress.org/trunk@61639 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2026-02-13T20:26:15Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61639
GitHub commit: 208ec4d

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

…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 WordPress/wordpress-develop#10890 Props manishxdp, westonruter, ovidiul, digamberpradhan. Fixes #43801. Built from https://develop.svn.wordpress.org/trunk@61639 git-svn-id: http://core.svn.wordpress.org/trunk@60950 1a063a9b-81f0-0310-95a4-ce76da25c4cd

…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 WordPress#10890 Props manishxdp, westonruter, ovidiul, digamberpradhan. Fixes #43801. git-svn-id: https://develop.svn.wordpress.org/trunk@61639 602fd350-edb4-49c9-b593-d223f7449a82

Docs: Clarify that cron event arguments must match when using wp_sche…

e6dc190

…dule_event() and wp_next_scheduled()

Merge branch 'trunk' into 43801

ba02934

Merge branch 'trunk' into 43801

4a11a37

westonruter reviewed Feb 10, 2026

View reviewed changes

src/wp-includes/cron.php Outdated Show resolved Hide resolved

src/wp-includes/cron.php Outdated Show resolved Hide resolved

manishdhorepatil-art and others added 4 commits February 11, 2026 10:41

Update src/wp-includes/cron.php

55d208d

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Update src/wp-includes/cron.php

e079a04

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Merge branch 'trunk' into 43801

00395e8

Merge branch 'trunk' into 43801

1108a41

manishdhorepatil-art added 2 commits February 13, 2026 09:38

Merge branch 'trunk' into 43801

4e676df

Merge branch 'trunk' into 43801

e8fcd21

westonruter reviewed Feb 13, 2026

View reviewed changes

manishdhorepatil-art added 2 commits February 13, 2026 23:40

pr updated

8753c1d

Merge branch '43801' of https://github.com/manishdhorepatil-art/wordp…

a7d336f

…ress-develop into 43801

westonruter reviewed Feb 13, 2026

View reviewed changes

src/wp-includes/cron.php Outdated Show resolved Hide resolved

westonruter reviewed Feb 13, 2026

View reviewed changes

src/wp-includes/cron.php Outdated Show resolved Hide resolved

manishdhorepatil-art and others added 3 commits February 14, 2026 00:00

commets resolved

3817d3d

Merge branch 'trunk' into 43801

f0dca63

* trunk: Docs: Add missing `@global` variable descriptions.

westonruter approved these changes Feb 13, 2026

View reviewed changes

github-actions bot closed this Feb 13, 2026

Conversation

manishdhorepatil-art commented Feb 9, 2026

Summary

Problem

Solution

Notes

Trac Ticket

Uh oh!

github-actions bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 9, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

Uh oh!

manishdhorepatil-art commented Feb 12, 2026

Uh oh!

manishdhorepatil-art commented Feb 13, 2026

Uh oh!

westonruter Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

manishdhorepatil-art Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

westonruter commented Feb 13, 2026

Uh oh!

manishdhorepatil-art commented Feb 13, 2026

Uh oh!

westonruter commented Feb 13, 2026

Uh oh!

westonruter commented Feb 13, 2026

Uh oh!

manishdhorepatil-art commented Feb 13, 2026

Uh oh!

westonruter commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Feb 9, 2026 •

edited

Loading