README.md

InitPHP Events — Documentation

This is the long-form documentation for initphp/events. The package README covers the same material at a glance; these chapters go into the details.

If you are new to the package, read in order:

1. Getting started — install it, run the smallest possible example, learn the three classes you will touch.
2. The Events facade — the static application-wide dispatcher, when to use it, when not to.
3. Using EventEmitter directly — the low-level primitive: instantiate, on / once / emit, no global state.
4. Priorities and ordering — the full contract for what runs when, including how once() interacts with the priority queue and the case-insensitive event-name rule.
5. Once-listeners, removal, and cleanup — once, off, removeAllListeners, clearOnceListeners, and the guarantees each one gives you.
6. Debug and simulate modes — opt-in instrumentation for dry-runs and timing measurements.
7. Migrating from initphp/event-emitter — the BC alias, the emit() bug fix, the v2.0 priority-sort fix, what to change and what to leave alone.
8. Recipes — concrete patterns: plugin systems, request lifecycle hooks, WordPress-style action / filter hooks, testing strategies.
9. API reference — every public method, every exception, every constant.

Spotted a gap or something that doesn't match what the code actually does? Please open an issue — the documentation tries to match the code character for character, and divergence is a bug we want to hear about.