HTTP Layer Generators

Purpose and Scope

This document provides an overview of the HTTP layer generator commands in the Hypervel/Devtool package. These generators create PHP classes for handling HTTP requests and responses, including controllers, middleware, form requests, and API resources.

This page covers the architectural relationships between these generators and their shared patterns. For detailed documentation on specific generators, see:

• Controller generation with all stub variants and options: 7.1
• Middleware generation including PSR-15 support: 7.2
• Request and Resource generation: 7.3

For model-related generators, see 5. For authorization generators like policies, see 10.

---

HTTP Layer Component Generators

The HTTP layer generators create four primary types of components that work together to handle web requests:

Generator	Command	Default Namespace	Primary Purpose
ControllerCommand	make:controller	App\Http\Controllers	Route handlers and business logic orchestration
MiddlewareCommand	make:middleware	App\Http\Middleware	Request/response filtering and transformation
RequestCommand	make:request	App\Http\Requests	Form validation and authorization
ResourceCommand	make:resource	App\Http\Resources	API response transformation

Sources: src/Generator/ControllerCommand.php48-51 src/Generator/RequestCommand.php28-31 src/Generator/ResourceCommand.php34-37

---

Generator Class Hierarchy

Diagram: HTTP Layer Generator Architecture

All HTTP layer generators extend the GeneratorCommand base class from Hyperf, inheriting stub processing, namespace resolution, and file generation capabilities. The ControllerCommand has a special orchestration capability where the --requests option triggers automatic generation of FormRequest classes through the call() method.

Sources: src/Generator/ControllerCommand.php12-16 src/Generator/RequestCommand.php9-14 src/Generator/ResourceCommand.php10-15 src/Generator/ControllerCommand.php97-112

---

Controller Generation System

The ControllerCommand provides the most sophisticated stub selection logic among HTTP layer generators, supporting five distinct controller types through various combinations of flags and options.

Controller Stub Selection Logic

Diagram: ControllerCommand Stub Selection Flow

The stub selection occurs in the getStub() method and follows a priority hierarchy: explicit --type option takes precedence, followed by --model, then --resource, then --api, and finally defaults to plain. The --api flag can modify other stubs by appending .api before the .stub extension.

Sources: src/Generator/ControllerCommand.php26-46

Controller Method Patterns

The different controller stubs generate methods following RESTful conventions:

Stub Type	Methods Generated	Use Case
controller.plain.stub	Empty class	Custom controller without resource structure
controller.stub	index, create, store, show, edit, update, destroy	Full resource controller with form views
controller.api.stub	index, store, show, update, destroy	API resource controller (no create/edit)
controller.model.stub	Same as controller.stub with model type-hinting	Model-bound resource controller
controller.model.api.stub	Same as controller.api.stub with model type-hinting	Model-bound API controller

Sources: src/Generator/stubs/controller.plain.stub1-13 src/Generator/stubs/controller.stub1-67 src/Generator/stubs/controller.api.stub1-51

---

Request Orchestration Pattern

The ControllerCommand can automatically generate FormRequest classes when used with both --model and --requests options, demonstrating the orchestration pattern where one generator invokes another.

Diagram: Controller-to-Request Generation Flow

The orchestration occurs in two methods: replaceClass() checks for the --requests option and invokes generateFormRequests(), which uses the call() method to execute make:request commands programmatically. The generated request class names follow the pattern Store{Model}Request and Update{Model}Request.

Sources: src/Generator/ControllerCommand.php66-95 src/Generator/ControllerCommand.php97-112 src/Generator/ControllerCommand.php114-120

Model Placeholder Replacement

When using the --model option, the controller stub uses several placeholders that get replaced during generation:

Placeholder	Replaced With	Example
%NAMESPACED_MODEL%	Fully qualified model class name	App\Models\User
%MODEL%	Model class basename	User
%MODEL_VARIABLE%	Camelcase model variable	$user
%NAMESPACED_REQUESTS%	Request class use statements	use App\Http\Requests\StoreUserRequest;
%STORE_REQUEST%	Store request class name	StoreUserRequest
%UPDATE_REQUEST%	Update request class name	UpdateUserRequest

Sources: src/Generator/ControllerCommand.php72-94 src/Generator/stubs/controller.model.stub7-8

---

Resource Generation System

