kristos80/hook

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

2.11.0 2026-08-13 10:47 UTC

Requires

• php: ^8.2

Requires (Dev)

• pestphp/pest: ^3.8
• phpstan/phpstan: ^2.0

MIT

Published on Packagist.org on 2026-08-13 10:47 UTC

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 (with per-hook priority support)
• ✅ Multiple callbacks per hook
• ✅ Multiple hook names in a single call
• ✅ Supports all PHP callable types (closures, functions, static methods, instance methods, invokables)
• ✅ Optimized sorting (sorted once, cached until modified)
• ✅ Type-safe with strict types
• ✅ Interface-based design (HookInterface)
• ✅ Optional type hint enforcement for callbacks
• ✅ Priority introspection (getMinPriority, getMaxPriority)
• ✅ Built-in FIRST and LAST priority constants
• ✅ Zero dependencies

Requirements

• PHP ^8.2

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;
});

$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

Per-Hook Priority

When registering multiple hook names, you can assign a different priority to each hook by passing an array of priorities. Each hook name is mapped to the priority at the same index, with a fallback to the first priority if the index doesn't exist:

// Different priority per hook: 'init' gets priority 1, 'save' gets priority 20
$hook->addFilter(['init', 'save'], function(string $data) {
    return $data;
}, [1, 20]);

// Partial array: 'init' gets priority 5, 'save' and 'cleanup' fall back to index 0 (priority 5)
$hook->addAction(['init', 'save', 'cleanup'], function() {
    // ...
}, [5]);

// Single int still works as before — all hooks get the same priority
$hook->addFilter(['init', 'save'], $callback, 10);

Callable Types

The library accepts any valid PHP callable:

// Closure
$hook->addFilter('my_filter', function(string $value) {
    return strtoupper($value);
});

// Function name (string)
$hook->addFilter('my_filter', 'strtoupper');

// Static method (string)
$hook->addFilter('my_filter', 'MyClass::transform');

// Static method (array)
$hook->addFilter('my_filter', [MyClass::class, 'transform']);

// Instance method (array)
$formatter = new TextFormatter();
$hook->addFilter('my_filter', [$formatter, 'format']);

// Invokable object
class MyTransformer {
    public function __invoke(string $value): string {
        return strtoupper($value);
    }
}
$hook->addFilter('my_filter', new MyTransformer());

Enforcing Type Hints on Callbacks

Use the requireTypedParameters named argument to enforce that all callback parameters have type hints:

$hook->addFilter('process_data', function(array $data): array {
    return array_map('strtoupper', $data);
});

// This will work - callback has typed parameters
$result = $hook->applyFilter('process_data', ['hello'], requireTypedParameters: true);

// Register an untyped callback
$hook->addFilter('other_filter', function($value) {
    return $value;
});

// This will throw MissingTypeHintException
$hook->applyFilter('other_filter', 'test', requireTypedParameters: true);

The requireTypedParameters argument is stripped and never passed to callbacks. This feature helps enforce stricter contracts when the hook owner wants to ensure all registered callbacks follow type safety conventions.

Priority Constants

Use HookInterface::FIRST and HookInterface::LAST to guarantee a callback runs before or after all others:

use Kristos80\Hook\HookInterface;

// Guaranteed to run before any other callback
$hook->addFilter('process', function(string $data) {
    return trim($data);
}, HookInterface::FIRST);

// Guaranteed to run after any other callback
$hook->addFilter('process', function(string $data) {
    return htmlspecialchars($data);
}, HookInterface::LAST);

The constants are also accessible via Hook::FIRST and Hook::LAST. Multiple callbacks at the same constant priority follow FIFO order, consistent with the rest of the priority system.

Priority Introspection

Query the lowest or highest registered priority for a given hook:

$hook->addFilter('my_filter', function(string $v) { return $v; }, 5);
$hook->addFilter('my_filter', function(string $v) { return $v; }, 20);
$hook->addFilter('my_filter', function(string $v) { return $v; }, 12);

$hook->getMinPriority('my_filter'); // 5
$hook->getMaxPriority('my_filter'); // 20

