 |
VOOZH | about |
|
VOOZH | about |
The Events trait (src/Concerns/Events.php9-43) provides a lightweight observer pattern implementation that allows prompts to emit events and register callbacks during their lifecycle. This enables decoupled event handling where application code can react to prompt lifecycle events (such as key presses, state changes, or value updates) without modifying prompt internals.
The event system is used throughout the prompt base class to expose interaction points for custom behavior. For related documentation, see:
Sources: src/Concerns/Events.php9-43 src/Prompt.php20
The Events trait maintains an internal registry of event listeners organized by event name. When an event is emitted, all registered callbacks for that event are invoked in registration order with the provided data.
Title: Event System Flow
Sources: src/Concerns/Events.php9-43 src/Prompt.php20-333
The trait stores event listeners in a protected property:
The structure maps event names to arrays of closures: ['eventName' => [Closure, Closure, ...], ...]
This allows multiple listeners to be registered for the same event, executed in the order they were registered.
Sources: src/Concerns/Events.php16
Registers a callback to be invoked when the specified event is emitted. Multiple callbacks can be registered for the same event.
| Parameter | Type | Description |
|---|---|---|
$event | string | The event name to listen for |
$callback | Closure | The callback to invoke when event is emitted |
Implementation: Appends the callback to the listeners array for the specified event name (src/Concerns/Events.php21-24).
Sources: src/Concerns/Events.php21-24
Triggers an event, invoking all registered callbacks for that event in registration order. Each callback receives the provided data arguments.
| Parameter | Type | Description |
|---|---|---|
$event | string | The event name to emit |
...$data | mixed | Variable arguments passed to each callback |
Implementation: Iterates through listeners[$event] (if it exists) and invokes each callback with the provided data using spread syntax (src/Concerns/Events.php29-33).
Sources: src/Concerns/Events.php29-33
Removes all registered event listeners by resetting the listeners array to empty. This is called automatically in the prompt lifecycle cleanup.
Implementation: Sets $this->listeners = [] (src/Concerns/Events.php39-42).
Sources: src/Concerns/Events.php39-42
The Prompt base class uses the Events trait and emits the 'key' event during the input processing loop. This allows application code to react to every key press.
Title: Key Event Emission Flow
Sources: src/Prompt.php104-366
The 'key' event is emitted in the handleKeyPress() method (src/Prompt.php333):
This occurs for every key press during the input loop, before prompt-specific key handling logic executes.
Sources: src/Prompt.php327-366
Event listeners are automatically cleared in the finally block of Prompt::prompt() (src/Prompt.php159):
This ensures listeners don't persist beyond a single prompt invocation, preventing memory leaks and unintended behavior in subsequent prompts.
Sources: src/Prompt.php104-161
The callback receives the raw key string from Terminal::read(), including special keys like Key::UP, Key::ENTER, Key::CTRL_C, etc.
This allows inspection of prompt state transitions during interaction.
Sources: src/Prompt.php20-333
While the Events trait is event-name agnostic, the codebase currently uses:
| Event Name | Emitted By | Data Passed | Purpose |
|---|---|---|---|
'key' | Prompt::handleKeyPress() | string $key | Raw key press from terminal |
Individual prompt implementations may extend this by emitting custom events for:
'stateChanged', 'validated', 'error')'valueChanged', 'selectionChanged')'rendered', 'submitted')The event system is designed to support any event name without modification to the trait.
Sources: src/Concerns/Events.php9-43 src/Prompt.php333
The emit() method uses a null coalescing operator to handle events with no registered listeners:
If no listeners are registered for the event, the null coalescing operator (??) returns an empty array, and the foreach loop executes zero times. This makes emitting events with no listeners a no-op with no performance overhead.
Sources: src/Concerns/Events.php29-33
The implementation allows unlimited listeners per event. Each on() call appends to the array:
Listeners execute in registration order, and each receives the same data arguments passed to emit().
Sources: src/Concerns/Events.php21-24
Event listeners hold references to closures, which may capture variables from their defining scope. The clearListeners() method releases these references:
This is essential for preventing memory leaks, especially when prompts capture large objects or when running multiple prompts in succession.
Sources: src/Concerns/Events.php39-42
This diagram maps conceptual event system components to their concrete code implementations:
Title: Event System Code Entity Mapping
Sources: src/Concerns/Events.php9-43 src/Prompt.php20-333
When a prompt component uses the Events trait, application code can register listeners:
The event names and data signatures depend on what events the specific prompt implementation emits.
Before creating prompts in a non-interactive environment:
Sources: src/Concerns/Events.php21-33 src/Concerns/Interactivity.php19-38 src/Exceptions/NonInteractiveValidationException.php9-11
Both traits are designed to be mixed into prompt components. A typical prompt class structure:
Sources: src/Concerns/Events.php9-43 src/Concerns/Interactivity.php9-39
Individual prompt implementations decide which events to emit and how to handle non-interactive mode based on their specific requirements.
Refresh this wiki