The ResourceCommand generates API resource transformers that extend either JsonResource or ResourceCollection depending on whether the class name ends with "Collection" or the --collection flag is used.

Resource Type Selection

Diagram: ResourceCommand Stub Selection Logic

The stub selection in getStub() uses str_ends_with() to check the class name or examines the --collection option. Both conditions lead to the resource-collection.stub template; otherwise, the standard resource.stub is used.

Sources: src/Generator/ResourceCommand.php24-32

Resource Class Structure

Both resource types provide a toArray() method for transforming data:

Resource Type	Base Class	Use Case	Stub Template
Single Resource	Hypervel\Http\Resources\Json\JsonResource	Transform individual model instances	resource.stub
Resource Collection	Hypervel\Http\Resources\Json\ResourceCollection	Transform collections of models	resource-collection.stub

Sources: src/Generator/stubs/resource.stub1-19 src/Generator/stubs/resource-collection.stub1-19

---

Middleware Generation

The MiddlewareCommand generates middleware classes that intercept HTTP requests and responses. The standard middleware stub uses the Hyperf convention with a handle() method accepting ServerRequestInterface and a Closure for the next middleware in the chain.

Middleware Structure

The generated middleware follows this pattern from src/Generator/stubs/middleware.stub1-21:

The middleware receives the request, can perform pre-processing, passes the request to the next middleware via $next($request), and can perform post-processing on the returned response.

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

---

FormRequest Validation

The RequestCommand generates classes extending Hypervel\Foundation\Http\FormRequest that encapsulate validation logic and authorization checks for incoming HTTP requests.

FormRequest Structure

The generated FormRequest provides two key methods from src/Generator/stubs/request.stub1-28:

Method	Return Type	Purpose
authorize()	bool	Determines if the user is authorized to make the request
rules()	array	Returns validation rules for the request data

By default, authorize() returns true, allowing all requests through. Developers modify this to implement authorization logic. The rules() method returns an empty array that developers populate with validation rules.

Sources: src/Generator/stubs/request.stub1-28

---

Configuration and Customization

All HTTP layer generators support configuration overrides through the getConfig() method inherited from GeneratorCommand. The configuration can customize:

Configuration Key	Purpose	Example
stub	Override default stub file path	Custom controller template
namespace	Override default namespace	App\Api\Controllers instead of App\Http\Controllers
model_namespace	Override default model namespace (controllers only)	Domain\Models instead of App\Models

The configuration is retrieved via $this->getConfig() and checked before falling back to defaults in methods like getStub() and getDefaultNamespace().

Sources: src/Generator/ControllerCommand.php45 src/Generator/ControllerCommand.php48-51 src/Generator/ControllerCommand.php127 src/Generator/RequestCommand.php25 src/Generator/ResourceCommand.php26

---

Command Options Summary

Each HTTP layer generator provides specific command-line options:

ControllerCommand Options

Option	Shortcut	Type	Description
--namespace	-N	Value	Custom namespace for the controller
--api	-	Flag	Exclude create and edit methods
--type	-	Value	Manually specify stub file to use
--force	-	Flag	Overwrite existing file
--model	-m	Value	Generate resource controller for model
--resource	-r	Flag	Generate resource controller
--requests	-R	Flag	Generate FormRequest classes

Sources: src/Generator/ControllerCommand.php53-64

ResourceCommand Options

Option	Shortcut	Type	Description
--namespace	-N	Value	Custom namespace for the resource
--force	-f	Flag	Overwrite existing file
--collection	-c	Flag	Create a resource collection

Sources: src/Generator/ResourceCommand.php39-46

RequestCommand Options

The RequestCommand uses the standard options inherited from GeneratorCommand without additional custom options.

Sources: src/Generator/RequestCommand.php1-33

---

Integration with Generator System

All HTTP layer generators follow the standard generator command pattern documented in 3.2:

1. Stub Selection: Override getStub() to select appropriate template based on options
2. Namespace Resolution: Override getDefaultNamespace() to specify output location
3. Placeholder Replacement: Override replaceClass() for custom placeholder substitution
4. File Generation: Inherit file writing logic from GeneratorCommand

The HTTP layer generators are registered in ConfigProvider and become available as make:controller, make:middleware, make:request, and make:resource commands when the package is installed.

Sources: src/Generator/ControllerCommand.php1-136 src/Generator/RequestCommand.php1-33 src/Generator/ResourceCommand.php1-48