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...