Download the PHP package kristos80/hook without Composer

🪝 Hook

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

Usage

Basic Filter

Priority-based Execution

Lower priority numbers run first (default is 10):

Actions

Actions are filters that don't return values:

Multiple Arguments

Multiple Hook Names

Register the same callback to multiple hooks at once:

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:

Callable Types

The library accepts any valid PHP callable:

Enforcing Type Hints on Callbacks

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

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:

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:

Exceptions

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

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

Testing & Static Analysis

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

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

License

MIT

Author

Christos Athanasiadis - [email protected]