Hook & Filter Strategy

Hook & Filter Strategy

This project leverages the native WordPress Plugin API to maintain a decoupled, modular architecture. By using actions and filters, you can extend or modify core functionalities without altering the underlying source code.

Architectural Philosophy

Our modular system relies on two primary interaction patterns:

1. Actions (Events): Allow you to execute custom code at specific execution points.
2. Filters (Interceptors): Allow you to intercept and modify data before it is processed or rendered.

Action Hooks

Actions are used to trigger side effects such as logging, sending notifications, or injecting scripts.

Usage Pattern

To hook into an event, use the standard WordPress add_action() function.

/**
 * Example: Triggering custom logic after a module initializes
 * 
 * @param string $module_name The name of the initialized module.
 * @param array  $context     Metadata related to the initialization.
 */
add_action('ua_module_initialized', function($module_name, $context) {
    if ($module_name === 'payment_gateway') {
        error_log('Payment module is ready.');
    }
}, 10, 2);

Common Action Hooks

| Hook Name | Description | Parameters | | :--- | :--- | :--- | | ua_before_component_render | Fires before a UI component is output. | (string) $component_id | | ua_data_sync_complete | Fires after a background sync process finishes. | (bool) $status, (int) $records_affected | | ua_api_response_received | Fires immediately after an external API call. | (array) $response_data |

Filter Hooks

Filters are critical for customizing configurations, modifying strings, or altering data structures before they are saved to the database or sent to the client.

Usage Pattern

Use add_filter() to modify data. Always ensure you return the modified value.

/**
 * Example: Modifying the default configuration for a feature
 * 
 * @param array $config The default configuration array.
 * @return array The modified configuration.
 */
add_filter('ua_feature_settings', function($config) {
    $config['enable_cache'] = true;
    $config['timeout'] = 3000;
    return $config;
});

Common Filter Hooks

| Hook Name | Description | Input Type | Output Type | | :--- | :--- | :--- | :--- | | ua_component_class_list | Modify CSS classes applied to components. | array | array | | ua_api_endpoint_url | Override the default API endpoint. | string | string | | ua_metadata_validation_rules | Add custom validation logic for metadata. | array | array |

Best Practices

To maintain a clean and performant integration, follow these guidelines when using our hook system:

• Priority Management: Use the default priority (10) for standard logic. Use a higher priority (e.g., 20+) to ensure your code runs after other modifications, or a lower priority (e.g., 5) for early-stage overrides.
• Context Awareness: Always check the parameters passed to the hook. Many filters provide a second or third parameter to provide context (e.g., a $post_id or $user_id).
• Avoid Heavy Logic in Filters: Since filters are often called multiple times during a single request, avoid performing expensive database queries or API calls inside a filter callback.
• Namespacing: While the project uses the ua_ prefix for its internal hooks, ensure your callback functions are appropriately namespaced or prefixed to avoid collisions with other plugins.

Debugging Hooks

To see all callbacks attached to a specific project hook, you can use the following snippet:

global $wp_filter;
// Replace 'ua_feature_settings' with the hook you are investigating
print_r($wp_filter['ua_feature_settings']);