JBZoo Event

https://github.com/jbzoo/event
Admin
JBZoo Event is a lightweight PHP event manager library that provides a simple yet powerful pattern...
Tokens:15,985
Snippets:158
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Development Setup Command

Source: https://github.com/jbzoo/event/blob/master/CLAUDE.md

Use this command to install or update project dependencies via Composer.

```bash
make update
```

--------------------------------

### Install dependencies with make update

Source: https://github.com/jbzoo/event/blob/master/README.md

Use this command to install the necessary project dependencies.

```bash
make update  # Install dependencies
```

--------------------------------

### Install JBZoo Event via Composer

Source: https://github.com/jbzoo/event/blob/master/README.md

Use this command to install the library in your project.

```sh
composer require jbzoo/event
```

--------------------------------

### Quick Start with EventManager

Source: https://github.com/jbzoo/event/blob/master/README.md

Initialize the EventManager and trigger a simple event.

```php
use JBZoo\Event\EventManager;

$eManager = new EventManager();

// Simple
$eManager->on('create', function () {
    echo "Something action";
});

// Just do it!
$eManager->trigger('create');
```

--------------------------------

### EventManager::setDefault usage examples

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Examples showing how to set the default manager and retrieve it later, as well as how it behaves when guarded.

```php
// Basic call
EventManager::setDefault(new EventManager());

// later, anywhere in the app:
$m = EventManager::getDefault();
```

```php
// Replacing / guarding the default
EventManager::setDefault(new EventManager());
if (EventManager::getDefault() === null) {
    // never reached after setDefault
}
```

--------------------------------

### Basic event subscription

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example of subscribing to a single event and triggering it.

```php
// Basic call — single event
use JBZoo\Event\EventManager;

$e = new EventManager();
$e->on('user.create', function ($id) {
    echo "User created: $id";
});
$e->trigger('user.create', [42]);
```

--------------------------------

### getSummeryInfo listener check

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example demonstrating how to check if any listeners are registered.

```php
// Realistic: decide whether anything is wired up
$summary = $e->getSummeryInfo();
if (\count($summary) === 0) {
    // no listeners registered at all
}
```

--------------------------------

### Multiple event subscription and chaining

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example of subscribing to multiple events with explicit priority and using fluent chaining.

```php
// Multiple names + explicit priority + fluent chain
$e->on(['item.init', 'item.load'], $handler, EventManager::HIGH)
  ->on('item.*', $catchAllHandler);
```

--------------------------------

### EventManager::getDefault usage example

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Retrieving the global manager and triggering an event if it exists.

```php
// Basic call
$global = EventManager::getDefault(); // ?EventManager

if ($global !== null) {
    $global->trigger('app.boot');
}
```

--------------------------------

### getSummeryInfo basic usage

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example showing how the method returns an associative array of event names mapped to listener counts.

```php
// Basic call
$e->on('user.create', $cb1);
$e->on('user.create', $cb2);
$e->on('item.*', $cb3);

// $e->getSummeryInfo() === ['item.*' => 1, 'user.create' => 2]
```

--------------------------------

### Throwing ExceptionStop in a Listener

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

Example of throwing ExceptionStop within a listener to halt the dispatch process.

```php
use JBZoo\Event\ExceptionStop;

$e->on('user.create', function () {
    throw new ExceptionStop('Some reason'); // halts dispatch
});
```

--------------------------------

### Error handling for empty event names

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example of catching an exception when an invalid empty event name is provided.

```php
// Error handling: empty event name
try {
    $e->on('   ', static function (): void {});
} catch (\JBZoo\Event\Exception::class $e) {
    // $e->getMessage() === 'Event name is empty!'
}
```

--------------------------------

### cleanEventName error handling

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example showing how to handle the exception thrown when an event name results in an empty string.

```php
// Error handling
try {
    EventManager::cleanEventName(' .. ');
} catch (\JBZoo\Event\Exception::class $e) {
    // $e->getMessage() === 'Event name is empty!'
}
```

--------------------------------

### Catching JBZoo\Event\Exception

Source: https://github.com/jbzoo/event/blob/master/_autodocs/errors.md

Example of how to handle the exception thrown when an invalid event name is provided to the EventManager.

