Home

InitPHP Events — Wiki

Welcome to the official documentation for initphp/events — a tiny, zero-dependency event/hook library for PHP 5.6+.

It gives you two complementary APIs over the same core:

API	Use it when…
Events facade	You want a single, global hook point — register listeners from anywhere with Events::on(...), fire them with Events::trigger(...). WordPress-style hooks.
EventEmitter	You want a plain object you can new, inject, and pass around — node-style on/once/emit.

composer require initphp/events

use InitPHP\Events\Events;

Events::on('user.registered', function ($user) {
    mail($user['email'], 'Welcome', 'Thanks for signing up!');
});

Events::trigger('user.registered', ['email' => 'jane@example.com']);

That is the whole programming model. The rest of the wiki documents the details — argument passing, propagation control, once-listeners, simulate & debug modes, and the migration path from the deprecated initphp/event-emitter package.

Start here

• New to the package? Read Installation, then Quick Start.
• Picking an API? Compare the Events facade and the low-level EventEmitter.
• Coming from initphp/event-emitter? See the Migration Guide.
• Want the contract? The complete API Reference lists every method, constant, and exception.

Navigation

Getting Started

• Installation
• Quick Start

Core APIs

• Events facade
• EventEmitter
• Listeners & Priorities
• Stopping Propagation
• Simulate & Debug Mode

Practical

• Recipes
• Troubleshooting
• FAQ

Reference

• API Reference
• Migration Guide

At a glance — Events facade vs EventEmitter

Capability	Events facade	EventEmitter
Static / global	✅	—
Instantiable object	—	✅
Register listener (on)	✅	✅
One-shot listener (once)	✅	✅
Fire (trigger / emit)	✅	✅
Variadic arguments	✅ (varargs)	✅ (array)
Stop propagation by returning false	✅	—
Remove a single listener (off)	✅	✅
Remove all listeners	✅	✅
Priority-ordered dispatch	✅	✅
Simulate mode (skip execution)	✅	—
Debug timing	✅	—
Reset singleton between tests/jobs	✅	n/a
Implements EventEmitterInterface	—	✅

Pick the facade when you want a single, app-wide hook registry. Pick the emitter when you want a plain dependency you can hand to a service.

What changed in 2.0? Priorities are now actually honoured (1.x dispatched in registration order), one-shot listeners are correctly dropped after firing, and the high-level dispatcher gained once(), off(), removeAllListeners(), plus a reset() test hook on the facade. Full list: Migration Guide.

Package metadata

• License: MIT
• Minimum PHP: 5.6
• Packagist: initphp/events
• Source: github.com/InitPHP/Events
• Issues: github.com/InitPHP/Events/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Replaces: initphp/event-emitter (deprecated, see Migration Guide)

If something in this wiki is unclear, ambiguous, or wrong, please open an issue — documentation fixes are reviewed eagerly.