Using WordPress ‘pre_unschedule_event’ PHP filter

by

‘pre_unschedule_event’ is a WordPress filter that is triggered just before an event is unscheduled.

This filter receives the event ID as a parameter and allows you to modify or cancel the unscheduling process.

Usage

function my_custom_preflight_unschedule( $pre, $timestamp, $hook, $args, $wp_error ) {
    // Your custom code here
    return $pre;
}
add_filter( 'pre_unschedule_event', 'my_custom_preflight_unschedule', 10, 5 );

Parameters

  • $pre (null|int|false|WP_Error)
    • The value to return instead of continuing the unscheduling process.
    • Default is null.
  • $timestamp (int)
    • Timestamp for when to run the event.
  • $hook (string)
    • The action hook whose events will be unscheduled.
  • $args (array)
    • Arguments to pass to the hook’s callback function.
  • $wp_error (bool)
    • Whether to return a WP_Error on failure.

Examples

Prevent Unscheduling of a Specific Event

function prevent_specific_event_unschedule( $pre, $timestamp, $hook, $args, $wp_error ) {
    if ( 'my_custom_hook' == $hook ) {
        return false; // Prevent unscheduling
    }
    return $pre;
}
add_filter( 'pre_unschedule_event', 'prevent_specific_event_unschedule', 10, 5 );

This example prevents unscheduling of events with the hook named my_custom_hook. The filter function checks if the $hook is equal to my_custom_hook, and if so, it returns false to prevent unscheduling. Otherwise, it returns $pre to continue the normal unscheduling process.

Log Unscheduled Events

function log_unscheduled_events( $pre, $timestamp, $hook, $args, $wp_error ) {
    error_log( "Unscheduling event: {$hook} at {$timestamp}" );
    return $pre;
}
add_filter( 'pre_unschedule_event', 'log_unscheduled_events', 10, 5 );

This example logs information about events being unscheduled. The filter function writes a log entry containing the $hook and $timestamp of the event being unscheduled.

Change Arguments Before Unscheduling

function change_args_before_unschedule( $pre, $timestamp, $hook, $args, $wp_error ) {
    if ( 'my_hook' == $hook ) {
        $args['my_arg'] = 'new_value'; // Modify the argument
    }
    return $pre;
}
add_filter( 'pre_unschedule_event', 'change_args_before_unschedule', 10, 5 );

In this example, the filter function checks if the $hook is equal to my_hook. If so, it changes the value of an argument in the $args array before the event is unscheduled.

Return WP_Error on Failure

function return_wp_error_on_failure( $pre, $timestamp, $hook, $args, $wp_error ) {
    if ( 'my_failing_hook' == $hook ) {
        return new WP_Error( 'my_error_code', 'This is a custom error message.' );
    }
    return $pre;
}
add_filter( 'pre_unschedule_event', 'return_wp_error_on_failure', 10, 5 );

This example returns a WP_Error if an event with the hook my_failing_hook is being unscheduled. The filter function creates a new WP_Error with a custom error code and message and returns it instead of the default $pre.

Custom Unschedule Handling

function custom_unschedule_handling( $pre, $timestamp, $hook, $args, $wp_error ) {
    if ( 'my_custom_unschedule' == $hook ) {
        // Custom unscheduling logic here
        return true; // Indicate that the event was successfully unscheduled
    }
    return $pre;
}
add_filter( 'pre_unschedule_event', 'custom_unschedule_handling', 10, 5 );

In this example, we have a custom unscheduling handling for events with the hook `my_custom_unschedule`. The filter function checks if the `$hook` is equal to `my_custom_unschedule`. If so, it performs custom unscheduling logic and returns `true` to indicate that the event was successfully unscheduled. Otherwise, it returns `$pre` to continue the normal unscheduling process.