```php
use JBZoo\Event\EventManager;
use JBZoo\Event\Exception;

$e = new EventManager();
try {
    $e->trigger('   ');
} catch (Exception $e) {
    // $e->getMessage() === 'Event name is empty!'
    $e->getMessage();   // inherited from \RuntimeException
}
```

--------------------------------

### cleanEventName basic usage

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Example of normalizing a raw event name string.

```php
// Basic call
$name = EventManager::cleanEventName('USER.Create.'); // 'user.create'
```

--------------------------------

### Basic getList Usage

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates how listeners are retrieved and sorted by priority, with higher priority values appearing first in the returned array.

```php
// Basic call
$e->on('foo', $cb1, 200);
$e->on('foo', $cb2, 100);
// $e->getList('foo') === [$cb2, $cb1]   // highest priority first
```

--------------------------------

### Run tests and linters with make

Source: https://github.com/jbzoo/event/blob/master/README.md

Commands for executing the test suite and code style analysis.

```bash
make test      # Run PHPUnit tests
make test-all  # Run tests + code style checks
make codestyle # Run all linters
```

--------------------------------

### Catching ExceptionStop and general exceptions

Source: https://github.com/jbzoo/event/blob/master/_autodocs/errors.md

Demonstrates how to distinguish between ExceptionStop and other library exceptions when invoking listeners.

```php
use JBZoo\Event\Exception;
use JBZoo\Event\ExceptionStop;

try {
    $e->trigger('job', [$id]);
} catch (ExceptionStop $e) {
    // deliberate halt (only reachable if something other than
    // trigger() dispatch invokes listeners, since trigger() swallows it)
} catch (Exception $e) {
    // invalid event name
}
```

--------------------------------

### Basic usage of once

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates registering a listener that executes only on the first trigger.

```php
// Basic call
$e->once('app.init', function () {
    echo 'Initialized once';
});

$e->trigger('app.init'); // executes
$e->trigger('app.init'); // no-op: listener already removed
```

--------------------------------

### Basic trigger with arguments

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Shows how to pass arguments to listeners, noting that the event name is automatically appended as the final argument.

```php
// Basic call with arguments (event name arrives as the last argument)
$e->on('user.create', function ($id, $eventName) {
    echo "id=$id event=$eventName";
});
$count = $e->trigger('user.create', [42]);
// $count === 1
```

--------------------------------

### Use Namespace Wildcards

Source: https://github.com/jbzoo/event/blob/master/README.md

Listen to multiple related events using wildcard patterns.

```php
$eManager->on('item.*', function () {
    // item.init
    // item.save
    echo "Any actions with item";
});

$eManager->on('*.init', function () {
    // tag.init
    // item.init
    echo "Init any entity";
});

$eManager->on('*.save', function () {
    // tag.save
    // item.save
    echo "Saving any entity in system";
});

$eManager->on('*.save.after', function () {
    // tag.save.after
    // item.save.after
    echo "Any entity on after save";
});

$eManager->trigger('tag.init');
$eManager->trigger('tag.save.before');
$eManager->trigger('tag.save');
$eManager->trigger('tag.save.after');

$eManager->trigger('item.init');
$eManager->trigger('item.save.before');
$eManager->trigger('item.save');
$eManager->trigger('item.save.after');
```

--------------------------------

### Catching ExceptionStop and Exception

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/Exception.md

Shows how to catch the specific ExceptionStop subclass before the general Exception class to handle propagation control separately.

```php
use JBZoo\Event\Exception;
use JBZoo\Event\ExceptionStop;

try {
    $e->trigger('user.save');
} catch (ExceptionStop $e) {
    // listener deliberately halted propagation
} catch (Exception $e) {
    // invalid event name, etc.
}
```

--------------------------------

### Testing Commands

Source: https://github.com/jbzoo/event/blob/master/CLAUDE.md

Commands for running the test suite and code style checks.

```bash
make test           # Run PHPUnit tests
make test-all       # Run all tests and code style checks
make codestyle      # Run linters (PHPStan, Psalm, PHP-CS-Fixer, etc.)
```

--------------------------------

### Instantiating EventManager

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Creating a new instance of the EventManager using the implicit parameterless constructor.

```php
$eManager = new EventManager();
```

