CRON often returns ambiguous values

[evansolomon]

Many of the cron API functions return ambiguous values. For example, wp_cron() ​returns null (explicitly) when cron doesn't run, but it also returns null (implicitly) every other time. This can make debugging harder.

Whenever possible, I think it's valuable to return meaningful values. The attached patch does that.

[nacin]

I think this is good. While there are technically return value changes, I'm not too concerned about the back compat.

wp_clear_scheduled_hook() probably just needs to return true (it got cleared) or false, versus an array. It's also possible we change how that function works in the future, #25773 gave us some trouble.

The wp_remote_post() call is non-blocking, so spawn_cron() should probably not have a return value, right? Thus wp_cron() shouldn't have a return value either. I know that was the original bug report — what about true? Is that sufficient?

[jrf]

Refresh of the earlier patch.

[jrf]

I've refreshed @evansolomon's patch.

(and boyscouted inline control structures in the touched functions).

[ericlewis]

#31598 was marked as a duplicate.

[peterwilsoncc]

This got dragged in to the patch for #32656 as return values are needed for that too.

I'll take into account @nacin's comment re return values as part of that.

[peterwilsoncc]

In 21072.diff​:

• wp_schedule_single_event(), wp_schedule_event(), wp_reschedule_event() and wp_unschedule_event(): boolean outcome
• wp_clear_scheduled_hook(): false if fails to unschedule one or more events, zero if no events need to be unscheduled, or number of events unscheduled. If there are events to unschedule, partial success is possible.
• wp_unschedule_hook() : false if it fails to unschedule events, zero if no events need to be unscheduled, or number of events unscheduled. If there are events to unschedule, partial success is not possible.
• spawn_cron() false if no attempt to spawn, outcome of wp_remote_post() if an attempt is made (either an array or WP_Error)
• wp_cron(): false if one or more events fail to spawn, zero if no events require spawning, integer indicating number of events spawned if all successful
• _set_cron_array(): boolean outcome of update_option().

Tests updated to include return values.

[peterwilsoncc]

Working on this on a ​Github PR

[peterwilsoncc]

21072.3.diff​ is a tidy up of earlier patches:

• Fixes some CS errors
• Ensures _set_cron_array is only called when need when unscheduling

I've got a 👌 from Pento on the ​Github PR so labeling commit for next time I've got vvv runnning.

[peterwilsoncc]

In 43050:

Cron API: Return meaningful values from cron functions.

Return values added to Cron API functions to indicate outcome:

• wp_schedule_single_event(), wp_schedule_event(), wp_reschedule_event() and wp_unschedule_event(): boolean indicating success or failure,
• wp_clear_scheduled_hook(): integer indicating number of jobs cleared (zero or more), false if one or more jobs fail to clear,
• wp_unschedule_hook(): integer indicating number of jobs cleared (zero or more), false if the jobs fail to clear,
• spawn_cron(): boolean indicating whether job spawned,
• wp_cron(): integer indicating number of jobs spawned (zero or more), false if one or more jobs fail to spawned,
• _set_cron_array(): boolean outcome of update_option().

Props evansolomon, jrf, peterwilsoncc, pento for code review.
Fixes #21072.

[peterwilsoncc]

Milestone changed to the 5.1 branch, inline docs will need to be updated.

[desrosj]

In 44324:

Docs: Correct inline documentation versions.

[43050] updated the Cron API to return values indicating success or failure when called.

At the time, these changes were slated for 5.0, but have since been moved to the 5.1 release. This updates the inline documentation to reflect that.

Fixes #21072.

[desrosj]

This was detailed in the following dev note: ​https://make.wordpress.org/core/2019/01/23/cron-api-changes-in-wordpress-5-1/