Filter uncanny-automator

automator_trigger_should_complete

Filters whether a trigger should complete its execution after running its actions.

add_filter( 'automator_trigger_should_complete', $callback, 10, 2 );

Description

Filters whether a trigger should fully complete its execution. Developers can use this hook to conditionally prevent a trigger from proceeding based on custom logic, useful for advanced validation or error handling within Automator recipes. The `$process_further` parameter determines the outcome.

Usage

add_filter( 'automator_trigger_should_complete', 'your_function_name', 10, 2 );

Parameters

$do_action (mixed)
This parameter represents the default return value of the filter, typically indicating whether the trigger should proceed with completion.
$this (mixed)
This parameter indicates whether the action associated with the trigger should be executed.

Return Value

The filtered value.

Examples

/**
 * Conditionally prevents a trigger from completing if a specific condition is met.
 *
 * This example demonstrates how to use the 'automator_trigger_should_complete'
 * filter to prevent a trigger from proceeding. In this scenario, we'll assume
 * we want to stop the trigger if the 'post_status' within the trigger arguments
 * is 'draft'.
 *
 * @param bool   $process_further The default value, indicating whether to proceed with the trigger completion.
 * @param array  $do_action       An array containing data related to the trigger execution.
 *                                Includes 'trigger_entry', 'entry_args', and 'trigger_args'.
 * @param object $trigger_object  The current trigger object instance.
 *
 * @return bool Whether the trigger should proceed with completion.
 */
add_filter( 'automator_trigger_should_complete', function ( $process_further, $do_action, $trigger_object ) {

	// Check if the 'trigger_args' key exists and if it contains 'post_status'.
	if ( isset( $do_action['trigger_args'] ) && is_array( $do_action['trigger_args'] ) && isset( $do_action['trigger_args']['post_status'] ) ) {

		// If the post status is 'draft', we don't want to complete the trigger.
		if ( 'draft' === $do_action['trigger_args']['post_status'] ) {
			// Log a message for debugging purposes (optional).
			error_log( 'Automator: Trigger completion prevented due to draft post status.' );
			return false; // Prevent the trigger from completing.
		}
	}

	// If no specific condition is met to prevent completion, return the original value.
	return $process_further;

}, 10, 3 );

Placement

This code should be placed in the functions.php file of your active theme, a custom plugin, or using a code snippets plugin.

Source Code

src/core/lib/recipe-parts/triggers/abstract-trigger.php:544
src/core/lib/recipe-parts/triggers/trait-triggers.php:254

protected function process( $recipe_id, $trigger, $hook_args ) {

		if ( Automator()->is_recipe_throttled( absint( $recipe_id ), absint( $this->user_id ) ) ) {
			return;
		}

		$this->recipe_log_id = $this->maybe_create_recipe_log_entry( $this->recipe_id );

		$this->trigger_log_entry = $this->maybe_create_trigger_log_entry( $this->recipe_id, $this->recipe_log_id, $this->trigger );

		$this->trigger_records = array(
			'code'           => $this->get_code(),
			'user_id'        => $this->user_id,
			'trigger_id'     => (int) $this->trigger['ID'],
			'recipe_id'      => $this->recipe_id,
			'trigger_log_id' => $this->trigger_log_entry,
			'recipe_log_id'  => $this->recipe_log_id,
			'run_number'     => (int) Automator()->get->next_run_number( $this->recipe_id, $this->user_id, true ),
			'meta'           => $this->get_trigger_meta(),
			'get_trigger_id' => $this->trigger_log_entry,
		);

		$this->token_values = $this->hydrate_tokens( $this->trigger, $this->hook_args );
		$this->save_tokens( $this->get_code(), $this->token_values );

		$do_action = array(
			'trigger_entry' => $this->trigger,
			'entry_args'    => $this->trigger_records,
			'trigger_args'  => $this->hook_args,
		);

		do_action( 'automator_before_trigger_completed', $do_action, $this );

		$process_further = apply_filters( 'automator_trigger_should_complete', true, $do_action, $this );

		if ( $process_further ) {
			// Register the hook.
			$this->register_loopable_trigger_tokens_hooks( $do_action );
			// Fire the hook.
			do_action( 'automator_loopable_token_hydrate', $do_action['entry_args'], $do_action['trigger_args'] );
			// Complete the trigger.
			Automator()->complete->trigger( $this->trigger_records );
		}

		do_action( 'automator_after_maybe_trigger_complete', $do_action, $this );
	}

Internal Usage

Found in src/core/classes/class-api-server.php:67:

add_filter( 'automator_trigger_should_complete', array( $this, 'maybe_log_trigger' ), 10, 3 );
Scroll to Top