Overview

The hypervel/console package provides a console application framework with advanced task scheduling capabilities for the Hypervel ecosystem. Built on Hyperf and Symfony Console, it extends base console functionality with a sophisticated scheduler, command lifecycle management, and distributed execution coordination.

Package Identification

Property	Value
Package Name	hypervel/console
Type	Library
Namespace	Hypervel\Console
PHP Requirement	^8.2
License	MIT
Source Repository	https://github.com/hypervel/components

Sources: composer.json1-21

Package Overview

The package serves two primary functions:

1. Console Command Infrastructure: Enhanced command base classes with coroutine support, event dispatching, and dependency injection
2. Task Scheduling System: Cron-based scheduler with distributed mutex coordination, overlap prevention, and background execution

The scheduling system is the most critical subsystem, with the Event class (importance: 9.54) and Schedule class (importance: 8.99) forming the core architecture.

Dependencies

Required Dependencies

Dependency	Purpose	Version
php	Runtime environment	^8.2
hyperf/command	Base command infrastructure from Hyperf	~3.1.0
symfony/console	Symfony console I/O and command framework	^5.4|^6.4|^7.0
dragonmantank/cron-expression	Cron expression parsing and evaluation	^3.3.2
guzzlehttp/guzzle	HTTP client for webhook pinging	^7.8.2
friendsofhyperf/command-signals	Signal handling for graceful shutdown	~3.1.0
hypervel/foundation	Core Hypervel framework components	^0.3
hypervel/cache	Cache abstraction for mutex storage	^0.3
hypervel/queue	Queue integration for job scheduling	^0.3
hypervel/coroutine	Coroutine support for async execution	^0.3

Optional Dependencies

Dependency	Purpose	Version
hypervel/prompt	Interactive prompts for schedule:test	Not specified
friendsofhyperf/pretty-console	Enhanced output formatting for schedule:run	~3.1.0

Sources: composer.json27-42

High-Level Architecture

System Component Map

This diagram maps the major subsystems to their implementing classes and shows dependencies between components.

Sources: composer.json27-37 src/ConfigProvider.php1-27

Core Subsystems

Scheduling System (Primary Component)

The scheduling system is the most important subsystem, comprising:

Class	Location	Importance	Responsibility
Event	src/Scheduling/Event.php	9.54	Represents a scheduled task with cron expression, callbacks, and execution logic
Schedule	src/Scheduling/Schedule.php	8.99	Registry for events; determines which events are due to run
CallbackEvent	src/Scheduling/CallbackEvent.php	-	Subclass of Event for closure-based tasks
ManagesFrequencies	src/Scheduling/ManagesFrequencies.php	2.13	Trait providing fluent API for cron expressions (daily(), hourly(), etc.)
ManagesAttributes	src/Scheduling/ManagesAttributes.php	-	Trait for configuring execution attributes (environments, maintenance mode, etc.)

Key scheduling features:

• Cron expression evaluation using dragonmantank/cron-expression
• Distributed coordination via EventMutex and SchedulingMutex contracts
• Overlap prevention with cache-based locking
• Background execution with coroutine pool management
• Before/after callbacks with success/failure handling
• Webhook pinging via Guzzle HTTP client

Command Execution Layer

Class	Location	Importance	Responsibility
Command	src/Command.php	5.32	Base command class extending Hyperf\Command\Command with lifecycle events
Application	src/Application.php	3.56	Console application extending Symfony\Component\Console\Application
CommandReplacer	src/CommandReplacer.php	3.80	Implements command aliasing (e.g., gen:* → make:*)
ClosureCommand	src/ClosureCommand.php	-	Wraps PHP closures as executable commands

Key command features:

• Event dispatching at lifecycle points (BeforeHandle, AfterHandle, AfterExecute)
• Coroutine execution support via hypervel/coroutine
• Signal handling for graceful shutdown
• Dependency injection via Hyperf container
• Output redirection and context management

Schedule Management Commands

These commands are registered in ConfigProvider and provide scheduler interaction:

Command	Class	Importance	Purpose
schedule:run	ScheduleRunCommand	4.13	Executes the scheduler in daemon or one-time mode
schedule:list	ScheduleListCommand	2.13	Displays all registered scheduled tasks
schedule:test	ScheduleTestCommand	-	Interactively tests schedule definitions
schedule:stop	ScheduleStopCommand	-	Gracefully stops the scheduler daemon
schedule:clear-cache	ScheduleClearCacheCommand	-	Clears scheduler cache and mutex locks

Sources: src/ConfigProvider.php1-27

Concurrency Contracts

Interface	Location	Purpose
EventMutex	src/Contracts/EventMutex.php	Prevents overlapping executions of the same event
SchedulingMutex	src/Contracts/SchedulingMutex.php	Ensures single-server execution across distributed systems
CacheAware	src/Contracts/CacheAware.php	Configures cache store for mutex implementations

Default implementations use hypervel/cache for storing locks, enabling horizontal scalability.

Framework Integration

Dependency Layering

The package integrates with frameworks through a layered architecture:

Hyperf Integration Points

The package integrates with Hyperf through:

• Service Discovery: ConfigProvider registers commands via Hyperf's discovery mechanism
• Dependency Injection: Command::execute() uses Hyperf\Context\ApplicationContext to resolve dependencies
• Event System: Commands dispatch lifecycle events (BeforeHandle, AfterHandle, AfterExecute)
• Container Resolution: Application resolves command instances through Hyperf's container

Symfony Console Extension

The package extends Symfony Console:

• Application extends Symfony\Component\Console\Application
• Command indirectly extends Symfony\Component\Console\Command\Command through Hyperf\Command\Command
• Uses Symfony's InputInterface and OutputInterface for I/O
• Supports Symfony's helper set and formatter systems

Sources: composer.json27-37

Key Capabilities

Task Scheduling Features

• Cron Expression Support: Full cron syntax with second-level precision
• Distributed Coordination: Multi-server scheduling with mutex-based coordination
• Overlap Prevention: Configurable execution overlap detection and prevention
• Background Execution: Asynchronous task execution with coroutine support
• Conditional Execution: Filter-based conditional task execution

Command Management Features

• Dynamic Commands: Runtime command creation via closures
• Command Aliasing: Flexible command name transformation and aliasing
• Enhanced Lifecycle: Event-driven command execution with comprehensive error handling
• Interactive Testing: Built-in tools for schedule development and debugging

Framework Integration Features

• Container Integration: Full Hyperf dependency injection support
• Context Management: Coroutine-aware context handling
• Event System: Comprehensive lifecycle event dispatching
• Configuration Management: Streamlined service registration and discovery

For detailed documentation on each subsystem, see the respective sections: Task Scheduling System covers the core scheduling functionality, Command System details the command infrastructure, Application System explains the application management layer, and Configuration and Setup covers integration and setup procedures.

Sources: composer.json1-52 README.md1-4