--------------------------------

### Importing JBZoo/Event classes

Source: https://github.com/jbzoo/event/blob/master/_autodocs/index.md

The library uses PSR-4 autoloading. Import these classes to access the EventManager, base Exception, and propagation control ExceptionStop.

```php
use JBZoo\Event\EventManager;
use JBZoo\Event\Exception;
use JBZoo\Event\ExceptionStop;
```

--------------------------------

### Individual QA Tool Commands

Source: https://github.com/jbzoo/event/blob/master/CLAUDE.md

Specific commands for running individual quality assurance tools via the JBZoo Toolbox.

```bash
make test-phpstan        # Static analysis
make test-psalm          # Psalm analysis
make test-phpcs          # Code style check
make test-phpcsfixer-fix # Auto-fix code style
make test-phpmd          # Mess detector
```

--------------------------------

### Wildcard Resolution in getList

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Shows how wildcard patterns match specific event names based on dot-separated parts, and how part count mismatches result in empty lists.

```php
// Wildcard resolution
$e->on('item.*', $handler);
if (\count($e->getList('item.save')) === 1) {
    $e->trigger('item.save');
}
// getList('item') === []    — part count mismatch
```

--------------------------------

### Catching ExceptionStop in Consumer Code

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

Demonstrates how to catch ExceptionStop when invoking listeners directly outside of the trigger() method.

```php
use JBZoo\Event\Exception;
use JBZoo\Event\ExceptionStop;

try {
    // some code that may invoke listeners directly
} catch (ExceptionStop $e) {
    // deliberate halt signal
} catch (Exception $e) {
    // empty-event-name failure, etc.
}
```

--------------------------------

### Creating Independent EventManager Instances

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates that each instance of EventManager maintains its own independent private listener registry.

```php
// Basic call
$local = new EventManager();   // private registry
$eManager = new EventManager(); // independent instance
```

--------------------------------

### Report Generation Commands

Source: https://github.com/jbzoo/event/blob/master/CLAUDE.md

Commands for generating coverage reports and uploading them to external services.

```bash
make report-all         # Generate coverage and analysis reports
make report-coveralls   # Upload coverage to Coveralls
```

--------------------------------

### Basic Usage: Halting After First Listener

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

Shows how throwing ExceptionStop in the first registered handler prevents subsequent handlers from executing.

```php
// Basic: halt after the first matched listener
use JBZoo\Event\EventManager;
use JBZoo\Event\ExceptionStop;

$e = new EventManager();
$e->on('search', function ($q) {
    // first registered handler answers the query
    echo "handler 1 got: $q";
    throw new ExceptionStop('handled');
});
$e->on('search', function ($q) {
    echo 'handler 2 — never runs';
});

$count = $e->trigger('search', ['php']); // $count === 1
```

--------------------------------

### on(array|string $eventNames, callable $callback, int $priority)

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Registers a callback to be executed when the specified event(s) are triggered. Supports wildcard event names and fluent method chaining.

```APIDOC
## on(array|string $eventNames, callable $callback, int $priority)

### Description
Registers a callback for one or more event names. The callback is stored with a priority, and the method returns the EventManager instance to allow for fluent chaining.

### Parameters
- **eventNames** (array|string) - Required - One event name or an array of event names. Supports dot-namespaces and '*' wildcards.
- **callback** (callable) - Required - The function or method to execute when the event is triggered.
- **priority** (int) - Optional (Default: 100) - Execution priority; higher values execute earlier.

### Returns
- **self** - The EventManager instance.

### Throws
- **JBZoo\Event\Exception** - Thrown if the event name is empty after cleaning.

### Example
```php
$e = new EventManager();
$e->on('user.create', function ($id) {
    echo "User created: $id";
});
```
```

--------------------------------

### Execute Events with Priority

Source: https://github.com/jbzoo/event/blob/master/README.md

Control the execution order of subscribers using priority constants or integers. The default priority is EventManager::MID.

```php
// Run it first
$eManager->on('create', function () {
    echo "Something high priority action";
}, EventManager::HIGH);

// Run it latest
$eManager->on('create', function () {
    echo "Something another action";
}, EventManager::LOW);

// Custom index
$eManager->on('create', function () {
    echo "Something action";
}, 42);

// Don't care...
$eManager->on('create', function () {
    echo "Something action";
});
```

