superpowers-sage:wp-hooks-lifecycle

WordPress Hooks and Lifecycle

When to use

When adding, modifying, or debugging WordPress hooks (actions and filters) within a Sage/Acorn project. This covers where to place hooks in the Sage architecture, understanding execution order, managing priority, using dependency injection in callbacks, and diagnosing hook-related issues.

Inputs required

• The behavior to implement or modify (what the hook should accomplish)
• Whether the task requires an action (side effect) or a filter (data transformation)
• The appropriate lifecycle stage for the hook

Procedure

1. Understand actions vs filters

• Actions perform side effects: register post types, enqueue scripts, send emails, flush caches.
  • add_action('hook_name', $callback, $priority, $accepted_args)
  • Callback returns nothing (return value is ignored).
• Filters transform data: modify queries, alter output, change settings.
  • add_filter('hook_name', $callback, $priority, $accepted_args)
  • Callback MUST return the filtered value.

2. WordPress lifecycle order

See references/hook-timing.md for the full boot sequence and early/late hook guidance.

Quick reference:

plugins_loaded → after_setup_theme → init → wp_loaded → wp_enqueue_scripts → the_content

3. Where to place hooks in Sage

See references/acorn-hook-patterns.md for the three correct hook locations in Acorn.

Preferred: boot() method in a ServiceProvider:

class ProjectServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        add_action('init', [$this, 'registerPostTypes']);
        add_action('wp_enqueue_scripts', [$this, 'enqueueAssets']);
        add_filter('the_content', [$this, 'appendProjectMeta']);
        add_filter('pre_get_posts', [$this, 'modifyProjectQuery']);
    }
}

4. Priority and argument count

// Default priority is 10, default accepted_args is 1
add_action('save_post', [$this, 'onSave'], 10, 3);

// Lower number = runs earlier
add_action('init', [$this, 'earlyInit'], 5);
add_action('init', [$this, 'lateInit'], 20);

// accepted_args must match callback parameters
add_filter('the_title', function (string $title, int $post_id) {
    return $title . ' #' . $post_id;
}, 10, 2);