Core Hooks Reference: Actions, Filters & Usage Guide

Order Daemon Docs

Core Hooks Reference

This comprehensive reference documents all public WordPress hooks (actions and filters) exposed by Order Daemon Core that are intended for safe use by third-party plugins and site customizations.

Usage Guidelines

  • Stability: All hooks listed here are stable and designed for extension
  • Security: Continue to observe capability checks and odcm_can_use() for premium-gated features
  • Text Domain: All examples assume the order-daemon text domain for internationalization
  • Internal Hooks: Do not rely on undocumented internal hooks not listed here

Component Registration Hooks

Component Registration Actions

odcm_register_triggers

Purpose: Register custom Trigger components with the Rule Component Registry

When it fires: During options/registry load (plugin init) when Core is assembling available components

Arguments:

  • $registry (RuleComponentRegistry) — The registry instance to register components into

Example:

add_action('odcm_register_triggers', function ($registry) {
    $registry->register_trigger(new \Vendor\Plugin\Rules\MyTrigger());
});

odcm_register_conditions

Purpose: Register custom Condition components with the Rule Component Registry

Arguments: Same as odcm_register_triggers

Example:

add_action('odcm_register_conditions', function ($registry) {
    $registry->register_condition(new \Vendor\Plugin\Rules\MyCondition());
});

odcm_register_actions

Purpose: Register custom Action components with the Rule Component Registry

Arguments: Same as odcm_register_triggers

Example:

add_action('odcm_register_actions', function ($registry) {
    $registry->register_action(new \Vendor\Plugin\Rules\MyAction());
});

Rule Builder and Persistence Hooks

Rule Builder Configuration Filters

odcm_rule_builder_config

Purpose: Adjust Rule Builder UI configuration before it’s passed to the frontend

When it applies: In Admin\RuleBuilder when preparing editor configuration

Signature:

$config = apply_filters('odcm_rule_builder_config', array $config)

Returns: Modified configuration array

Example:

add_filter('odcm_rule_builder_config', function (array $config): array {
    $config['ui'] = $config['ui'] ?? [];
    $config['ui']['my_plugin_enabled'] = true;
    return $config;
});

Rule Validation and Persistence Filters

odcm_before_rule_validation

Purpose: Last chance to adjust rule payload before server-side validation runs

When it applies: In API\RuleBuilderApiController when saving a rule

Signature:

$rule_data = apply_filters('odcm_before_rule_validation', array $rule_data, int $rule_id|null, WP_Post|null $post)

Returns: Adjusted rule payload array

Example:

add_filter('odcm_before_rule_validation', function (array $rule, $rule_id, $post) {
    // Ensure a default title if missing
    if (empty($rule['title'])) {
        $rule['title'] = __('Default Rule Title', 'order-daemon');
    }
    return $rule;
}, 10, 3);

odcm_before_rule_save

Purpose: Sanitize/transform rule data right before persistence

When it applies: In API\RuleBuilderApiController after validation

Signature:

$sanitized = apply_filters('odcm_before_rule_save', array $sanitized, int $rule_id|null, WP_Post|null $post)

Returns: Sanitized payload array

Example:

add_filter('odcm_before_rule_save', function (array $rule, $rule_id, $post) {
    // Remove any experimental fields
    unset($rule['experimental']);
    return $rule;
}, 10, 3);

Rule Save Actions

odcm_after_rule_save

Purpose: React after a rule has been successfully saved

When it fires: In API\RuleBuilderApiController after persistence succeeds

Signature:

do_action('odcm_after_rule_save', array $data, int $rule_id, WP_Post $post)

Example:

add_action('odcm_after_rule_save', function (array $data, int $rule_id, WP_Post $post) {
    // Emit an audit event
    if (function_exists('odcm_log_event')) {
        odcm_log_event(
            __('Rule saved successfully', 'order-daemon'),
            ['rule_id' => $rule_id, 'title' => $data['title'] ?? 'Untitled'],
            null,
            'info',
            'rule_management'
        );
    }
}, 10, 3);

Webhook and Gateway Integration Hooks

Gateway Adapter Registration

odcm_register_gateway_adapters

Purpose: Register webhook gateway adapters with the Event Router

When it fires: In Core\Events\EventRouter during setup

Signature:

do_action('odcm_register_gateway_adapters', EventRouter $router)

Example:

use OrderDaemon\CompletionManager\Core\Events\Adapters\AbstractGatewayAdapter;

add_action('odcm_register_gateway_adapters', function ($router) {
    $custom_adapter = new class extends AbstractGatewayAdapter {
        public function get_slug(): string { return 'my-gateway'; }
        public function process_payload(array $payload): array {
            // Custom processing logic
            return ['status' => 'processed'];
        }
    };

    $router->register_adapter('my-gateway', $custom_adapter);
});

Webhook Test Configuration

odcm_webhook_test_event_types

Purpose: Alter the list of test event types available in admin test tools

When it applies: In API\WebhookTestPayloads when enumerating types

Signature:

$event_types = apply_filters('odcm_webhook_test_event_types', array $event_types, string $gateway)

Returns: Array of event type slugs/labels

Example:

add_filter('odcm_webhook_test_event_types', function (array $types, string $gateway) {
    if ($gateway === 'my-gateway') {
        $types['custom_event'] = __('Custom Event Type', 'order-daemon');
    }
    return $types;
}, 10, 2);

odcm_webhook_test_payload

Purpose: Provide custom payload for given gateway+event type in admin test tools

