Middleware Generation

Purpose and Scope

This document explains the make:middleware command, which generates HTTP middleware classes for the Hypervel framework. The command supports two middleware styles: standard Hypervel middleware and PSR-15 compatible middleware. Middleware classes intercept HTTP requests before they reach controllers or modify responses before they are sent to clients.

For information about other HTTP layer components, see Controller Generation and Request and Resource Generation.

Command Overview

The make:middleware command is implemented in the MiddlewareCommand class and is registered with the command name make:middleware. It generates middleware classes in the App\Http\Middleware namespace by default.

Basic Usage:

Command	Description	Output Location
make:middleware ClassName	Generate standard middleware	app/Http/Middleware/ClassName.php
make:middleware ClassName --psr15	Generate PSR-15 compatible middleware	app/Http/Middleware/ClassName.php

Sources: src/Generator/MiddlewareCommand.php14

MiddlewareCommand Class Structure

Diagram: MiddlewareCommand Inheritance Hierarchy

The MiddlewareCommand class extends Hyperf\Devtool\Generator\GeneratorCommand, inheriting the core stub processing and file generation functionality. The class overrides specific methods to provide middleware-specific behavior.

Sources: src/Generator/MiddlewareCommand.php10 src/Generator/MiddlewareCommand.php7

Command Execution Flow

Diagram: Middleware Generation Execution Flow

The command execution flow shows how the --psr15 option determines which stub template is selected through the getStub() method.

Sources: src/Generator/MiddlewareCommand.php24-31 src/Generator/MiddlewareCommand.php19

Stub Template Selection

The MiddlewareCommand implements conditional stub selection based on the --psr15 option:

src/Generator/MiddlewareCommand.php24-31

protected function getStub(): string
{
 return $this->getConfig()['stub'] ?? __DIR__ . (
 $this->input->getOption('psr15')
 ? '/stubs/middleware.psr15.stub'
 : '/stubs/middleware.stub'
 );
}

Stub Selection Logic:

1. Configuration Override: First checks getConfig()['stub'] to allow custom stub paths via configuration
2. PSR-15 Detection: If --psr15 option is present, selects middleware.psr15.stub
3. Default: Otherwise selects standard middleware.stub

The stub files are located relative to the MiddlewareCommand class file in the stubs/ subdirectory.

Sources: src/Generator/MiddlewareCommand.php24-31

Middleware Types

Standard Middleware

Standard Hypervel middleware uses a closure-based pattern compatible with Hyperf's middleware system.

Generated Structure:

src/Generator/stubs/middleware.stub1-21

Key Characteristics:

Aspect	Implementation
Method Name	handle()
Request Parameter	ServerRequestInterface $request
Next Handler	Closure $next
Return Type	ResponseInterface
Interface	None (convention-based)

Request Processing Pattern:

• Receives PSR-7 ServerRequestInterface request object
• Receives Closure $next representing the next middleware or controller
• Can modify request before calling $next($request)
• Can modify response after receiving it from $next()
• Must return ResponseInterface

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

PSR-15 Middleware

PSR-15 middleware implements the Psr\Http\Server\MiddlewareInterface standard, making it fully compatible with PSR-15 middleware stacks.

Generated Structure:

src/Generator/stubs/middleware.psr15.stub1-21

Key Characteristics:

Aspect	Implementation
Method Name	process()
Request Parameter	ServerRequestInterface $request
Next Handler	RequestHandlerInterface $handler
Return Type	ResponseInterface
Interface	MiddlewareInterface

PSR-15 Compliance:

• Explicitly implements MiddlewareInterface
• Uses RequestHandlerInterface instead of Closure
• Uses method name process() instead of handle()
• Calls $handler->handle($request) to delegate to next handler
• Fully interoperable with other PSR-15 middleware

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

Middleware Type Comparison

Diagram: Standard vs PSR-15 Middleware Comparison

Feature	Standard Middleware	PSR-15 Middleware
Stub File	middleware.stub	middleware.psr15.stub
Interface	None	MiddlewareInterface
Method Name	handle()	process()
Next Parameter Type	Closure	RequestHandlerInterface
Next Invocation	$next($request)	$handler->handle($request)
Standards Compliance	Hyperf convention	PSR-15 standard

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

Configuration and Options

Default Namespace

The default namespace for generated middleware is App\Http\Middleware, but can be overridden via configuration:

src/Generator/MiddlewareCommand.php33-36

protected function getDefaultNamespace(): string
{
 return $this->getConfig()['namespace'] ?? 'App\Http\Middleware';
}

Configuration can be provided through Hyperf's configuration system by setting values for the middleware generator.

Sources: src/Generator/MiddlewareCommand.php33-36

Command Options

The MiddlewareCommand extends the base generator options with one additional option:

src/Generator/MiddlewareCommand.php38-43

protected function getOptions(): array
{
 return array_merge(parent::getOptions(), [
 ['psr15', null, InputOption::VALUE_NONE, 'Create a PSR-15 compatible middleware'],
 ]);
}

Available Options:

Option	Type	Default	Description
--psr15	Flag	false	Create PSR-15 compatible middleware instead of standard
(parent options)	Various	-	Inherited from GeneratorCommand (e.g., --force)

Sources: src/Generator/MiddlewareCommand.php38-43 src/Generator/MiddlewareCommand.php8

Placeholder Replacement

Both middleware stubs use the following placeholders that are replaced during generation:

Placeholder	Replaced With	Example
%NAMESPACE%	Target namespace	App\Http\Middleware
%CLASS%	Class name	AuthenticateUser

The placeholder replacement is handled by the base GeneratorCommand class, which the MiddlewareCommand inherits from.

Sources: src/Generator/stubs/middleware.stub5-11 src/Generator/stubs/middleware.psr15.stub5-12

Integration with HTTP Layer

Diagram: Middleware in HTTP Request Lifecycle

Generated middleware classes integrate into Hyperf's HTTP middleware stack, where they intercept requests before they reach controllers and can modify responses before they are sent to clients. Middleware must be registered in the application's middleware configuration to be used.

Sources: src/Generator/MiddlewareCommand.php14

Usage Patterns

Pre-Processing Example

Middleware can modify the request before it reaches the controller:

Post-Processing Example

Middleware can modify the response after the controller processes the request:

Conditional Short-Circuit Example

Middleware can prevent the request from reaching the controller:

These patterns apply to both standard and PSR-15 middleware, with the only difference being the method signature (handle vs process and Closure vs RequestHandlerInterface).

Sources: src/Generator/stubs/middleware.stub16-19 src/Generator/stubs/middleware.psr15.stub17-20