// Returns null for hooks with no registered callbacks
$hook->getMinPriority('nonexistent'); // null
$hook->getMaxPriority('nonexistent'); // null

Exceptions

Every exception the library throws extends the abstract HookException, so a single catch (HookException $e) will trap any hook-related failure:

use Kristos80\Hook\HookException;
use Kristos80\Hook\CircularDependencyException;
use Kristos80\Hook\InvalidPriorityException;
use Kristos80\Hook\MissingTypeHintException;

Exception	Thrown by	When
CircularDependencyException	applyFilter() / doAction()	A hook is dispatched while it is already on the running stack (a callback for X re-triggers X).
InvalidPriorityException	addFilter() / addAction()	A resolved priority is not an integer.
MissingTypeHintException	applyFilter() / doAction()	requireTypedParameters: true was passed and a registered callback has an untyped parameter.
HookException (abstract base)	—	Never thrown directly; use it as a catch-all supertype.

API Reference

addFilter(string|array $hookNames, callable $callback, int|array $priority = 10): 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). Pass an array to assign a different priority per hook name (falls back to index 0 for missing indices)
• Throws InvalidPriorityException if a resolved priority is not an integer

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

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

Note: The $acceptedArgs parameter exists for backwards compatibility but is deprecated and no longer used. PHP natively handles argument count validation.

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

Execute all callbacks registered to a filter hook.

• $hookName - Hook name to execute
• ...$arg - Arguments to pass to callbacks
• requireTypedParameters: bool - Named argument to enforce type hints on callbacks (default: false)
• Returns the filtered value
• Throws CircularDependencyException if the hook is already on the running stack
• Throws MissingTypeHintException if requireTypedParameters is true and a callback has untyped parameters

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

Execute all callbacks registered to an action hook.

• $hookName - Hook name to execute
• ...$arg - Arguments to pass to callbacks
• requireTypedParameters: bool - Named argument to enforce type hints on callbacks (default: false)
• Throws CircularDependencyException if the hook is already on the running stack
• Throws MissingTypeHintException if requireTypedParameters is true and a callback has untyped parameters

HookInterface::FIRST / HookInterface::LAST

Priority constants for guaranteed earliest (PHP_INT_MIN) and latest (PHP_INT_MAX) execution. Also accessible as Hook::FIRST / Hook::LAST.

getMinPriority(string $hookName): ?int

Get the lowest registered priority for a hook.

• $hookName - Hook name to query
• Returns the minimum priority value, or null if the hook has no registered callbacks

getMaxPriority(string $hookName): ?int

Get the highest registered priority for a hook.

• $hookName - Hook name to query
• Returns the maximum priority value, or null if the hook has no registered callbacks

Interface-based Design

The Hook class implements HookInterface, providing several benefits:

• Dependency Injection - Type-hint against HookInterface in your constructors and methods, making dependencies explicit and swappable
• Testability - Easily mock or stub the hook system in unit tests by creating test doubles that implement HookInterface
• Decoupling - Your code depends on an abstraction rather than a concrete implementation, following the Dependency Inversion Principle
• Extensibility - Create alternative implementations (e.g., a NullHook for disabled hooks, or a LoggingHook decorator) without modifying existing code
• Contract Guarantee - The interface defines a clear API contract, ensuring any implementation provides the expected methods

// Type-hint against the interface for better architecture
class UserService {
    public function __construct(
        private HookInterface $hooks
    ) {}

    public function createUser(array $data): User {
        $data = $this->hooks->applyFilter('user_data', $data);
        // ...
    }
}

Testing & Static Analysis

The project is held to three gates that all pass at 100%:

# Unit tests
./vendor/bin/pest

# Line coverage (must be 100%)
herd coverage ./vendor/bin/pest --coverage

# Mutation testing (must be 100%)
herd coverage ./vendor/bin/pest --mutate --parallel --everything --covered-only

# Static analysis at PHPStan level max
./vendor/bin/phpstan analyse

Substitute herd coverage with your own coverage driver (Xdebug, PCOV) if you are not on Laravel Herd.

License

MIT

Author

Christos Athanasiadis - [e-mail]