--------------------------------

### Error handling for once

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Shows how to catch exceptions when providing an invalid event name to the once method.

```php
// Error handling is identical to on(); the cleaning failure is the same:
try {
    $e->once('', static function (): void {});
} catch (\JBZoo\Event\Exception::class $e) {
    // empty event name rejected
}
```

--------------------------------

### getList(string $eventName)

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Retrieves a list of listeners for a specific event, sorted by priority. Supports wildcard matching for event names.

```APIDOC
## getList(string $eventName)

### Description
Returns the list of listeners for an event. The list is returned as an array, and the list of events are sorted by their priority.

### Method
PHP Method

### Parameters
- **eventName** (string) - Required - Event name to resolve.

### Returns
- **array** (callable[]) - A list of callables sorted by priority descending. Returns an empty array if no listeners match.

### Throws
- **JBZoo\Event\Exception** - Thrown if the event name is empty after cleaning.

### Example
```php
$e->on('foo', $cb1, 200);
$e->on('foo', $cb2, 100);
$listeners = $e->getList('foo'); // Returns [$cb2, $cb1]
```
```

--------------------------------

### Advanced trigger with references and continue callback

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates using reference arguments for inter-listener communication and a continue callback to conditionally halt propagation.

```php
// Reference arguments + error-aware continue callback
$warnings = [];
$e->on('user.save', function ($user, &$warnings) {
    $warnings[] = $user . ' may be dirty';
});

$e->trigger('user.save', [$user, &$warnings], static function (): bool {
    if (\count($warnings) >= 10) {
        return false; // stop propagation, counts as success
    }
    return true;
});

// If a listener throws ExceptionStop, the executed count is returned:
$halted = $e->trigger('user.save', [$user]); // int, never raises
```

--------------------------------

### Register One-Time Listeners

Source: https://github.com/jbzoo/event/blob/master/README.md

Use the once method to register a listener that executes only once and then removes itself.

```php
$eManager->once('app.init', function () {
    echo "This will only run once, then auto-remove itself";
});

$eManager->trigger('app.init'); // Executes
$eManager->trigger('app.init'); // Does nothing - listener was removed
```

--------------------------------

### Pass Arguments to Listeners

Source: https://github.com/jbzoo/event/blob/master/README.md

Pass data to listeners as arguments, including passing by reference for communication back to the emitter.

```php
$eManager->on('create', function ($entityId) {
    echo "An entity with id ", $entityId, " just got created.\n";
});
$entityId = 5;
$eManager->trigger('create', [$entityId]);
```

```php
$eManager->on('create', function ($entityId, &$warnings) {
    echo "An entity with id ", $entityId, " just got created.\n";
    $warnings[] = "Something bad may or may not have happened.\n";
});
$warnings = [];
$eManager->trigger('create', [$entityId, &$warnings]);
```

--------------------------------

### getSummeryInfo method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The method signature for retrieving a summary of the event registry.

```php
public function getSummeryInfo(): array
```

--------------------------------

### EventManager::getDefault static method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The signature for retrieving the currently registered default manager.

```php
public static function getDefault(): ?self
```

--------------------------------

### Supported Callback Types

Source: https://github.com/jbzoo/event/blob/master/README.md

The library supports various standard PHP callable types for event listeners.

```php
$eManager->on('create', function(){ /* ... */ }); // Custom function
$eManager->on('create', 'myFunction');            // Custom function name
$eManager->on('create', ['myClass', 'myMethod']); // Static function
$eManager->on('create', [$object, 'Method']);     // Method of instance
```

--------------------------------

### Catching Exception in Consumer Code

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/Exception.md

Demonstrates catching the base Exception class when an invalid event name is triggered.

```php
use JBZoo\Event\EventManager;
use JBZoo\Event\Exception;

$e = new EventManager();

try {
    $e->trigger('   ');
} catch (Exception $e) {
    // $e->getMessage() === 'Event name is empty!'
    // $e instanceof \RuntimeException === true
}
```

--------------------------------

### once(string $eventName, callable $callback, int $priority = self::MID)

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Registers a callback to be executed only once for a specific event. The listener is automatically removed after the first invocation.

