 |
VOOZH | about |
|
VOOZH | about |
This document covers the error handling mechanisms and event dispatching system in the hypervel/console package. It details how exceptions are caught and handled during command execution, the ManuallyFailedException class for controlled failures, and the lifecycle events emitted during both command and scheduled task execution.
For information about command execution lifecycle, see Command System. For scheduled task execution flow, see Event Execution and Lifecycle.
The Command base class implements a comprehensive error handling system within its execution pipeline. The execute method wraps command execution in a try-catch-finally block that handles multiple exception types and dispatches appropriate events.
Sources: src/Command.php41-89
The ManuallyFailedException class is a specialized exception used to intentionally fail a command with a user-friendly error message. It extends RuntimeException and is caught specifically in the command execution flow to provide controlled failure semantics.
Class Definition:
The exception is a simple marker class that identifies intentional command failures:
Usage via fail() Method:
Commands can fail manually using the fail() method, which accepts either a string message, a Throwable exception, or null (defaults to generic message):
ManuallyFailedExceptionThrowable, it re-throws that exception directlyHandling Behavior:
When ManuallyFailedException is caught during command execution:
$this->components->error($e->getMessage())Command::FAILURE (value 1)FailToHandle event is dispatched (only applies to unexpected exceptions)This provides a clean way for commands to signal failure conditions without exposing stack traces or triggering error event handlers.
Sources: src/ManuallyFailedException.php1-11 src/Command.php104-115 src/Command.php56-59
For all other exceptions implementing Throwable, the command execution flow follows a multi-step handling process:
Swoole's ExitException receives special handling. When caught, the command extracts the exit status from the exception and returns it directly:
This allows Swoole exit semantics to propagate correctly through the command system.
If no event dispatcher is bound to the command, the exception is immediately re-thrown, bypassing error rendering and event dispatching. This ensures exceptions are not silently swallowed when no error handling infrastructure exists.
When an event dispatcher is available, the ErrorRenderer class formats and displays the exception:
The renderer receives the command's input and output interfaces to properly format the error for console display.
After rendering the error, the FailToHandle event is dispatched with both the command instance and the caught exception:
This allows event listeners to log errors, trigger alerts, or perform other error handling actions.
The exit code is set to Command::FAILURE (value 1) to indicate execution failure.
Sources: src/Command.php60-74
The command execution pipeline emits four distinct events that provide observability into command execution. These events are dispatched at specific points in the execution lifecycle using the Hyperf event dispatcher.
| Event Class | Dispatch Location | Timing | Exception Available |
|---|---|---|---|
BeforeHandle | Before handle() call | Pre-execution hooks, initialization | No |
AfterHandle | After successful handle() | Success path only | No |
FailToHandle | When exception caught | Error path only (except ManuallyFailedException) | Yes |
AfterExecute | finally block | Always, regardless of success/failure | Yes (if failed) |
Sources: src/Command.php47-80
Dispatched immediately before the command's handle() method is invoked. This event fires in all execution scenarios, providing a guaranteed pre-execution hook point.
Properties:
$this: The command instance being executedUse Cases:
Sources: src/Command.php49
Dispatched after the command's handle() method completes successfully without throwing exceptions. This event indicates successful execution in the normal path.
Properties:
$this: The command instance that completedUse Cases:
BeforeHandle)Sources: src/Command.php55
Dispatched when any exception (except ManuallyFailedException and ExitException) is caught during command execution. This event provides both the command context and the exception details.
Properties:
$this: The command instance that failed$exception: The Throwable that was caughtUse Cases:
Important: This event is only dispatched when an event dispatcher is available. If no dispatcher exists, the exception is re-thrown.
Sources: src/Command.php74
Dispatched in the finally block of the execution flow, guaranteeing it fires regardless of success, failure, or ManuallyFailedException. This is the only event that always executes.
Properties:
$this: The command instance$exception: The Throwable if one occurred, otherwise nullUse Cases:
BeforeHandle)Key Characteristic: This event receives the exception parameter even in the success case (as null), allowing listeners to distinguish between success and failure paths.
Sources: src/Command.php76
All event dispatching in the command system uses the null-safe operator to ensure commands can function without event infrastructure:
This pattern is applied consistently across all four lifecycle events, allowing commands to operate in minimal environments.
Sources: src/Command.php49 src/Command.php55 src/Command.php74 src/Command.php76
The scheduling system emits three lifecycle events for each scheduled task execution, providing observability into task status. These events are dispatched by the Event class during task execution and follow a similar pattern to command lifecycle events.
Sources: src/Events/ScheduledTaskStarting.php1-19 src/Events/ScheduledTaskFailed.php1-20
Dispatched immediately before a scheduled event begins execution. This event fires after all eligibility checks pass (isDue, filtersPass, mutex checks) but before the actual execution starts.
Properties:
task (Event): The scheduled event instance about to executeConstructor:
Use Cases:
Sources: src/Events/ScheduledTaskStarting.php9-18
Dispatched after a scheduled event completes successfully without throwing exceptions. This event indicates the task ran to completion in the normal path.
Properties:
task (Event): The scheduled event instance that completed successfullyUse Cases:
ScheduledTaskStarting)Note: The implementation file for this class was not provided in the source listing, but it is referenced in system documentation and follows the same pattern as ScheduledTaskStarting.
Dispatched when a scheduled event throws an exception during execution. This event provides both the task context and the exception details for comprehensive error handling.
Properties:
task (Event): The scheduled event instance that failedexception (Throwable): The exception that caused the failureConstructor:
Use Cases:
Sources: src/Events/ScheduledTaskFailed.php10-19
The scheduled task execution integrates event dispatching at key lifecycle points. Events are dispatched through the application's event dispatcher as tasks progress through their execution pipeline.
The scheduled task events integrate with the broader execution pipeline:
This flow ensures events are dispatched at the appropriate times for monitoring while maintaining proper resource cleanup even in failure scenarios.
Sources: Based on high-level architecture diagrams and event class structure
The error handling system carefully manages command exit codes to communicate execution status to callers and external systems (such as cron or process supervisors).
| Scenario | Exit Code | Constant | Set Location |
|---|---|---|---|
| Successful execution | 0 or custom value | Command::SUCCESS | handle() return value |
Manual failure via fail() | 1 | Command::FAILURE | ManuallyFailedException handler |
| Exception thrown | 1 | Command::FAILURE | General exception handler |
| ExitException caught | Exception status | N/A | ExitException handler |
| Out of range (0-255) | 255 | Command::INVALID | Exit validation |
The final exit code is validated to ensure it falls within the POSIX-compliant range (0-255):
This validation catches programmer errors where invalid exit codes might be returned from handle() methods.
Sources: src/Command.php52-54 src/Command.php59 src/Command.php62 src/Command.php72 src/Command.php88
The ErrorRenderer class formats and displays exception details to the console output when unexpected exceptions occur during command execution. This system is separate from ManuallyFailedException handling, which displays simple error messages without stack traces.
The error renderer is instantiated with the command's input and output interfaces:
This ensures the renderer has access to:
The error renderer is invoked:
FailToHandle event is dispatchedfinally block executesThis positioning ensures users see formatted error output before event handlers are notified of the failure.
Sources: src/Command.php69-70
The error handling and event system relies on the Hyperf event dispatcher for all event broadcasting. Commands maintain an optional reference to the event dispatcher and use null-safe dispatching throughout.
All event dispatching uses the null-safe operator (?->) to allow commands to function without event infrastructure:
This pattern ensures:
When no event dispatcher is bound and an exception occurs:
FailToHandle event is dispatchedAfterExecute event is dispatchedThis behavior prevents silent exception swallowing when no error handling infrastructure exists.
Sources: src/Command.php49 src/Command.php55 src/Command.php65-66 src/Command.php74 src/Command.php76
The error handling and event system enables several observability patterns through strategic event listener registration.
Track command execution time by pairing BeforeHandle and AfterExecute events:
Listener receives BeforeHandle → Record start timestamp
Listener receives AfterExecute → Calculate duration = now - start
→ Log execution time with command name
Advantage: AfterExecute fires in all scenarios (success, failure, manual failure), ensuring complete duration data.
Monitor command and task failure rates by counting FailToHandle and ScheduledTaskFailed events:
Listener receives FailToHandle → Increment command_failures counter
→ Tag with command name
Listener receives ScheduledTaskFailed → Increment task_failures counter
→ Tag with task expression
Metric Export: Push counters to monitoring systems (Prometheus, StatsD, CloudWatch)
Create audit trails using the complete event lifecycle:
For Commands:
BeforeHandle → Log: "Command {name} started by {user}"
AfterHandle → Log: "Command {name} completed successfully in {duration}s"
FailToHandle → Log: "Command {name} failed: {exception.message}"
AfterExecute → Log: "Command {name} finished with exit code {exitCode}"
For Scheduled Tasks:
ScheduledTaskStarting → Log: "Task {expression} {command} starting"
ScheduledTaskFinished → Log: "Task {expression} completed successfully"
ScheduledTaskFailed → Log: "Task {expression} failed: {exception.message}"
Collect exceptions for analysis and alerting:
Listener receives FailToHandle:
→ Extract exception class, message, stack trace
→ Send to error tracking service (Sentry, Rollbar)
→ Check if critical exception type → Trigger alert
Listener receives ScheduledTaskFailed:
→ Extract task details (expression, command)
→ Send to error tracking with task context
→ Check failure count threshold → Trigger alert
Track successful operations for SLA monitoring:
Listener receives AfterHandle → Increment command_success counter
Listener receives ScheduledTaskFinished → Increment task_success counter
Calculate: success_rate = successes / (successes + failures)
Implement cross-cutting concerns using event listeners:
BeforeHandle listener:
→ Start database transaction
→ Initialize performance profiler
→ Set request context
AfterExecute listener:
→ Commit/rollback transaction based on exit code
→ Flush profiler data
→ Clear request context
Events can be correlated using command instance identity or scheduled task properties:
BeforeHandle event contains command instance $cmd
AfterExecute event contains same command instance $cmd
→ Use object identity or command name for correlation
ScheduledTaskStarting contains Event $task
ScheduledTaskFinished contains same Event $task
→ Use task instance or task identifier for correlation
The error handling and events system provides comprehensive observability and control over command and scheduled task execution:
ManuallyFailedException, ExitException, and general ThrowableErrorRenderer provides developer-friendly exception displayBeforeHandle, AfterHandle, FailToHandle, AfterExecute) and three scheduled task events (ScheduledTaskStarting, ScheduledTaskFinished, ScheduledTaskFailed)AfterExecute fires in finally block for cleanup and metricsThis architecture enables robust error handling in development while providing the hooks necessary for comprehensive monitoring, logging, and alerting in production environments.
Sources: src/Command.php41-126 src/ManuallyFailedException.php1-11 src/Events/ScheduledTaskStarting.php1-19 src/Events/ScheduledTaskFailed.php1-20
Refresh this wiki