Console Kernel and Command Discovery

Purpose and Scope

The Console Kernel is the central orchestrator for Hypervel's command-line interface. It manages command discovery, registration, bootstrapping, and execution of Artisan console commands. This system supports multiple command sources including directory scanning, configuration files, annotations, and closures, providing flexibility in how commands are defined and loaded.

For information about task scheduling, see Task Scheduling. For code generation commands, see Code Generation and Development Tools.

---

Kernel Architecture

The Kernel class implements the KernelContract interface and serves as the application's console entry point. It manages the entire console lifecycle from bootstrapping to command execution.

Core Responsibilities

Responsibility	Description
Bootstrapping	Initializes the application for console use via defined bootstrappers
Command Discovery	Scans multiple sources to locate available commands
Command Registration	Registers discovered commands with the Artisan application
Schedule Management	Resolves and configures the task scheduler
Execution	Delegates command execution to the Artisan application

Key Properties

Kernel Properties (src/foundation/src/Console/Kernel.php)
├── $artisan - The Artisan console application instance
├── $commands - Explicitly registered command classes
├── $closureCommands - Closure-based commands
├── $commandPaths - Directories to scan for commands
├── $commandRoutePaths - Files defining closure commands
├── $loadedPaths - Paths that have been scanned
├── $commandsLoaded - Flag indicating if commands are loaded
└── $bootstrappers - Application bootstrapper classes

Sources: src/foundation/src/Console/Kernel.php36-76

---

Command Discovery Architecture

Diagram: Multi-Source Command Discovery Flow

The kernel aggregates commands from six distinct sources, merges them, applies priority ordering, and registers them with the Artisan application.

Sources: src/foundation/src/Console/Kernel.php103-120 src/foundation/src/Console/Kernel.php149-192

---

Command Discovery Mechanisms

1. Directory Scanning

The kernel scans specified directories using ReflectionManager to find command classes. Directories are added via addCommandPaths() or the $commandPaths property.

Discovery via load() method:
├── Paths normalized to existing directories
├── ReflectionManager::getAllClasses() scans paths
├── Classes filtered to SymfonyCommand subclasses
└── Results merged into command collection

Key Methods:

• load(array|string $paths) - Adds paths to scan src/foundation/src/Console/Kernel.php332-347
• getLoadedPaths() - Returns scanned paths src/foundation/src/Console/Kernel.php352-355

2. Configuration-Based Discovery

Commands can be explicitly listed in the commands configuration key. The kernel retrieves these via ConfigInterface.

Sources: src/foundation/src/Console/Kernel.php158-160

3. Annotation-Based Discovery

If Hyperf's annotation system is available, commands marked with @Command annotations are automatically discovered via AnnotationCollector.

Annotation Discovery:
├── Check for AnnotationCollector class
├── AnnotationCollector::getClassesByAnnotation(AnnotationCommand::class)
├── Extract class names from annotation results
└── Reflect classes for registration

Sources: src/foundation/src/Console/Kernel.php163-169

4. Command Route Files

The kernel can load files that define closure-based commands. These files are executed during discovery, allowing dynamic command registration.

Route File Loading:
├── Paths specified in commandRoutePaths
├── File existence check
├── require statement executes file
└── File typically calls $kernel->command()

Sources: src/foundation/src/Console/Kernel.php139-143

5. Closure Commands

Commands can be registered dynamically using closures via the command() method. These are stored separately and registered during the collection phase.

Closure Command Registration:
├── ClosureCommand instance created
├── Assigned unique ID via spl_object_hash()
├── Bound to container with "commands.{hash}" key
└── Added to collection for registration

Sources: src/foundation/src/Console/Kernel.php311-327

6. Explicit Command Registration

Commands can be registered directly via the addCommands() method, providing fine-grained control over available commands.

Sources: src/foundation/src/Console/Kernel.php360-369

---

Command Collection and Registration

Diagram: Command Collection and Registration Sequence

The kernel collects commands from all sources, applies priority ordering (Hyperf framework commands first), resolves instances from the container, and registers them with Artisan.

Sources: src/foundation/src/Console/Kernel.php149-214

---

Command Priority and Ordering

The kernel implements a priority system to ensure framework commands load before application commands. This allows application commands to override framework commands with the same name.

Priority Algorithm

Command Sorting (loadCommands method):
1. Split commands into two arrays:
 ├── Hyperf\* namespace → hyperfCommands
 └── All others → otherCommands
2. Merge arrays: hyperfCommands + otherCommands
3. Register in merged order

Rationale: Framework commands register first, then application commands. When commands share a name, the last-registered wins, allowing applications to override framework defaults.

Sources: src/foundation/src/Console/Kernel.php198-208

---

Closure Commands

Closure commands provide a lightweight way to define simple commands without creating dedicated class files.

Registration API

Implementation Details