```APIDOC
## once(string $eventName, callable $callback, int $priority = self::MID)

### Description
Registers a callback to be executed only once for a specific event. The listener is automatically removed after the first invocation.

### Parameters
- **eventName** (string) - Required - A single event name.
- **callback** (callable) - Required - The function to be invoked at most once.
- **priority** (int) - Optional - Execution priority (default: 100).

### Return
- **self** - Returns the instance for fluent chaining.

### Throws
- **JBZoo\Event\Exception** - If the event name is empty after cleaning.
```

--------------------------------

### removeListener error handling

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Shows how to handle cases where the event or listener is not found.

```php
// Error handling / negative path
if (!$e->removeListener('bar', $cb)) {
    // event 'bar' unknown or callback not registered
}
```

--------------------------------

### EventManager::setDefault static method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The signature for registering a manager as the process-wide default.

```php
public static function setDefault(self $eManager): void
```

--------------------------------

### EventManager getList Method Signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The method signature for getList, which returns an array of callables sorted by priority.

```php
/**
 * Returns the list of listeners for an event.
 * The list is returned as an array, and the list of events are sorted by their priority.
 * @return callable[]
 */
public function getList(string $eventName): array
```

--------------------------------

### Error Handling: Swallowing ExceptionStop

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

Demonstrates that ExceptionStop is swallowed by the trigger() method and does not propagate to the caller.

```php
// Error handling: the caller of trigger() never sees ExceptionStop
try {
    $executed = $e->trigger('checkout', [$order]);
    // control reaches here even when a listener halted the chain
} catch (ExceptionStop $e) {
    // unreachable — ExceptionStop is swallowed inside trigger()
}
```

--------------------------------

### Advanced Event Manager Operations

Source: https://github.com/jbzoo/event/blob/master/README.md

Manage global instances, retrieve event summaries, and remove listeners.

```php
use JBZoo\Event\EventManager;

// Create a global event manager
EventManager::setDefault(new EventManager());
$globalManager = EventManager::getDefault();

// Get summary of registered events
$summary = $eManager->getSummeryInfo();
// Returns: ['user.create' => 3, 'user.update' => 1, ...]

// Remove specific listeners
$callback = function() { echo "test"; };
$eManager->on('test', $callback);
$eManager->removeListener('test', $callback);

// Remove all listeners for an event
$eManager->removeListeners('test');

// Remove ALL listeners
$eManager->removeListeners();
```

--------------------------------

### EventManager Dependency Graph

Source: https://github.com/jbzoo/event/blob/master/_autodocs/index.md

Visual representation of the dependency relationships between EventManager, Exception, and ExceptionStop classes.

```text
EventManager ──throws──▶ Exception         (empty event name, via cleanEventName)
EventManager ──catches─▶ ExceptionStop     (per-listener try/catch in callOneListener)
ExceptionStop ──extends─▶ Exception ──extends─▶ \RuntimeException (PHP built-in)
```

--------------------------------

### Catching Listener Exceptions with trigger()

Source: https://github.com/jbzoo/event/blob/master/_autodocs/errors.md

Wrap the trigger() call in a try-catch block to handle both library-specific exceptions and general Throwable errors originating from within listeners.

```php
try {
    $e->trigger('job', [$id]);
} catch (\JBZoo\Event\Exception $e) {
    // invalid event name (or ExceptionStop, which extends it)
} catch (\Throwable $e) {
    // failure from within a listener
}
```

--------------------------------

### Class Declaration of EventManager

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The class definition including priority constants and the internal listener storage structure.

```php
declare(strict_types=1);

namespace JBZoo\Event;

final class EventManager
{
    public const LOWEST  = 0;
    public const LOW     = 50;
    public const MID     = 100; // Default
    public const HIGH    = 500;
    public const HIGHEST = 1000;

    private static ?EventManager $defaultManager = null;

    /** The list of listeners. */
    private array $list = [];
```

--------------------------------

### EventManager::on method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The definition of the on method used to subscribe to events.

```php
/**
 * Subscribe to an event.
 * @param string|string[] $eventNames
 * @SuppressWarnings(PHPMD.ShortMethodName)
 */
public function on(array|string $eventNames, callable $callback, int $priority = self::MID): self
```

