Event and Listener Generation

Purpose and Scope

This document explains the event and listener code generation commands in the hypervel/devtool package. These generators create the foundation for event-driven architecture in Hypervel applications by scaffolding event classes and their corresponding listener classes.

• Event Generation (make:event): Creates event classes that represent application occurrences
• Listener Generation (make:listener): Creates listener classes that respond to specific events

For information about model observer generation (which responds to model lifecycle events), see Observer Generation. For details on the event inspection tool, see Event Inspector.

---

Event Generation Overview

The make:event command generates event classes that represent specific occurrences in the application. Events serve as notification objects that are dispatched through the event dispatcher and handled by registered listeners.

Command Registration

Both event and listener generators are registered through the ConfigProvider as part of the Event System category:

Sources: src/Commands/EventListCommand.php1-109 Diagram 3 from high-level architecture

---

Event Class Structure

Event Stub Template

The event stub template defines the structure of generated event classes:

Placeholder	Purpose	Example Replacement
%NAMESPACE%	Event class namespace	App\Events
%CLASS%	Event class name	OrderShipped

Generated Event Anatomy

Events generated by the make:event command follow this structure:

Key Components:

1. Dispatchable Trait: Provides the dispatch() static method for event triggering src/Generator/stubs/event.stub7
2. Constructor: Intended for accepting event payload data src/Generator/stubs/event.stub16-19
3. Public Properties/Methods: Can be added to carry event context data

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

Event Template Details

The complete event stub template structure:

Template Features:

• Strict Typing: Declares strict_types=1 for type safety src/Generator/stubs/event.stub3
• Dispatchable Pattern: Includes the Dispatchable trait enabling static dispatch methods src/Generator/stubs/event.stub7-11
• Empty Constructor: Provides placeholder for event initialization logic src/Generator/stubs/event.stub16-19

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

---

Listener Generation Overview

The make:listener command generates listener classes that respond to dispatched events. Listeners contain the business logic executed when their associated event occurs.

Listener Class Responsibilities

Listener Characteristics:

1. Handler Method: Contains a handle() method that receives the event instance
2. Type Hinting: The handle() method is type-hinted with the specific event class
3. Dependency Injection: Can inject dependencies through the constructor
4. Synchronous/Queued: Can implement queue interfaces for async processing

Sources: Inferred from system architecture, src/Commands/EventListCommand.php49-93

---

Event-Listener Integration

Registration and Dispatch Flow

The relationship between events, listeners, and the event dispatcher:

Flow Stages:

1. Dispatch: Event is dispatched via the Dispatchable trait's static method
2. Lookup: Dispatcher retrieves registered listeners for the event class src/Commands/EventListCommand.php49
3. Resolution: Container resolves listener instances
4. Execution: Each listener's handle() method is invoked with the event instance
5. Return: Control returns to the calling code

Sources: src/Commands/EventListCommand.php25-93 src/Generator/stubs/event.stub7

Listener Data Structure

The event dispatcher maintains listener metadata in ListenerData objects:

Listener Representation Types:

Format	Structure	Display	Line Reference
Array	[object/class, method]	ClassName::method	src/Commands/EventListCommand.php68-75
String	'ClassName'	ClassName	src/Commands/EventListCommand.php77-79
Closure	Closure instance	'Closure'	src/Commands/EventListCommand.php81-83

Sources: src/Commands/EventListCommand.php58-86

---

Event Dispatcher Integration

Dispatcher Contract Requirements

The event system integrates with Hypervel's event dispatcher contract:

Contract Methods:

• getRawListeners(): Returns all registered event-listener mappings src/Commands/EventListCommand.php49
• PSR-14 Compliance: Implements standard EventDispatcherInterface src/Commands/EventListCommand.php12-31
• Hypervel Extension: Extends PSR-14 with framework-specific functionality src/Commands/EventListCommand.php9

Sources: src/Commands/EventListCommand.php9-49

---

Event and Listener Code Generation

Generator Command Pattern

Both event and listener generators follow the standard generator command pattern:

Generation Steps:

1. Name Resolution: Parse the provided class name and determine namespace
2. Stub Loading: Load the appropriate stub template (event.stub or listener.stub)
3. Placeholder Substitution: Replace %NAMESPACE% and %CLASS% with resolved values
4. File Writing: Write the generated class to the appropriate directory

Sources: src/Generator/stubs/event.stub1-21 Diagram 4 from high-level architecture

Default Output Directories

Generator	Default Directory	Namespace
make:event	app/Events/	App\Events
make:listener	app/Listeners/	App\Listeners

Sources: Standard Laravel/Hypervel conventions, src/Generator/stubs/event.stub5

---

Event Inspection and Debugging

While not part of code generation, the EventListCommand provides debugging capabilities for the event system:

Inspection Features:

• Event Filtering: Filter output by event name using --event option src/Commands/EventListCommand.php38
• Listener Filtering: Filter output by listener name using --listener option src/Commands/EventListCommand.php39
• Table Display: Renders events and their listeners in a readable table format src/Commands/EventListCommand.php104-106

Sources: src/Commands/EventListCommand.php25-107

---

Usage Examples

Generated Event Class Example

When running make:event OrderShipped, the generator produces:

app/Events/OrderShipped.php

With content following the event stub template structure src/Generator/stubs/event.stub1-21:

• Namespace: App\Events
• Class name: OrderShipped
• Includes Dispatchable trait
• Contains constructor for initialization

Generated Listener Class Example

When running make:listener SendShipmentNotification --event=OrderShipped, the generator produces:

app/Listeners/SendShipmentNotification.php

With content that includes:

• Namespace: App\Listeners
• Class name: SendShipmentNotification
• handle() method type-hinted with OrderShipped event

Sources: src/Generator/stubs/event.stub1-21 Standard generator patterns

---

Summary

The event and listener generation system provides:

Component	Generator Command	Output Location	Stub Template
Event Class	make:event	app/Events/	event.stub
Listener Class	make:listener	app/Listeners/	listener.stub

Key Design Patterns:

1. Dispatchable Trait: Events use the Dispatchable trait for static dispatch methods src/Generator/stubs/event.stub7-11
2. Type-Hinted Handlers: Listeners receive specific event instances in their handle() methods
3. PSR-14 Compliance: Integration with standard event dispatcher interfaces src/Commands/EventListCommand.php12
4. Container Resolution: Listeners are resolved from the dependency injection container src/Commands/EventListCommand.php20-31

Sources: src/Generator/stubs/event.stub1-21 src/Commands/EventListCommand.php1-109