When it applies: In API\WebhookTestPayloads before falling back to built-ins

Signature:

$payload = apply_filters('odcm_webhook_test_payload', mixed $payloadOrNull, string $gateway, string $event_type)

Returns: Array, string, or null payload (null lets Core provide defaults)

Example:

add_filter('odcm_webhook_test_payload', function ($payload, string $gateway, string $event) {
    if ($gateway === 'my-gateway' && $event === 'custom_event') {
        return [
            'order_id' => 1234,
            'event' => 'custom_processing',
            'timestamp' => current_time('mysql')
        ];
    }
    return $payload;
}, 10, 3);

Dashboard and Diagnostics Hooks

Insight Dashboard Configuration

odcm_insight_dashboard_accordion_state

Purpose: Control the open/closed state of sections in the Insight dashboard UI

When it applies: In Admin\InsightDashboard when rendering

Signature:

$state = apply_filters('odcm_insight_dashboard_accordion_state', array $state)

Returns: UI state array

odcm_debug_source_labels

Purpose: Adjust labels used for debug source badges or listings in the Insight UI

When it applies: In Admin\InsightDashboard

Signature:

$labels = apply_filters('odcm_debug_source_labels', array $labels)

Returns: Array of slug => label mappings

odcm_insight_dashboard_settings_sections

Purpose: Inject additional settings sections into the Insight dashboard settings area

When it fires: In Admin\InsightDashboard when building settings UI

Signature:

do_action('odcm_insight_dashboard_settings_sections')

Attribution and Performance Hooks

Context Caching

odcm_enable_context_cache

Purpose: Enable/disable caching for context building to balance performance vs freshness

When it applies: In Core\AttributionTracker

Signature:

$enabled = (bool) apply_filters('odcm_enable_context_cache', bool $defaultTrue)

Returns: Boolean indicating if caching should be enabled

Attribution Context

odcm_attribution_context

Purpose: Inspect/alter the attribution context array built for evaluations/logging

When it applies: In Core\AttributionTracker

Signature:

$context = (array) apply_filters('odcm_attribution_context', array $context)

Returns: Modified context array

Deep Attribution Controls

odcm_enable_deep_attribution

Purpose: Toggle more expensive call-stack/backtrace attribution

When it applies: In Core\AttributionTracker (multiple sites in codepath)

Signature:

$enabled = (bool) apply_filters('odcm_enable_deep_attribution', bool $defaultTrue)

Returns: Boolean indicating if deep attribution should be enabled

odcm_attribution_backtrace_limit

Purpose: Limit the number of frames inspected during deep attribution

When it applies: In Core\AttributionTracker

Signature:

$limit = (int) apply_filters('odcm_attribution_backtrace_limit', int $default20)

Returns: Integer frame limit

odcm_attribution_time_budget_ms

Purpose: Millisecond budget for deep attribution work

When it applies: In Core\AttributionTracker

Signature:

$ms = (int) apply_filters('odcm_attribution_time_budget_ms', int $default25)

Returns: Time budget in milliseconds

Process Lifecycle

odcm_process_lifecycle_families

Purpose: Alter process lifecycle family definitions (groupings used for timeline correlation)

When it applies: In Core\ProcessLifecycleDiscovery

Signature:

$families = apply_filters('odcm_process_lifecycle_families', array $families)

Returns: Modified families array

Dynamic Checkout Context (Advanced)

Purpose: Provide gateway-specific context shaping during checkout/webhook processing

When it applies: In Core\CheckoutContextBuilder with dynamic filter name constructed at runtime

Signature:

$filtered = apply_filters($filter_name, array $context, WC_Order $order|null, $gateway_instance)

Note: Inspect runtime logs or the builder to determine exact filter name your gateway receives. Prefer using the generic odcm_attribution_context when possible if you cannot target the dynamic name.

Entitlements and Premium Detection

odcm_is_premium_user

Purpose: Allow Pro (or site policy) to short-circuit entitlement checks globally

When it applies: In src/Includes/functions.php within odcm_can_use()

Signature:

$is_premium = apply_filters('odcm_is_premium_user', bool $defaultFalse)

Returns: Boolean — treat with care; intended for Pro/licensing to override

Warning: This filter affects global entitlement behavior. Use responsibly and ensure proper licensing validation.

Best Practices

Hook Priorities

  • Prefer default priority (10) unless you need to run earlier/later
  • Document your priority assumptions and dependencies
  • Use early priorities (< 10) for data preparation, later priorities (> 10) for cleanup

Return Types and Data Integrity

  • Match return types exactly (e.g., return array for filters declared to return arrays)
  • Validate input data before processing
  • Preserve data structure when modifying arrays or objects

Internationalization

  • Pass labels/messages through translation functions with the order-daemon text domain
  • Use proper context for translations where ambiguity might exist
  • Test with different locales to ensure proper text rendering

Security Considerations

  • Do not weaken permission checks in your hook handlers
  • For REST-facing changes, continue to use nonces and capability guards
  • Do not bypass server-side entitlement checks
  • Sanitize and validate all user inputs

Performance

  • Be mindful of hook execution frequency
  • Use caching appropriately for expensive operations
  • Avoid blocking operations in frequently-called hooks
  • Consider using wp_schedule_single_event() for deferred processing

Error Handling

  • Implement proper error handling and logging
  • Use odcm_log_event() for audit trails when available
  • Fail gracefully and provide meaningful error messages
  • Avoid fatal errors that could break the checkout process

Was this article helpful?

  • Loading...
Table of Contents
  • Loading...