Filter uncanny-automator

automator_log_backtrace_property_enabled

Filters whether the backtrace property is enabled for automation logs before it's saved.

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

Description

This filter allows developers to control whether backtrace information is logged during recipe execution. By default, it respects the `AUTOMATOR_DEBUG_MODE` constant. Use this hook to conditionally enable or disable backtrace logging based on custom logic, such as specific recipe IDs or user roles, to manage performance impact in production environments.

Usage

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

Parameters

$default (mixed): This parameter contains the default value for whether the backtrace property should be enabled, typically determined by the `AUTOMATOR_DEBUG_MODE` constant.
$args (mixed): This parameter holds the default value for whether the backtrace property is enabled, typically determined by the `AUTOMATOR_DEBUG_MODE` constant.

Return Value

The filtered value.

Examples

/**
 * Conditionally enable backtrace logging based on user role and debug mode.
 *
 * By default, the backtrace property is enabled if AUTOMATOR_DEBUG_MODE is defined as true.
 * This filter allows for more granular control, such as enabling it only for administrator users
 * or disabling it even when debug mode is on under certain conditions.
 *
 * @param bool  $default The default value for whether the backtrace property is enabled.
 * @param array $args    The arguments passed to the Automator process.
 *
 * @return bool Whether the backtrace property should be enabled.
 */
function my_automator_enable_backtrace_property( $default, $args ) {

	// If debug mode is off, we generally want to keep it off, unless there's a specific reason.
	if ( ! $default ) {
		// Perhaps we want to enable it for a specific trigger type during development, even if AUTOMATOR_DEBUG_MODE is false.
		// Example: if ( isset( $args['trigger_type'] ) && 'my_specific_trigger' === $args['trigger_type'] ) {
		//     return true;
		// }
		return false; // Default to false if debug mode is off.
	}

	// If debug mode is on, we want to potentially enable it, but with further conditions.
	// Example: Only enable backtrace for administrators when debug mode is on.
	if ( current_user_can( 'administrator' ) ) {
		return true;
	}

	// Otherwise, if debug mode is on but the user is not an administrator, we might want to disable it
	// to avoid unnecessary logging in a shared development environment.
	return false;
}
add_filter( 'automator_log_backtrace_property_enabled', 'my_automator_enable_backtrace_property', 10, 2 );

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/process/class-automator-recipe-process-complete.php:160

public function add_backtrace_property( $args ) {

		$default    = defined( 'AUTOMATOR_DEBUG_MODE' ) && AUTOMATOR_DEBUG_MODE;
		$is_enabled = apply_filters( 'automator_log_backtrace_property_enabled', $default, $args );

		// Only run backtrace when debug mode is on — it's expensive in production.
		if ( false === $is_enabled ) {
			return;
		}

		$stack_trace = explode( ' ', wp_debug_backtrace_summary() ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_wp_debug_backtrace_summary

		$properties = new Properties();

		$properties->add_item(
			array(
				'type'       => 'code',
				'label'      => esc_html__( 'Trigger backtrace (for support)', 'uncanny-automator' ),
				'value'      => var_export( $stack_trace, true ), // phpcs:ignore
				'attributes' => array(
					'code_language' => 'PHP',
				),
			)
		);

		$properties->record_trigger_properties( array( 'args' => $args ) );
	}