--------------------------------

### Advanced Usage: Priority-Based Validation

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

Uses priority to run a validation listener first, which throws ExceptionStop to prevent the main logic from executing if conditions are not met.

```php
// Advanced: verify-before-proceed using priority + ExceptionStop
$e = new EventManager();
$e->on('checkout', function ($order) {
    if (!\count($order['items'])) {
        throw new ExceptionStop('empty cart');
    }
}, EventManager::HIGHEST);          // runs first
$e->on('checkout', function ($order) {
    charge($order);                  // only reached when cart is non-empty
}, EventManager::LOW);

$executed = $e->trigger('checkout', [$order]);
// $executed === 0 for an empty cart, 1 otherwise — never throws
```

--------------------------------

### Control Event Propagation

Source: https://github.com/jbzoo/event/blob/master/README.md

Stop event propagation by throwing an ExceptionStop exception.

```php
use JBZoo\Event\ExceptionStop;

$eManager->on('create', function () {
    throw new ExceptionStop('Some reason'); // Special exception for JBZoo/Event
});

$eManager->trigger('create'); // Returns count of executed listeners
```

--------------------------------

### EventManager::once method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The signature for the once method, which registers a listener that is automatically removed after its first invocation.

```php
/**
 * Subscribe to an event only once.
 */
public function once(string $eventName, callable $callback, int $priority = self::MID): self
```

--------------------------------

### Validating Event Names with safeRegister

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/Exception.md

A realistic pattern for validating event names before registration by catching the Exception thrown by the EventManager.

```php
// Realistic pattern: validate an event name before registering
use JBZoo\Event\EventManager;
use JBZoo\Event\Exception;

function safeRegister(EventManager $m, string $name, $callback): bool
{
    try {
        $m->on($name, $callback);
        return true;
    } catch (Exception $e) {
        // name normalized to '' — rejected, nothing registered
        return false;
    }
}

$e = new EventManager();
safeRegister($e, 'user.create.', static function (): void {}); // true  → 'user.create'
safeRegister($e, ' . ', static function (): void {});          // false → would be '' anyway
```

--------------------------------

### trigger(string $eventName, array $arguments = [], ?callable $continueCallback = null)

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Emits an event, triggering all registered listeners in priority order. Supports passing arguments and a continue callback to control propagation.

```APIDOC
## trigger(string $eventName, array $arguments = [], ?callable $continueCallback = null)

### Description
Emits an event, triggering all registered listeners in priority order. The cleaned event name is automatically appended as the final argument to all listeners.

### Parameters
- **eventName** (string) - Required - The event name to emit.
- **arguments** (array) - Optional - Arguments passed to every matched listener (default: []).
- **continueCallback** (callable) - Optional - Callback invoked before each subsequent listener; returning false halts propagation.

### Return
- **int** - The number of listeners that executed successfully.

### Throws
- **JBZoo\Event\Exception** - If the event name is empty after cleaning.
```

--------------------------------

### getSummeryInfo

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Retrieves an associative array mapping each registered event name to the count of its listeners, sorted by event name.

```APIDOC
## getSummeryInfo

### Description
Returns a summary of the registry, mapping each registered event name to the count of its listeners.

### Method
public function getSummeryInfo(): array

### Return
- **array** - Associative array mapping each registered event name to the count of its listeners, sorted by key.
```

--------------------------------

### Priority Constants

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Constants used to define the execution order of event listeners. Higher values are executed earlier.

```APIDOC
## Priority Constants

### Description
Listeners are sorted by priority in descending order. The default priority is `EventManager::MID` (100).

### Constants
- **EventManager::LOWEST** (0) - Lowest built-in priority
- **EventManager::LOW** (50) - Low priority
- **EventManager::MID** (100) - Default priority
- **EventManager::HIGH** (500) - High priority
- **EventManager::HIGHEST** (1000) - Highest built-in priority
```

--------------------------------

### isContainPart internal method

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Internal method implementing single-part wildcard matching for event names.

