Event Inspector

The Event Inspector is a development utility command that introspects the application's event system, displaying all registered events and their associated listeners. This tool allows developers to understand which events are available in the application and which listeners are bound to handle them, making it easier to debug event-driven workflows and verify event registration.

For information about generating event and listener classes, see Event and Listener Generation. For information about the file watching utility, see File Watching and Hot Reload.

Command Overview

The Event Inspector is implemented by the EventListCommand class, which provides the event:list console command. Unlike the code generation commands in this package, the Event Inspector is a runtime introspection tool that queries the live application state rather than generating files.

Property	Value
Command Name	event:list
Command Class	EventListCommand
Base Class	Hyperf\Command\Command
Primary Interface	Hypervel\Event\Contracts\Dispatcher
Output Format	Table (Events + Listeners)

Sources: src/Commands/EventListCommand.php18-23

Command Structure

Command Definition

The EventListCommand extends HyperfCommand (not GeneratorCommand) because it performs runtime introspection rather than file generation. The command is registered with the name event:list and accepts two optional filter parameters.

php bin/hyperf.php event:list [--event=PATTERN] [--listener=PATTERN]

Available Options:

Option	Short	Type	Description
--event	-e	Optional string	Filter events by event name (substring match)
--listener	-l	Optional string	Filter listeners by listener name (substring match)

Sources: src/Commands/EventListCommand.php35-40

Command Execution Flow

Diagram: Event List Command Execution

Sources: src/Commands/EventListCommand.php25-33 src/Commands/EventListCommand.php95-107

Event Dispatcher Integration

Dispatcher Contract Requirement

The Event Inspector requires the event dispatcher to implement the Hypervel\Event\Contracts\Dispatcher interface (aliased as EventDispatcherContract). This contract extends the PSR-14 EventDispatcherInterface and adds the getRawListeners() method that provides access to the raw event-to-listener mapping.

Diagram: Event Dispatcher Query Mechanism

Sources: src/Commands/EventListCommand.php30-31 src/Commands/EventListCommand.php42-47

Listener Data Structure

The command expects listeners to be instances of ListenerData, which contains information about the listener callable and its registration metadata. The getRawListeners() method returns an array where keys are event names and values are arrays of ListenerData objects.

Sources: src/Commands/EventListCommand.php10 src/Commands/EventListCommand.php49-52 src/Commands/EventListCommand.php58-64

Data Processing Pipeline

Event and Listener Filtering

The handleData() method processes the raw event-listener mapping through a multi-stage filtering and formatting pipeline.

Diagram: Data Processing Pipeline

Sources: src/Commands/EventListCommand.php42-93

Filtering Logic

Event Name Filtering

When the --event option is provided, the command performs a substring match against event names using str_contains():

// Example: --event=User
// Matches: UserCreated, UserUpdated, UserDeleted
// Does not match: AccountCreated, OrderPlaced

Implementation: src/Commands/EventListCommand.php54-56

Listener Name Filtering

When the --listener option is provided, the command filters listeners after extracting their string representation:

// Example: --listener=SendEmail
// Matches: App\Listeners\SendEmailNotification
// Does not match: App\Listeners\LogUserActivity

Implementation: src/Commands/EventListCommand.php58-64

Sources: src/Commands/EventListCommand.php42-65

Listener Formatting

Listener Callable Types

The command handles multiple types of listener callables and formats them into human-readable strings:

Listener Type	Format	Example Output
Array callable [class, method]	ClassName::methodName	App\Listeners\UserEventSubscriber::handleUserCreated
String callable	Raw string	App\Listeners\SendWelcomeEmail
Closure	Literal 'Closure'	Closure
Unknown type	Literal 'Unknown listener'	Unknown listener

Diagram: Listener Formatting Logic

Sources: src/Commands/EventListCommand.php66-86

Array Callable Processing

For array callables in the format [object, method], the command extracts the class name and method name:

1. If the first element is a string (static method), use it directly as the class name
2. If the first element is an object instance, use get_class() to extract the class name
3. Concatenate with :: separator to create ClassName::methodName format

Sources: src/Commands/EventListCommand.php68-74

Output Formatting

Table Structure

The command renders output as a table with two columns using Symfony's Table helper:

Column	Content
Events	Event class name or event identifier
Listeners	Newline-separated list of listener callables

Each event-listener group is separated by a TableSeparator for visual clarity.

Sources: src/Commands/EventListCommand.php95-107

Table Rendering Process

Diagram: Table Rendering Process

Sources: src/Commands/EventListCommand.php95-107

Multiple Listeners Display

When an event has multiple listeners, they are displayed on separate lines within the same table cell, separated by newline characters (PHP_EOL). This creates a vertical list within the "Listeners" column:

+-------------------+----------------------------------+
| Events | Listeners |
+-------------------+----------------------------------+
| UserCreated | App\Listeners\SendWelcomeEmail |
| | App\Listeners\LogUserActivity |
| | App\Listeners\UpdateStatistics |
+-------------------+----------------------------------+

Sources: src/Commands/EventListCommand.php99

Usage Examples

List All Events

Display all registered events and their listeners:

Filter by Event Name

Display only events matching a specific pattern:

Filter by Listener Name

Display only events with listeners matching a specific pattern:

Combined Filtering

Apply both event and listener filters simultaneously:

This would show only events containing "User" that have at least one listener containing "Send".

Sources: src/Commands/EventListCommand.php38-39

Integration with Event System

Relationship to Event Generation

While the Event Inspector displays registered events and listeners, the actual event classes are typically generated using the make:event command (see Event and Listener Generation). The standard event stub includes the Dispatchable trait:

Sources: src/Generator/stubs/event.stub1-20

Event Registration Flow

Diagram: Event System Overview

Sources: src/Commands/EventListCommand.php1-108

Error Handling

Non-Compatible Dispatcher

If the resolved event dispatcher does not implement the Dispatcher contract (i.e., it only implements the basic PSR-14 EventDispatcherInterface), the command returns an empty data array and displays an empty table. This provides graceful degradation rather than throwing an exception.

Sources: src/Commands/EventListCommand.php45-47

Invalid Listener Data

The command filters out listeners that are not instances of ListenerData, silently skipping them during processing. This ensures that only properly structured listener data is displayed.

Sources: src/Commands/EventListCommand.php58-60

Implementation Details

Constructor Dependency Injection

The command receives the ContainerInterface through constructor injection, which it uses to resolve the event dispatcher at runtime:

Sources: src/Commands/EventListCommand.php20-23

Output Interface

The show() method accepts an OutputInterface parameter (from Symfony Console), allowing for flexible output handling and potential testing with mock output interfaces:

Sources: src/Commands/EventListCommand.php95

Data Structure

The internal data structure groups listeners by event name:

Sources: src/Commands/EventListCommand.php88-90