 |
VOOZH | about |
|
VOOZH | about |
This document covers the event-driven architecture generators in the hypervel/devtool package. These generators create classes for the observer pattern and event dispatch system, enabling loosely-coupled, reactive application design.
The event system generators include:
make:event - Creates event classes that represent application occurrencesmake:listener - Creates listener classes that respond to eventsmake:observer - Creates observer classes that respond to model lifecycle eventsFor job queue generation (background processing), see Job and Queue Generators. For notification-related generators (mail, channels), see the respective sections. For the development tool that inspects registered events and listeners, see Event Inspector.
The event system provides a mechanism for decoupling application components through the observer pattern. The architecture consists of three primary components:
Sources: src/Generator/stubs/event.stub1-21 src/Generator/stubs/observer.stub1-51
| Component | Purpose | Generated By | Default Location |
|---|---|---|---|
| Event | Immutable data container representing an occurrence | make:event | App\Events |
| Listener | Handler that executes logic in response to events | make:listener | App\Listeners |
| Observer | Specialized listener for model lifecycle events | make:observer | App\Observers |
Events use the Dispatchable trait from Hypervel\Foundation\Events\Dispatchable, providing static dispatch methods for firing events throughout the application.
Sources: src/Generator/stubs/event.stub7-11
The event system generators create the classes necessary for event-driven architecture:
| Command | Description | Primary Options | Output Location |
|---|---|---|---|
make:event | Creates event class | --force (overwrite) | app/Events/{Name}.php |
make:listener | Creates event listener class | --event (bind to event)--queued (async) | app/Listeners/{Name}.php |
make:observer | Creates model observer class | --model (target model) | app/Observers/{Name}Observer.php |
All commands extend Hyperf\Devtool\Generator\GeneratorCommand and follow the standard generator pattern: accept a class name, process a stub template, perform placeholder substitution, and write the file to the filesystem.
Sources: src/Generator/ObserverCommand.php11-16
make:eventThe make:event command generates event classes that encapsulate data about application occurrences. Events are dispatched to notify the application that something has happened.
Basic Usage:
Sources: src/Generator/stubs/event.stub1-21
The event stub template src/Generator/stubs/event.stub1-21 produces classes with the following characteristics:
%NAMESPACE% placeholder, defaults to App\EventsHypervel\Foundation\Events\Dispatchable src/Generator/stubs/event.stub7%CLASS% placeholder replaced with the provided nameExample Generated Code Pattern:
Sources: src/Generator/stubs/event.stub1-21
make:listenerThe make:listener command generates listener classes that handle events. Listeners contain the business logic that should execute when an event occurs.
Basic Usage:
| Option | Description |
|---|---|
--event=<EventClass> | Bind listener to specific event class |
--queued | Generate queued listener (asynchronous execution) |
Queued listeners implement queue interfaces and are dispatched to background workers rather than executing synchronously during the request lifecycle.
Note: The listener stub template and ListenerCommand implementation are not included in the provided files, but they follow the same generator pattern as other commands in this package.
make:observerThe make:observer command generates observer classes that respond to model lifecycle events. Observers centralize event handling logic for a specific model, responding to creation, updates, deletion, and restoration events.
Basic Usage:
Sources: src/Generator/ObserverCommand.php11-22
The ObserverCommand class src/Generator/ObserverCommand.php1-65 implements model-aware stub processing:
Sources: src/Generator/ObserverCommand.php28-46
The replaceClass() method src/Generator/ObserverCommand.php28-46 implements intelligent model detection:
Explicit Model Option: If --model is provided, use that value src/Generator/ObserverCommand.php31
Name-Based Inference: If no option, extract model from observer name:
Str::before() src/Generator/ObserverCommand.php32-34Namespace Construction: Combine with configured model namespace src/Generator/ObserverCommand.php37-38:
config['model_namespace'] ?? 'App\Models'
Variable Name: Generate camelCase variable name using Str::camel() src/Generator/ObserverCommand.php39
Sources: src/Generator/ObserverCommand.php28-46
The observer stub src/Generator/stubs/observer.stub1-51 generates classes with handlers for five model lifecycle events:
| Method | Triggered When | Line Reference |
|---|---|---|
created() | Model instance is created and saved | src/Generator/stubs/observer.stub14-17 |
updated() | Model instance is updated and saved | src/Generator/stubs/observer.stub22-25 |
deleted() | Model instance is soft or hard deleted | src/Generator/stubs/observer.stub30-33 |
restored() | Soft-deleted model is restored | src/Generator/stubs/observer.stub38-41 |
forceDeleted() | Model is permanently deleted (hard delete) | src/Generator/stubs/observer.stub46-49 |
Sources: src/Generator/stubs/observer.stub1-51
The observer template uses three model-specific placeholders:
| Placeholder | Replaced With | Example |
|---|---|---|
%NAMESPACE_MODEL% | Full model class path | App\Models\User |
%MODEL% | Model class name | User |
%MODEL_VARIABLE% | camelCase variable name | $user |
Example Generated Observer:
Sources: src/Generator/stubs/observer.stub1-51 src/Generator/ObserverCommand.php41-45
Observer generation respects configuration values accessed via getConfig() src/Generator/ObserverCommand.php37-56:
| Configuration Key | Purpose | Default Value |
|---|---|---|
model_namespace | Base namespace for models | App\Models |
namespace | Observer output namespace | App\Observers |
stub | Custom stub file path | __DIR__ . '/stubs/observer.stub' |
Configuration is retrieved from the generator's configuration system, allowing project-specific customization of namespaces and stub templates.
Sources: src/Generator/ObserverCommand.php48-56
The ObserverCommand extends parent options with model-specific configuration src/Generator/ObserverCommand.php58-63:
This adds the --model / -m option to the standard generator options (like --force for overwriting existing files).
Sources: src/Generator/ObserverCommand.php58-63
While not a generator, the EventListCommand provides development-time visibility into the event system. This command inspects the event dispatcher to display registered events and their listeners.
Sources: src/Commands/EventListCommand.php25-33 src/Commands/EventListCommand.php42-93
The command provides filtering capabilities src/Commands/EventListCommand.php27-28:
--event / -e: Filter by event name (partial match)--listener / -l: Filter by listener name (partial match)Listener display logic src/Commands/EventListCommand.php66-86 handles multiple listener types:
[ClassName, 'method'] → displays as ClassName::method'Closure''Unknown listener'The output table src/Commands/EventListCommand.php95-107 uses Symfony Console's Table component to render a two-column display with separators between rows.
Sources: src/Commands/EventListCommand.php1-109
Observers integrate closely with the model lifecycle. When generating a complete model system using make:model --all, the observer can be included to immediately set up lifecycle event handling.
Generated observers must be manually registered with models. Typical registration occurs in service providers or model boot methods:
The observer pattern allows multiple observers per model and supports granular control over which lifecycle events trigger which handlers.
Sources: src/Generator/stubs/observer.stub1-51
app/
├── Events/
│ ├── UserRegistered.php
│ ├── Order/
│ │ └── OrderShipped.php
│ └── Payment/
│ └── PaymentProcessed.php
├── Listeners/
│ ├── SendWelcomeEmail.php
│ ├── SendOrderConfirmation.php
│ └── ProcessPaymentNotification.php
└── Observers/
├── UserObserver.php
├── PostObserver.php
└── CommentObserver.php
| Generator | Naming Pattern | Example |
|---|---|---|
make:event | PastTense + Noun | UserRegistered, OrderShipped |
make:listener | Action verb phrase | SendWelcomeEmail, UpdateInventory |
make:observer | Model name + Observer | UserObserver, PostObserver |
The observer naming convention is enforced through the model inference algorithm src/Generator/ObserverCommand.php32-34 which strips the "Observer" suffix to determine the target model.
Sources: src/Generator/ObserverCommand.php32-34 src/Generator/ObserverCommand.php54-56
The event system generators provide the foundational classes for implementing event-driven architecture in Hypervel applications:
Dispatchable traitAll generators follow consistent patterns: stub template processing, configurable namespaces, and intelligent placeholder replacement. The ObserverCommand demonstrates advanced features like model inference from class names and automatic namespace construction.
For development-time inspection of registered events and listeners, use the event:list command documented in Event Inspector.
Sources: src/Generator/stubs/event.stub1-21 src/Generator/ObserverCommand.php1-65 src/Generator/stubs/observer.stub1-51 src/Commands/EventListCommand.php1-109
Refresh this wiki