README

HookX is a next-generation, high-performance PHP hook and event system designed for modern applications. Built on PHP 8.3+, it leverages Attributes, Fibers, and Strong Typing to deliver a developer experience that is both powerful and elegant.

✨ Features

• Zero-Dependency: Pure PHP implementation, no external bloat.
• Async & Background Hooks: Run hooks in Fibers or push them to a Queue (Redis/Sync) using #[Async] and #[Background] attributes.
• Framework Integrations: Native support for Laravel and Symfony.
• Developer Experience: CLI tool (bin/hookx), REPL, and global helpers (hook(), filter()).
• Advanced Matching: Wildcards (user.*) and Regex (#^order\.(created|updated)$#) support.
• Safety: Immutable context, strict mode, and sandbox execution with time/memory limits.
• Performance: JIT compilation (experimental) and Zero-Copy dispatching.

📋 Requirements

• PHP 8.3 or higher

📦 Installation

Install the package via Composer:

composer require alizharb/hookx

Documentation

• Basics: Core concepts, HookManager, and Priorities.
• Async & Queue: Background processing and Fibers.
• Advanced Usage: Wildcards, Regex, JIT, and Sandbox.
• CLI Tooling: Using the hookx command-line tool.
• Integrations:
  • Laravel
  • Symfony
  • WordPress

Quick Start

Installation

composer require alizharb/hookx

Basic Usage

use AlizHarb\Hookx\Attributes\Hook;
use AlizHarb\Hookx\Context\HookContext;

class UserListener
{
    #[Hook('user.registered')]
    public function onRegister(HookContext $context): void
    {
        echo "User registered: " . $context->getArgument('email');
    }
}

// Register
$manager->registerObject(new UserListener());

// Dispatch
$manager->dispatch('user.registered', [
    'user' => ['name' => 'Alice', 'email' => 'alice@example.com']
]);

⚡ Async & Background Hooks

HookX supports both concurrent execution (Fibers) and true background processing (Queues).

use AlizHarb\Hookx\Async\AsyncHookDispatcher;

$dispatcher = new AsyncHookDispatcher($manager);

// Dispatches in background using Fibers
$dispatcher->dispatchAsync('email.send', [
    'to' => 'user@example.com',
    'subject' => 'Welcome!'
]);

For true background processing via Redis, check the Async Documentation.

📚 Documentation

For comprehensive documentation, check the docs/ directory:

• Introduction
• Installation
• Basic Usage
• Advanced Usage
• CLI Tooling
• Async & Background Hooks
• Filters
• Framework Integrations

🧪 Testing

Run the test suite:

composer test

📄 License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by Ali Harb