```php
private static function isContainPart(array $eNameParts, array $ePaths): bool
{
    // Length of parts is equals
    if (\count($eNameParts) !== \count($ePaths)) {
        return false;
    }

    $isFound = true;

    foreach ($eNameParts as $pos => $eNamePart) {
        if ($eNamePart !== '*' && \array_key_exists($pos, $ePaths) && $ePaths[$pos] !== $eNamePart) {
            $isFound = false;
            break;
        }
    }

    return $isFound;
}
```

--------------------------------

### callListenersWithCallback internal method

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Internal method that iterates through listeners in priority order, supporting early termination via callbacks or ExceptionStop.

```php
private static function callListenersWithCallback(
    array $listeners,
    array $arguments = [],
    ?callable $continueCallback = null,
): int {
    $counter     = \count($listeners);
    $execCounter = 0;

    foreach ($listeners as $listener) {
        $counter--;

        $result = self::callOneListener($listener, $arguments);
        if (!$result) {
            return $execCounter;
        }

        $execCounter++;

        if ($continueCallback !== null && $counter > 0 && !$continueCallback()) {
            break;
        }
    }

    return $execCounter;
}
```

--------------------------------

### ExceptionStop Class Declaration

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

The class definition for ExceptionStop, which is final and inherits from the library's base Exception class.

```php
declare(strict_types=1);

namespace JBZoo\Event;

/**
 * @psalm-suppress UnusedClass
 */
final class ExceptionStop extends Exception
{
}
```

--------------------------------

### removeListeners basic usage

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates clearing listeners for a specific event or clearing the entire registry.

```php
// Basic calls
$e->removeListeners('foo'); // drop all listeners of 'foo'
$e->removeListeners();      // drop every listener of every event
```

--------------------------------

### cleanEventName method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The static method signature for normalizing event names.

```php
/**
 * Prepare event name before using.
 */
public static function cleanEventName(string $eventName): string
```

--------------------------------

### EventManager Constructor

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The EventManager class uses an implicit public parameterless constructor to create an instance with an independent listener registry.

```APIDOC
## Constructor

### Description
Creates a new instance of the EventManager. Each instance maintains its own independent private listener map.

### Signature
`new JBZoo\Event\EventManager()`

### Parameters
- None

### Example
```php
use JBZoo\Event\EventManager;

$eManager = new EventManager();
```
```

--------------------------------

### removeListener basic usage

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Demonstrates removing a specific callable listener from an event.

```php
// Basic call
$cb = function () { echo 'hi'; };
$e->on('foo', $cb);
$removed = $e->removeListener('foo', $cb); // true
$again   = $e->removeListener('foo', $cb); // false — already gone
```

--------------------------------

### EventManager::getDefault

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Retrieves the currently registered default EventManager instance.

```APIDOC
## static ?EventManager getDefault()

### Description
Returns the manager previously registered with setDefault(), or null if none was set.

### Returns
- **?EventManager** - The default manager instance or null.

### Usage
```php
$global = EventManager::getDefault();
if ($global !== null) {
    $global->trigger('app.boot');
}
```
```

--------------------------------

### Throwing ExceptionStop

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

To halt the dispatch chain, throw an instance of ExceptionStop within your event listener.

```APIDOC
## Throwing ExceptionStop

### Description
Throwing this exception inside a listener callback signals the EventManager to stop executing any remaining listeners for the current event.

### Usage
```php
use JBZoo\Event\ExceptionStop;

$e->on('event.name', function () {
    // Logic to determine if chain should stop
    throw new ExceptionStop('Reason for stopping');
});
```
```

--------------------------------

### Error Hierarchy Diagram

Source: https://github.com/jbzoo/event/blob/master/_autodocs/errors.md

Visual representation of the exception class inheritance structure within the JBZoo\Event namespace.

```text
\RuntimeException                      (PHP built-in)
  └── JBZoo\Event\Exception            (src/Exception.php:19) — base library exception
        └── JBZoo\Event\ExceptionStop  (src/ExceptionStop.php:22, final) — propagation stop signal
```

--------------------------------

### removeListeners error handling

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Shows how the method handles invalid event names that clean to an empty string.

```php
// Error handling — an explicit empty-ish name is rejected
try {
    $e->removeListeners('   ');
} catch (\JBZoo\Event\Exception::class $e) {
    // use removeListeners(null) or removeListeners() instead
}
```

--------------------------------

### Exception Class Declaration

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/Exception.md

