Filter uncanny-automator

automator_maybe_parse_{$matching_token}

Filters the value of a specific token before it's replaced in automation content.

add_filter( 'automator_maybe_parse_{$matching_token}', $callback, 10, 5 );

Description

This filter allows modification of how specific tokens are parsed and replaced. Developers can intercept and alter the replacement value for a given token before it's inserted into the field text. This hook is invoked during the token parsing process, enabling custom logic for predefined or custom tokens.

Usage

add_filter( 'automator_maybe_parse_{$matching_token}', 'your_function_name', 10, 5 );

Parameters

$replaceable (mixed)
This parameter represents the value that will replace the matched token.
$field_text (mixed)
This parameter holds the value that will replace the matched token.
$matching_token (mixed)
This parameter contains the original text where the `$matching_token` was found, allowing for context-aware replacements.
$user_id (mixed)
This parameter holds the specific token that was found and is being processed for replacement.
$args (mixed)
This parameter contains the ID of the user for whom the token is being parsed.

Return Value

The filtered value.

Examples

/**
 * Example filter for automator_maybe_parse_{$matching_token} hook.
 *
 * This filter allows for custom parsing of specific tokens within the Automator plugin.
 * In this example, we'll demonstrate how to handle a hypothetical 'YOUR_CUSTOM_POST_TITLE' token.
 *
 * @param mixed $replaceable The value to replace the token with.
 * @param mixed $field_text The original text containing the token.
 * @param string $matching_token The token that was matched (e.g., 'YOUR_CUSTOM_POST_TITLE').
 * @param int $user_id The ID of the user performing the action.
 * @param array $args Additional arguments passed to the parser.
 *
 * @return mixed The modified value to replace the token.
 */
add_filter( 'automator_maybe_parse_YOUR_CUSTOM_POST_TITLE', function ( $replaceable, $field_text, $matching_token, $user_id, $args ) {

	// Check if the token is the one we want to handle.
	if ( 'YOUR_CUSTOM_POST_TITLE' === $matching_token ) {

		// Let's assume the $args array contains a 'post_id' key.
		// In a real scenario, you'd retrieve this from your trigger or action setup.
		$post_id = isset( $args['post_id'] ) ? absint( $args['post_id'] ) : 0;

		if ( $post_id ) {
			// Attempt to get the post title.
			$post_title = get_the_title( $post_id );

			// If a post title is found, return it to replace the token.
			if ( ! empty( $post_title ) ) {
				$replaceable = $post_title;
			} else {
				// Optionally, return a fallback if the post is not found or has no title.
				$replaceable = '[Post Not Found]';
			}
		} else {
			// Handle cases where post_id is not provided in args.
			$replaceable = '[Invalid Post ID]';
		}
	}

	// Always return the $replaceable variable.
	return $replaceable;

}, 10, 5 ); // Priority 10, accepts 5 arguments.

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/utilities/class-automator-input-parser.php:229
src/core/lib/utilities/class-automator-input-parser.php:391

// Predefined tokens.
			$is_predefined_token = in_array( $matching_token, $this->defined_tokens, true );
			if ( $is_predefined_token ) {
				$replaceable = $this->parse_defined_tokens_default( $matching_token, $args, $context );
			}

			$replaceable = apply_filters( "automator_maybe_parse_{$matching_token}", $replaceable, $field_text, $matching_token, $user_id, $args );
			$replaceable = apply_filters( 'automator_maybe_parse_replaceable', $replaceable );

			// Added fallback fix for action token meta in case it was not recorded earlier.
			if ( false === strpos( $matching_token, 'ACTION_META' ) ) {
				// Record the token raw vs replaceable with respect to $args for log details consumption.
				$parsed_tokens_record->record_token( '{{' . $matching_token . '}}', $replaceable, $args );
			}
Scroll to Top