Exception Generation

Purpose and Scope

This document covers the make:exception command, which generates custom exception classes for the application. The command creates exception classes that extend PHP's base Exception class and can optionally include render() and report() methods for custom error handling and logging.

For information about other code generators, see Additional Generators. For general code generation architecture, see Code Generation System.

---

Command Overview

The ExceptionCommand class provides the make:exception command for generating exception classes. It extends GeneratorCommand and supports two primary options that control the structure of the generated exception.

Command Signature:

make:exception <name> [--render] [--report]

Available Options:

Option	Type	Description
--render	Flag	Include an empty render() method for custom HTTP response rendering
--report	Flag	Include an empty report() method for custom exception logging

The command generates exception classes in the App\Exceptions namespace by default and creates files in the app/Exceptions directory.

Sources: src/Generator/ExceptionCommand.php1-50

---

Command Architecture

Class Structure

The ExceptionCommand follows the standard generator pattern by extending GeneratorCommand and overriding key methods to customize behavior for exception generation.

Sources: src/Generator/ExceptionCommand.php10-50

---

Configuration

Default Settings

The command uses the following default configuration:

• Namespace: App\Exceptions src/Generator/ExceptionCommand.php38-41
• Stub Location: src/Generator/stubs/exception*.stub src/Generator/ExceptionCommand.php24-36

Both settings can be overridden through configuration:

The configuration is retrieved via the getConfig() method inherited from GeneratorCommand.

Sources: src/Generator/ExceptionCommand.php35-41

---

Stub Template Selection Logic

The command selects one of four stub templates based on the combination of --render and --report options:

Stub Selection Flow

Stub Selection Implementation

The stub selection logic is implemented in the getStub() method:

if (--render option present) {
 if (--report option present) {
 return exception-render-report.stub
 } else {
 return exception-render.stub
 }
} else {
 if (--report option present) {
 return exception-report.stub
 } else {
 return exception.stub
 }
}

Sources: src/Generator/ExceptionCommand.php24-36

---

Generated Exception Types

Basic Exception

Generated with: make:exception MyException

Structure:

• Extends Exception
• No custom methods
• Empty class body for manual implementation

Stub Template: src/Generator/stubs/exception.stub1-13

---

Exception with Report Method

Generated with: make:exception MyException --report

Structure:

• Extends Exception
• Includes report(): void method for custom logging
• Method body is empty by default

Stub Template: src/Generator/stubs/exception-report.stub1-19

The report() method is called by the exception handler to log or report the exception. Common use cases include:

• Custom logging to external services
• Conditional reporting based on exception context
• Aggregating exception data for monitoring

Sources: src/Generator/stubs/exception-report.stub1-19

---

Exception with Render Method

Generated with: make:exception MyException --render

Structure:

• Extends Exception
• Includes render(Request $request): Response method
• Imports Hypervel\Http\Request and Hypervel\Http\Response

Stub Template: src/Generator/stubs/exception-render.stub1-21

The render() method allows custom HTTP response generation when the exception is caught during request handling. Use cases include:

• Custom error pages
• API error response formatting
• Conditional rendering based on request type (JSON, HTML)

Sources: src/Generator/stubs/exception-render.stub1-21

---

Exception with Both Methods

Generated with: make:exception MyException --render --report

Structure:

• Extends Exception
• Includes both report(): void and render(Request, Response) methods
• Imports all necessary dependencies

Stub Template: src/Generator/stubs/exception-render-report.stub1-29

This variant provides complete control over both exception reporting and HTTP response rendering.

Sources: src/Generator/stubs/exception-render-report.stub1-29

---

Exception Class Comparison

Feature	Basic	--report	--render	--render --report
Extends	Exception	Exception	Exception	Exception
report() method	❌	✅	❌	✅
render() method	❌	❌	✅	✅
Hypervel\Http imports	❌	❌	✅	✅
Use Case	Simple custom exception	Custom logging	Custom error responses	Full control
Stub File	exception.stub	exception-report.stub	exception-render.stub	exception-render-report.stub

Sources: src/Generator/stubs/exception.stub1-13 src/Generator/stubs/exception-report.stub1-19 src/Generator/stubs/exception-render.stub1-21 src/Generator/stubs/exception-render-report.stub1-29

---

Code Entity Mapping

Sources: src/Generator/ExceptionCommand.php24-49

---

Usage Examples

Example 1: Basic Custom Exception

Creates app/Exceptions/PaymentFailedException.php with a basic exception class that can have custom properties and methods added manually.

---

Example 2: Exception with Custom Logging

Generates an exception with a report() method for custom logging behavior, useful for tracking rate limit violations.

---

Example 3: Exception with Custom Response

Creates an exception with a render() method for returning a custom maintenance page or JSON response.

---

Example 4: Full-Featured Exception

Generates an exception with both methods, allowing custom logging and response rendering for subscription validation errors.

Sources: src/Generator/ExceptionCommand.php1-50

---

Integration with Exception Handler

The generated exception classes integrate with the application's exception handler. When an exception is thrown:

1. Report Phase: If the exception has a report() method, it is called to log the exception
2. Render Phase: If the exception has a render() method, it is used to generate the HTTP response
3. Fallback: If methods are not present, the default exception handler behavior applies

This allows fine-grained control over exception handling on a per-exception basis while maintaining compatibility with the framework's exception handling infrastructure.

Sources: src/Generator/stubs/exception-render-report.stub1-29