The Exception class is an empty class that extends \RuntimeException, serving as a namespace-specific marker for library exceptions.

```php
declare(strict_types=1);

namespace JBZoo\Event;

class Exception extends \RuntimeException
{
}
```

--------------------------------

### EventManager::trigger method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The signature for the trigger method, used to emit events and execute registered listeners.

```php
public function trigger(string $eventName, array $arguments = [], ?callable $continueCallback = null): int
```

--------------------------------

### EventManager::callOneListener Catch Site

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/ExceptionStop.md

The internal method where the EventManager catches ExceptionStop to halt the dispatch chain.

```php
private static function callOneListener(callable $listener, array $arguments = []): bool
{
    try {
        $listener(...$arguments);
    } catch (ExceptionStop) {
        return false;
    }

    return true;
}
```

--------------------------------

### EventManager::setDefault

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Registers a specific EventManager instance as the process-wide default manager.

```APIDOC
## static void setDefault(EventManager $eManager)

### Description
Registers a manager as the process-wide default, stored in a static property. Only one default exists per process.

### Parameters
- **eManager** (EventManager) - Required - The manager to install as global default.

### Usage
```php
EventManager::setDefault(new EventManager());
```
```

--------------------------------

### removeListeners(?string $eventName = null): void

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Removes all listeners. With a non-null, non-empty eventName, only that event's listeners are removed; with null (the default), the whole registry is emptied.

```APIDOC
## removeListeners(?string $eventName = null): void

### Description
Removes all listeners. With a non-null, non-empty $eventName, only that event's listeners are removed; with null (the default) or an event name that cleans to '', the whole registry is emptied.

### Parameters
- **eventName** (?string) - Optional - Event whose listeners to remove. null clears every event.

### Returns
- **void**

### Throws
- **JBZoo\Event\Exception** - if a non-null $eventName is provided and cleans to an empty string.
```

--------------------------------

### EventManager::cleanEventName Method Implementation

Source: https://github.com/jbzoo/event/blob/master/_autodocs/errors.md

The internal method responsible for normalizing event names and throwing a JBZoo\Event\Exception when the resulting name is empty.

```php
public static function cleanEventName(string $eventName): string
{
    $eventName = \strtolower($eventName);
    $eventName = \str_replace('..', '.', $eventName);
    $eventName = \trim($eventName, '.');
    $eventName = \trim($eventName);

    if ($eventName === '') {
        throw new Exception('Event name is empty!');
    }

    return $eventName;
}
```

--------------------------------

### removeListener method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The method signature for removing a specific listener from an event.

```php
public function removeListener(string $eventName, ?callable $listener = null): bool
```

--------------------------------

### removeListeners method signature

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

The method signature for removing all listeners or listeners for a specific event.

```php
public function removeListeners(?string $eventName = null): void
```

--------------------------------

### cleanEventName

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Normalizes an event name by lowercasing, collapsing double dots, and trimming whitespace and dots.

```APIDOC
## cleanEventName

### Description
Prepares and normalizes an event name before use.

### Method
public static function cleanEventName(string $eventName): string

### Parameters
- **eventName** (string) - Required - Raw event name to normalize.

### Return
- **string** - The normalized event name.

### Throws
- **JBZoo\Event\Exception** - Thrown when the resulting normalized name is an empty string.
```

--------------------------------

### removeListener(string $eventName, ?callable $listener = null): bool

Source: https://github.com/jbzoo/event/blob/master/_autodocs/api-reference/EventManager.md

Removes a specific listener from a specific event. The listener is located by identity among the stored triples; only the first matching entry is removed.

```APIDOC
## removeListener(string $eventName, ?callable $listener = null): bool

### Description
Removes a specific listener from a specific event. The listener is located by identity (===) among the stored [priority, callback, eventName] triples; only the first matching entry is removed. If the event is unknown or the listener is absent, nothing is removed.

### Parameters
- **eventName** (string) - Required - Event from which to remove.
- **listener** (?callable) - Optional - The exact callable to remove.

### Returns
- **bool** - true if a listener was removed, false if the event does not exist or the listener was not found.

### Throws
- **JBZoo\Event\Exception** - if the event name is empty after cleaning.
```
Tokens:
Raw