Usage Guide

Getting the HookManager

The HookManager is registered as a singleton by HookServiceProvider. Retrieve it from the container:

use WPZylos\Framework\Hooks\HookManager;

// By alias
$hooks = $app->make('hooks');

// By class name
$hooks = $app->make(HookManager::class);

Or instantiate directly (requires a ContextInterface):

$hooks = new HookManager($context);

WordPress Core Hooks

Use the wp* methods to hook into WordPress core actions and filters. These methods pass the hook name exactly as provided — no prefixing occurs.

Adding Actions

$hooks->wpAction('init', [$this, 'onInit']);
$hooks->wpAction('admin_menu', [$this, 'registerAdminMenu'], 20);
$hooks->wpAction('wp_enqueue_scripts', [$this, 'enqueueAssets']);

Adding Filters

$hooks->wpFilter('the_content', [$this, 'modifyContent']);
$hooks->wpFilter('the_title', [$this, 'filterTitle']);
$hooks->wpFilter('body_class', [$this, 'addBodyClasses'], 10, 2);

Removing WordPress Hooks

$hooks->removeWpAction('init', [$this, 'onInit']);
$hooks->removeWpFilter('the_content', [$this, 'modifyContent']);

// Must match the same priority used when adding
$hooks->removeWpAction('admin_menu', [$this, 'registerAdminMenu'], 20);

Custom Plugin Hooks

Use the plain methods (action, filter, doAction, applyFilter) for your plugin's own custom hooks. These methods automatically prefix the hook name using $context->hook() to prevent collisions between plugins.

For example, if your plugin prefix is "myplugin", calling action('user_created', ...) registers a listener on the WordPress hook myplugin_user_created.

Registering Custom Action Listeners

// Listens on: {prefix}_user_created
$hooks->action('user_created', [$this, 'onUserCreated']);

// With priority
$hooks->action('settings_saved', [$this, 'onSettingsSaved'], 20);

Registering Custom Filter Listeners

// Listens on: {prefix}_settings
$hooks->filter('settings', [$this, 'filterSettings']);

// With priority and accepted args
$hooks->filter('email_recipients', [$this, 'filterRecipients'], 10, 2);

Firing Custom Actions

// Fires: {prefix}_user_created with $user as argument
$hooks->doAction('user_created', $user);

// Multiple arguments
$hooks->doAction('order_placed', $order, $customer);

Applying Custom Filters

// Applies: {prefix}_settings filter to $defaults
$settings = $hooks->applyFilter('settings', $defaults);

// With additional arguments
$price = $hooks->applyFilter('product_price', $basePrice, $product);

Note: The method is applyFilter() (singular), not applyFilters().

Removing Custom Hook Listeners

$hooks->removeAction('user_created', [$this, 'onUserCreated']);
$hooks->removeFilter('settings', [$this, 'filterSettings']);

// Must match the same priority
$hooks->removeAction('settings_saved', [$this, 'onSettingsSaved'], 20);

One-Time Hooks

The once() method registers a WordPress action that automatically removes itself after first execution. The hook name is used as-is (not prefixed).

$hooks->once('init', function () {
    // This runs only once, then the hook is removed
    update_option('my_plugin_initialized', true);
});

$hooks->once('admin_init', [$this, 'runMigration']);

Hook Registry & Introspection

HookManager tracks all hooks registered through it, enabling runtime introspection.

Get All Registered Actions

$actions = $hooks->getRegisteredActions();
// Returns: ['hook_name' => [['callable' => ..., 'priority' => 10], ...]]

Get All Registered Filters

$filters = $hooks->getRegisteredFilters();

Check If a Hook Is Registered

if ($hooks->hasHook('init')) {
    // An action or filter is registered on 'init'
}

// For custom hooks, use the full prefixed name
if ($hooks->hasHook($hooks->prefix('user_created'))) {
    // A listener is registered on the prefixed 'user_created' hook
}

Get Prefixed Hook Name

$prefixed = $hooks->prefix('settings');
// Returns: "myplugin_settings" (depending on your plugin prefix)

Method Chaining

All registration methods return static, enabling fluent chaining:

$hooks
    ->wpAction('init', [$this, 'onInit'])
    ->wpAction('admin_menu', [$this, 'registerMenu'])
    ->wpFilter('the_content', [$this, 'filterContent'])
    ->action('settings_saved', [$this, 'onSettingsSaved'])
    ->filter('settings', [$this, 'filterSettings']);

Service Provider Registration

The HookServiceProvider automatically registers the HookManager when added to your application:

// In your plugin bootstrap
$app->register(new HookServiceProvider());

// HookManager is now available as:
$hooks = $app->make('hooks');
$hooks = $app->make(HookManager::class);