System Architecture

This document explains the high-level architecture of the Hypervel/Devtool package, covering how the package integrates with the Hyperf framework, the three-layer system organization, and the core patterns used throughout the codebase.

For detailed information about command registration mechanisms, see Command Registration System. For generator command implementation patterns, see Generator Command Architecture. For stub template processing, see Stub Template System.

---

Package Overview

Hypervel/Devtool is a development tool suite that extends Hyperf's base generator capabilities. The package provides 30+ commands organized into three distinct subsystems:

Subsystem	Command Count	Purpose
Code Generators	26 commands	Generate application-level components (models, controllers, middleware, etc.)
Database Migration Generators	7 commands	Generate framework infrastructure tables (cache, sessions, queues, notifications)
Utility Commands	2 commands	Provide development workflow tools (hot-reload watcher, event inspector)

The package is distributed via Composer and automatically discovered by Hyperf through the extra.hyperf.config metadata in composer.json32-34

Sources: composer.json src/ConfigProvider.php

---

Package Discovery and Initialization

The Hyperf framework discovers and initializes the Hypervel/Devtool package through a three-phase process:

Initialization Flow Diagram

Configuration Discovery

The package is discovered via the extra.hyperf.config key in composer.json32-34:

"extra": {
 "hyperf": {
 "config": "Hypervel\\Devtool\\ConfigProvider"
 }
}

This instructs Hyperf to invoke the ConfigProvider::__invoke() method during framework initialization.

Fail-Safe Registration Pattern

The ConfigProvider implements a fail-safe pattern in src/ConfigProvider.php43-45:

This check ensures the package degrades gracefully if the hyperf/devtool dependency is missing. If GeneratorCommand is not available, no commands are registered and the package remains dormant.

Sources: composer.json31-34 src/ConfigProvider.php41-82

---

Three-Layer System Architecture

The package implements a three-layer architecture that separates concerns between registration, command implementation, and output generation:

System Layers Diagram

Layer 1: Registration & Discovery
The ConfigProvider48-79 class registers all 30+ command classes with Hyperf's DI container. This layer is responsible for making commands available to the console application.

Layer 2: Command Implementation
All generator commands inherit from Hyperf\Devtool\Generator\GeneratorCommand, which provides core functionality for stub loading, namespace resolution, placeholder replacement, and file writing. Commands override specific methods to customize behavior.

Layer 3: Output Generation
Commands read stub templates (.stub files), process placeholders, and write output to either application directories (app/) or migration directories (database/migrations/).

Sources: src/ConfigProvider.php src/Generator/ModelCommand.php src/Generator/FactoryCommand.php

---

Command Registration Architecture

The ConfigProvider class centralizes all command registration in a single location:

Command Organization Table

Category	Namespace	Example Commands	Registration Lines
Utility Commands	Hypervel\Devtool\Commands	WatchCommand, EventListCommand	ConfigProvider49-63
Code Generators	Hypervel\Devtool\Generator	ModelCommand, ControllerCommand, MiddlewareCommand	ConfigProvider60-76
Table Generators	Hypervel\Devtool\Generator	CacheTableCommand, SessionTableCommand, QueueTableCommand	ConfigProvider55-67

All commands are returned in a commands array from ConfigProvider48-79 which Hyperf's service container uses to instantiate and register them.

Complete Command Registry

The package registers exactly 30 commands in src/ConfigProvider.php48-79:

'commands' => [
 WatchCommand::class,
 ProviderCommand::class,
 EventCommand::class,
 ListenerCommand::class,
 ComponentCommand::class,
 TestCommand::class,
 SessionTableCommand::class,
 CacheTableCommand::class,
 CacheLocksTableCommand::class,
 RuleCommand::class,
 ConsoleCommand::class,
 ModelCommand::class,
 FactoryCommand::class,
 SeederCommand::class,
 EventListCommand::class,
 RequestCommand::class,
 NotificationTableCommand::class,
 BatchesTableCommand::class,
 QueueTableCommand::class,
 QueueFailedTableCommand::class,
 JobCommand::class,
 ChannelCommand::class,
 ObserverCommand::class,
 NotificationCommand::class,
 MailCommand::class,
 PolicyCommand::class,
 MiddlewareCommand::class,
 ControllerCommand::class,
 ResourceCommand::class,
 ExceptionCommand::class,
]

Sources: src/ConfigProvider.php39-82

---

Command Inheritance and Extension

All generator commands extend from Hyperf\Devtool\Generator\GeneratorCommand, which provides the base implementation for code generation:

Class Hierarchy Diagram

Base Class Methods

GeneratorCommand provides these key methods that subclasses override:

Method	Purpose	Example Implementation
getStub(): string	Return path to stub template file	ModelCommand80-83 FactoryCommand25-28
getDefaultNamespace(): string	Return base namespace for generated class	ModelCommand85-88 FactoryCommand78-81
replaceClass(string $stub, string $name): string	Replace placeholders in stub content	ModelCommand71-78 FactoryCommand40-58
getPath(string $name): string	Return filesystem path for output file	FactoryCommand71-76
getOptions(): array	Define command-line options	ModelCommand90-105 FactoryCommand83-90

Sources: src/Generator/ModelCommand.php src/Generator/FactoryCommand.php

---

Command Orchestration Pattern

Some commands act as orchestrators that invoke other commands programmatically. The primary example is ModelCommand, which can generate multiple related files through a single invocation:

ModelCommand Orchestration Flow

Orchestration Implementation

The orchestration is implemented in ModelCommand31-66:

1. Option Expansion lines 35-42: The --all flag sets multiple option flags
2. Conditional Invocation lines 44-64: Each flag triggers a specific generator
3. Command Calling line 192-198: The call() method uses ArrayInput to invoke other commands

Example invocation from ModelCommand114-118:

Similarly, ModelCommand127-130 shows migration generation, ModelCommand140-143 shows seeder generation, and ModelCommand186-189 shows policy generation.

Sources: src/Generator/ModelCommand.php31-198

---

Configuration Integration

Commands integrate with the Hyperf configuration system to allow customization:

Configuration Points

Configuration Key	Purpose	Default	Used By
devtool.generator.model.namespace	Model class namespace	App\Models	ModelCommand87
devtool.generator.model.stub	Custom model stub path	stubs/model.stub	ModelCommand82
devtool.generator.model.uses	Model base class	Hypervel\Database\Eloquent\Model	ModelCommand75
devtool.generator.factory.path	Factory output directory	database/factories	FactoryCommand73
devtool.generator.factory.model_namespace	Model namespace for factory	App\Models	FactoryCommand32

Commands retrieve configuration via the getConfig() method (provided by GeneratorCommand), which reads from the devtool.generator.<command> configuration namespace.

Sources: src/Generator/ModelCommand.php75-87 src/Generator/FactoryCommand.php32-73

---

Integration with Hyperf Framework

The package integrates with Hyperf at multiple levels:

Integration Points Diagram

Dependency Requirements

The package requires composer.json23-25:

"require": {
 "php": "^8.2",
 "hyperf/devtool": "~3.1.0"
}

The hyperf/devtool dependency provides the GeneratorCommand base class. This is why ConfigProvider43-45 checks for its existence before registering commands.

PSR-4 Autoloading

The package uses PSR-4 autoloading defined in composer.json26-30:

"autoload": {
 "psr-4": {
 "Hypervel\\Devtool\\": "src/"
 }
}

This maps the Hypervel\Devtool namespace to the src/ directory.

Sources: composer.json22-34 src/ConfigProvider.php7-45

---

Output Directory Structure

The package generates files in two primary locations:

Generated File Layout

project-root/
├── app/ # Application code
│ ├── Models/ # make:model
│ │ └── User.php
│ ├── Controller/ # make:controller
│ │ └── UserController.php
│ ├── Middleware/ # make:middleware
│ │ └── AuthMiddleware.php
│ ├── Request/ # make:request
│ │ ├── StoreUserRequest.php
│ │ └── UpdateUserRequest.php
│ ├── Resource/ # make:resource
│ │ └── UserResource.php
│ ├── Policy/ # make:policy
│ │ └── UserPolicy.php
│ └── Exception/ # make:exception
│ └── CustomException.php
│
├── database/
│ ├── factories/ # make:factory
│ │ └── UserFactory.php
│ ├── seeders/ # make:seeder
│ │ └── UserSeeder.php
│ └── migrations/ # Table migration commands
│ ├── 2024_01_01_000000_create_cache_table.php
│ ├── 2024_01_01_000001_create_cache_locks_table.php
│ └── 2024_01_01_000002_create_sessions_table.php

The actual paths are determined by:

• Namespace configuration: ModelCommand87 returns App\Models by default
• Custom path configuration: FactoryCommand73 returns database/factories by default
• Base path resolution: All paths resolve relative to BASE_PATH constant

Sources: src/Generator/ModelCommand.php85-88 src/Generator/FactoryCommand.php71-76

---

Summary

The Hypervel/Devtool package implements a modular, extensible architecture that:

1. Integrates seamlessly with Hyperf through the ConfigProvider pattern and composer metadata
2. Implements fail-safe patterns to gracefully degrade when dependencies are missing
3. Organizes 30+ commands into three logical subsystems (code generators, table generators, utilities)
4. Extends a common base class (GeneratorCommand) to promote code reuse
5. Supports orchestration where commands invoke other commands programmatically
6. Allows extensive configuration through the devtool configuration namespace
7. Generates output to standardized directories following framework conventions

For implementation details of specific patterns, see Command Registration System and Generator Command Architecture.

Sources: All files referenced throughout this document