README

WordPress hook management with plugin-scoped custom hooks for WPZylos framework.

📖 Full Documentation | 🐛 Report Issues

✨ Features

• Dual Hook API — Separate methods for WordPress core hooks and custom plugin hooks
• Auto-Prefixed Custom Hooks — Plugin-scoped hooks prevent naming collisions
• Fluent API — Chainable methods for clean registration
• One-Time Hooks — Actions that self-remove after first execution
• Hook Registry — Introspect all registered actions and filters

📋 Requirements

🚀 Installation

composer require KYNetCode/wpzylos-hooks

📖 Quick Start

use WPZylos\Framework\Hooks\HookManager;

$hooks = $app->make('hooks');

// WordPress core hooks (NEVER prefixed) — use wp* methods
$hooks->wpAction('init', [$this, 'initialize']);
$hooks->wpFilter('the_content', [$this, 'modifyContent']);

// Custom plugin hooks (ALWAYS prefixed) — use plain methods
$hooks->action('settings_saved', [$listener, 'onSettingsSaved']);
$hooks->filter('settings', [$this, 'filterSettings']);

// Fire & apply custom hooks
$hooks->doAction('settings_saved', $settings);
$filtered = $hooks->applyFilter('settings', $defaults);

🏗️ Core Concepts

The Dual API

HookManager provides two distinct APIs:

WordPress hooks (wp* methods) use the hook name exactly as provided — 'init', 'the_content', etc.

Custom plugin hooks (plain methods) automatically prefix the hook name via $context->hook() to prevent collisions between plugins.

WordPress Core Hooks

// Register actions on WordPress hooks
$hooks->wpAction('init', [$this, 'onInit']);
$hooks->wpAction('admin_menu', [$this, 'registerMenu'], 20);

// Register filters on WordPress hooks
$hooks->wpFilter('the_title', [$this, 'filterTitle']);
$hooks->wpFilter('body_class', [$this, 'addBodyClasses'], 10, 2);

// Remove hooks
$hooks->removeWpAction('init', [$this, 'onInit']);
$hooks->removeWpFilter('the_title', [$this, 'filterTitle']);

Custom Plugin Hooks

// Register listeners on your plugin's custom hooks
// If your plugin prefix is "myplugin", 'user_created' becomes 'myplugin_user_created'
$hooks->action('user_created', [$listener, 'onUserCreated']);
$hooks->filter('settings', [$this, 'filterSettings']);

// Fire a custom action
$hooks->doAction('user_created', $user);

// Apply a custom filter
$settings = $hooks->applyFilter('settings', $defaults);

// Remove custom hook listeners
$hooks->removeAction('user_created', [$listener, 'onUserCreated']);
$hooks->removeFilter('settings', [$this, 'filterSettings']);

One-Time Hooks

// Executes once then removes itself automatically
$hooks->once('init', function () {
    // Runs only on the first 'init' call
});

Fluent Chaining

$hooks
    ->wpAction('init', [$this, 'onInit'])
    ->wpAction('admin_menu', [$this, 'registerMenu'])
    ->wpFilter('the_content', [$this, 'filterContent']);

📦 Related Packages

📖 Documentation

For comprehensive documentation, tutorials, and API reference, visit wpzylos.com.

☕ Support the Project

• GitHub Sponsors
• PayPal Donate

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ by KYNetCode