Aspect	Implementation
Class	ClosureCommand wraps the closure
Storage	$closureCommands array during loading
Container Key	commands.{spl_object_hash}
Registration Timing	Immediate if loaded, deferred otherwise

Lazy vs Immediate Registration

If commandsLoaded = false:
├── Store in closureCommands array
└── Register during collectCommands()

If commandsLoaded = true:
├── Create container binding immediately
└── Call registerCommand() directly

This dual approach ensures closure commands work whether registered before or after bootstrap.

Sources: src/foundation/src/Console/Kernel.php311-327 src/foundation/src/Console/Kernel.php182-187

---

Bootstrap Process

Diagram: Console Kernel Bootstrap Sequence

The kernel bootstraps in two phases: application bootstrapping (if needed) and command loading. Discovery only occurs if shouldDiscoverCommands() returns true.

Bootstrap Components

Application Bootstrappers src/foundation/src/Console/Kernel.php71-75:

1. RegisterFacades - Initializes facade system
2. RegisterProviders - Registers service providers
3. BootProviders - Boots registered providers

Discovery Condition: The kernel only auto-discovers commands when the kernel class is Kernel itself (not a subclass). Subclasses override shouldDiscoverCommands() to control this behavior src/foundation/src/Console/Kernel.php125-128

Sources: src/foundation/src/Console/Kernel.php77-90 src/foundation/src/Console/Kernel.php103-120 src/foundation/src/Console/Kernel.php400-417

---

Integration with Artisan Application

The kernel creates and manages a ConsoleApplication instance (the "Artisan" application) which handles actual command execution.

Artisan Lifecycle

Diagram: Artisan Application Initialization

Key Integration Points

Method	Purpose
getArtisan()	Lazy-loads the Artisan application instance
setArtisan()	Allows external Artisan instance injection
call()	Executes command by name
all()	Retrieves all registered commands
output()	Gets output from last command execution

Container Command Loader

The Artisan application uses a container-based command loader, allowing commands to be resolved lazily from the DI container. This enables dependency injection into command constructors.

Sources: src/foundation/src/Console/Kernel.php402-417 src/foundation/src/Console/Kernel.php233-236 src/foundation/src/Console/Kernel.php241-244

---

Kernel Interface Contract

The KernelContract interface defines the public API for console kernel implementations.

Primary Operations

Method Signature	Purpose
bootstrap(): void	Bootstrap application for console use
schedule(Schedule): void	Define scheduled tasks (override in subclass)
commands(): void	Register application commands (override in subclass)
command(string, Closure): ClosureCommand	Register closure command
load(array|string): void	Add command scan paths
addCommands(array): static	Add explicit command classes
addCommandPaths(array): static	Add directory scan paths
addCommandRoutePaths(array): static	Add route file paths
getLoadedPaths(): array	Get scanned paths
registerCommand(string): void	Register single command
call(string, array, ?OutputInterface)	Execute command by name
all(): array	Get all registered commands
output(): string	Get last command output
getArtisan(): ApplicationContract	Get Artisan instance
setArtisan(ApplicationContract): void	Set Artisan instance

Sources: src/foundation/src/Console/Contracts/Kernel.php13-97

---

Extending the Kernel

Applications typically extend the Kernel class to customize command loading and scheduling.

Extension Pattern

Discovery Control

Subclasses automatically disable auto-discovery src/foundation/src/Console/Kernel.php125-128 This prevents accidental command loading and gives full control to the application.

Sources: src/foundation/src/Console/Kernel.php41-56 src/foundation/src/Console/Kernel.php304-306 src/foundation/src/Console/Kernel.php257-259

---

Schedule Integration

The kernel manages integration with the task scheduler, resolving Schedule instances with proper configuration.

Schedule Resolution

Schedule Creation:
├── Timezone from config('app.schedule_timezone') or config('app.timezone')
├── Cache store from config('cache.schedule_store') or env('SCHEDULE_CACHE_DRIVER')
├── Pass to Schedule constructor
└── Call schedule() method for user configuration

The kernel binds the Schedule class in the container, allowing commands and services to access the schedule configuration.

Sources: src/foundation/src/Console/Kernel.php264-299

---

Summary

The Console Kernel provides a sophisticated command discovery and registration system supporting multiple input sources. Key features include:

• Multi-source discovery: Directories, configuration, annotations, route files, closures, explicit registration
• Priority ordering: Framework commands load before application commands
• Lazy loading: Commands resolved from container on-demand
• Flexible extension: Override discovery, registration, and scheduling in subclasses
• Schedule integration: Automatic timezone and cache configuration
• Bootstrap management: Ensures proper application initialization

The kernel serves as the bridge between the application container, command implementations, and the Symfony Console foundation, providing a Laravel-compatible API for console interactions.

Sources: src/foundation/src/Console/Kernel.php src/foundation/src/Console/Contracts/Kernel.php