heybran / wp-hook-manager

v0.2.0 2026-08-15 13:24 UTC

Requires

• php: >=8.1

Requires (Dev)

• 10up/wp_mock: ^1.1

MIT

• Brandon Zhang

Published on Packagist.org on 2026-08-15 05:30 UTC

README

A lightweight WordPress hook manager with full support for PHP 8.1+ First-Class Callables, closures, arrays, and string callables.

The Problem

In PHP 8.1+, First-Class Callable Syntax (self::my_callback(...) or $this->my_callback(...)) creates a new Closure instance every time it is evaluated.

If you attempt to remove a filter registered with a First-Class Callable using standard WordPress remove_filter(), it will fail:

add_filter( 'the_title', $this->modify_title(...) );
// ❌ This does NOT work in WordPress core.
// Fails! The closure reference doesn't match.
remove_filter( 'the_title', $this->modify_title(...) );

The Solution

Heybran\HookManager tracks registered callbacks and compares First-Class Callables by reflection and object identity, allowing removeFilter() and removeAction() to work seamlessly.

Requirements

• PHP: >= 8.1
• WordPress: >= 5.9 (minimum version supporting PHP 8.1)

Installation

Install via Composer:

composer require heybran/wp-hook-manager

Usage

1. Adding and Removing Filters

use Heybran\HookManager\HookManager;

class TitleModifier
{
    public function register(): void
    {
        // Add filter using First-Class Callable.
        HookManager::addFilter('the_title', $this->append_version(...), 10);
    }

    public function unregister(): void
    {
        // Remove filter using First-Class Callable.
        HookManager::removeFilter('the_title', $this->append_version(...), 10);
    }

    public function append_version(string $title): string
    {
        return $title . ' v1.0';
    }
}

2. Adding and Removing Actions

addAction() and removeAction() are convenient aliases for addFilter() and removeFilter().

use Heybran\HookManager\HookManager;

// Register an action.
HookManager::addAction('wp_enqueue_scripts', Assets::enqueue_scripts(...));

// Remove the action.
HookManager::removeAction('wp_enqueue_scripts', Assets::enqueue_scripts(...));

Running Tests

This library includes a PHPUnit test suite powered by WP_Mock.

Run tests with Composer:

composer test

License

This project is open-source software licensed under the MIT License.