Expose the reason for failures that occur within WP-Cron functions

[johnbillion]

Since WordPress 5.1, the various WP-Cron related functions (wp_schedule_event() etc) ​now return meaningful return values, but this still doesn't expose the underlying reason for failure.

My WP Crontrol plugin regularly gets support requests from users who are managing cron events but getting a generic error message. It would be useful if core exposed the underlying problem so that anything that calls wp_schedule_event(), wp_unschedule_event() etc can provide a meaningful error message to the end user.

I see two potential approaches:

1. Add an optional $wp_error parameter to these functions, similar to wp_update_post(), wp_set_comment_status() etc, and return a meaningful error when one occurs.
2. Trigger an action containing the error details, similar to http_api_debug, which can be hooked into before calling the cron functions.

Trac ticket: https://core.trac.wordpress.org/ticket/49961

[johnbillion]

PR ready for review at ​https://github.com/WordPress/wordpress-develop/pull/914. One thing I'm particularly interested in hearing is if anybody thinks it will cause a problem for the various pre_* filters to now potentially pass a WP_Error object, when previously they only passed null|stdClass|false.

This is the nitiest of nits, but why no period on the error messages?

Thanks for the replies @johnbillion, this all looks good to me. Your reply about setting the array/updating option response makes sense.

[johnbillion]

The changes to the pre_* filters which means the $pre value can be a WP_Error after this change might have more of an impact than I thought. Looking through some plugin directory scans now.

[johnbillion]

Okay false alarm. We're all good. Only WP-Optimize needs an update for its back-compat function.

​pre_schedule_event

• ​https://wordpress.org/plugins/gdpress/ - no problem

​pre_reschedule_event

• No plugins affected

​pre_unschedule_event

• ​https://wordpress.org/plugins/wp-crontrol/ - no problem

​pre_clear_scheduled_hook

• No plugins affected

​pre_unschedule_hook

• ​https://wordpress.org/plugins/wp-optimize/ - Conditionally defines wp_unschedule_hook() if it doesn't exist. Will need to be updated with the new function signature.

---

In addition I checked ​Cavalcade, ​Cron Control, ​Action Scheduler, and ​WP Background Processing. Cavalcade will gracefully handle a WP_Error in all the $pre parameters with no change, and the others don't use the affected filters.

[johnbillion]

In 50143:

Cron API: Introduce a $wp_error parameter to functions that write to the cron array.

This allows the functions to return a WP_Error object containing more information in case of a problem, instead of just boolean false.

The various pre_ filters in these functions are also updated so they can return or be passed a WP_Error object.

Fixes #49961

https://core.trac.wordpress.org/changeset/50143

[desrosj]

In 50152:

Coding Standards: Fix several minor coding standards issues.

These are made by running composer format.

Follow up to [50124], [50129], [50143].

See #49961, #52192, #34281.

[SergeyBiryukov]

In 50174:

Docs: Add a @since note to wp_clear_scheduled_hook() for the $wp_error parameter.

Follow-up to [50143].

See #49961.

[johnbillion]

In 50394:

Cron API: Add a missing $wp_error parameter to the pre_reschedule_event filter.

Props tmatsuur, mukesh27

Fixes #52572
See #49961

[audrasjb]

Dev note published: ​https://make.wordpress.org/core/2021/02/23/miscellaneous-developer-focused-changes-in-wordpress-5-7/