kristos80/hook

A lightweight, WordPress-style hooks system for PHP. Add actions and filters with priority support to create extensible, event-driven applications.

1.0.3 2025-10-03 13:16 UTC

Requires

• php: ^7.4 || ^8

Requires (Dev)

• infection/infection: ^0.31.2
• pestphp/pest: ^3.8

MIT

README

A lightweight, WordPress-style hooks system for PHP. Add actions and filters with priority support to create extensible, event-driven applications.

Features

• ✅ WordPress-inspired API (addAction, addFilter, doAction, applyFilter)
• ✅ Priority-based execution order
• ✅ Multiple callbacks per hook
• ✅ Multiple hook names in a single call
• ✅ Optimized sorting (sorted once, cached until modified)
• ✅ Type-safe with strict types
• ✅ Zero dependencies

Installation

composer require kristos80/hook

Usage

Basic Filter

use Kristos80\Hook\Hook;

$hook = new Hook();

// Add a filter
$hook->addFilter('format_title', function(string $title) {
    return strtoupper($title);
});

// Apply the filter
$result = $hook->applyFilter('format_title', 'hello world');
echo $result; // HELLO WORLD

Priority-based Execution

Lower priority numbers run first (default is 10):

$hook->addFilter('modify_value', function(int $value) {
    return $value * 2;
}, 10);

$hook->addFilter('modify_value', function(int $value) {
    return $value + 5;
}, 5); // Runs first

$result = $hook->applyFilter('modify_value', 10);
echo $result; // 30 (first: 10 + 5 = 15, then: 15 * 2 = 30)

Actions

Actions are filters that don't return values:

$hook->addAction('user_login', function() {
    error_log('User logged in');
});

$hook->doAction('user_login');

Multiple Arguments

$hook->addFilter('format_name', function(string $name, string $prefix) {
    return $prefix . ' ' . $name;
}, 10, 2); // Accept 2 arguments

$result = $hook->applyFilter('format_name', 'John', 'Mr.');
echo $result; // Mr. John

Multiple Hook Names

Register the same callback to multiple hooks at once:

$hook->addAction(['init', 'startup', 'boot'], function() {
    // Initialization logic
});

$hook->doAction('init');    // Executes callback
$hook->doAction('startup'); // Executes callback
$hook->doAction('boot');    // Executes callback

API Reference

addFilter(string|array $hookNames, callable $callback, int $priority = 10, int $acceptedArgs = 0): void

Add a filter callback to one or more hooks.

• $hookNames - Hook name(s) to attach to
• $callback - Callable to execute
• $priority - Execution priority (lower = earlier, default: 10)
• $acceptedArgs - Number of arguments the callback accepts (default: 0)

addAction(string|array $hookNames, callable $callback, int $priority = 10, int $acceptedArgs = 0): void

Alias for addFilter(). Use for hooks that don't return values.

applyFilter(string $hookName, ...$arg): mixed

Execute all callbacks registered to a filter hook.

• $hookName - Hook name to execute
• ...$arg - Arguments to pass to callbacks
• Returns the filtered value

doAction(string $hookName, ...$arg): void

Execute all callbacks registered to an action hook.

• $hookName - Hook name to execute
• ...$arg - Arguments to pass to callbacks

Testing

./vendor/bin/pest

License

MIT

Author

Christos Athanasiadis - [e-mail]