Last indexed: 7 February 2026 (47f772)

Package Structure and Dependencies

Purpose and Scope

This document details the structural organization and dependency architecture of the hypervel/console package. It covers all required and optional dependencies, explains integration points with the Hyperf framework, documents relationships to the Hypervel ecosystem packages, and describes the package's autoloading and registration mechanisms.

For information about specific console commands registered by this package, see Schedule Management Commands. For details on the application bootstrap lifecycle, see Application System.

Package Identity and Namespace

The package is identified as hypervel/console and provides console and task scheduling functionality for applications built on the Hypervel framework. The package uses PSR-4 autoloading with the namespace Hypervel\Console mapped to the src/ directory composer.json22-26

Package Metadata:

Property	Value
Package Name	`hypervel/console`
Package Type	`library`
PHP Requirement	`^8.2`
Root Namespace	`Hypervel\Console`
Autoload Directory	`src/`
License	MIT

Sources: composer.json1-26

Dependency Architecture Overview

The package's dependency structure follows a three-tier architecture: framework foundation, ecosystem integration, and specialized libraries. This layered approach ensures separation of concerns while enabling tight integration with the Hypervel ecosystem.

Diagram: Complete Dependency Graph

The package depends on seven required libraries and suggests two optional packages for enhanced functionality.

Sources: composer.json27-42

Core Framework Dependencies

Symfony Console Foundation

The package requires symfony/console with flexible version support spanning Symfony 5.4, 6.4, and 7.0 composer.json36 This provides the foundational console component including:

Input/output abstractions
Command definition interfaces
Helper utilities
Formatter components

Version Constraint: ^5.4|^6.4|^7.0 - allows major version upgrades within LTS releases.

Hyperf Command Layer

The hyperf/command package (~3.1.0) extends Symfony Console with Hyperf-specific functionality composer.json30:

Integration with Hyperf's dependency injection container
Coroutine-aware command execution
Event dispatcher integration
Configuration and discovery mechanisms

Version Constraint: ~3.1.0 - equivalent to >=3.1.0 <3.2.0, pinned to Hyperf 3.1.x series.

The base Command class in this package extends the Hyperf command implementation, inheriting container resolution and coroutine execution capabilities.

Sources: composer.json30-36

Hypervel Ecosystem Integration

The package requires four sibling packages from the Hypervel ecosystem, all pinned to version ^0.3 composer.json31-34:

Package Relationships Table

Package	Version	Primary Usage in Console Package
`hypervel/foundation`	`^0.3`	Application container, kernel interfaces, event system
`hypervel/cache`	`^0.3`	Mutex storage for `withoutOverlapping()` and `onOneServer()`
`hypervel/queue`	`^0.3`	Job dispatching via `Schedule::job()` method
`hypervel/coroutine`	`^0.3`	Async execution in background tasks and concurrent processing

Diagram: Ecosystem Package Usage by Core Components

hypervel/foundation

Provides the application foundation layer used throughout the package:

Container abstraction for dependency resolution
Kernel interfaces for command execution
Event dispatcher for lifecycle hooks
Base application contracts

The Command class uses the foundation's container to resolve dependencies in the handle() method. The Application class extends foundation contracts for kernel integration.

hypervel/cache

Critical for scheduling concurrency control:

EventMutex implementations use cache to store locks for withoutOverlapping()
SchedulingMutex implementations use cache for onOneServer() coordination
ScheduleStopCommand uses cache to signal scheduler shutdown
Lock lifecycle management (create, check, forget operations)

The default implementations (CacheEventMutex, CacheSchedulingMutex) rely on cache stores for distributed lock management.

hypervel/queue

Enables queue-based task execution:

Schedule::job() method dispatches queue jobs
Allows scheduled tasks to run asynchronously outside the scheduler process
Provides integration between scheduling and job queue systems

hypervel/coroutine

Powers asynchronous execution capabilities:

Command class supports coroutine execution mode
ScheduleRunCommand uses Concurrent for background task pools
Enables non-blocking I/O in command execution
Provides context isolation for concurrent tasks

Sources: composer.json31-34

External Library Dependencies

GuzzleHTTP Client

Package: guzzlehttp/guzzle
Version: ^7.8.2
Purpose: HTTP client for scheduled task callbacks composer.json29

The Event class uses Guzzle to ping URLs when the pingBefore() or thenPing() methods are configured on a scheduled task. This enables HTTP-based health checks and webhooks as part of task lifecycle.

Common Usage Pattern:

Event::pingBefore('https://example.com/webhook')
 ->thenPing('https://example.com/complete')

Cron Expression Parser

Package: dragonmantank/cron-expression
Version: ^3.3.2
Purpose: Parse and evaluate cron schedule expressions composer.json35

The ManagesFrequencies trait generates cron expression strings (e.g., "0 0 * * *" for daily), and the Event::isDue() method uses this library to evaluate whether a task should run at the current time. This is the core scheduling logic that determines task execution timing.

Integration Point: Every method in ManagesFrequencies ultimately sets the expression property on Event, which is evaluated using Cron\CronExpression::factory().

Signal Handling

Package: friendsofhyperf/command-signals
Version: ~3.1.0
Purpose: Graceful signal handling for long-running commands composer.json37

Enables proper cleanup and graceful shutdown when commands receive SIGTERM, SIGINT, or other signals. Critical for the ScheduleRunCommand daemon mode to handle stop requests cleanly.

Sources: composer.json29-37

Optional Dependencies

The package suggests two optional dependencies for enhanced functionality composer.json39-42:

hypervel/prompt

Requirement Context: Required for schedule:test command
Purpose: Interactive command-line prompts and selection interfaces

The ScheduleTestCommand uses this package to provide interactive testing of scheduled tasks, allowing developers to select which task to test and view execution details.

friendsofhyperf/pretty-console

Requirement Context: Required for schedule:run command output
Version: ~3.1.0
Purpose: Enhanced console output formatting

Provides styled output and progress indicators for the scheduler daemon, making it easier to monitor running scheduled tasks in real-time.

Sources: composer.json39-42

Package Discovery and Registration

The package integrates with Hyperf's configuration discovery system through the ConfigProvider class composer.json47-49

ConfigProvider Implementation

Diagram: Configuration Discovery and Command Registration Flow

The ConfigProvider class returns an array with a commands key listing all command classes to register src/ConfigProvider.php15-26:

Command Class	Command Name	Primary Function
`ScheduleListCommand`	`schedule:list`	Display all scheduled tasks
`ScheduleRunCommand`	`schedule:run`	Execute the scheduler daemon
`ScheduleStopCommand`	`schedule:stop`	Signal scheduler to stop
`ScheduleClearCacheCommand`	`schedule:clear-cache`	Clear scheduling cache
`ScheduleTestCommand`	`schedule:test`	Interactively test tasks

Discovery Mechanism

The Hyperf framework automatically:

Reads composer.json extra configuration composer.json46-49
Locates the ConfigProvider class specified in extra.hyperf.config
Invokes the ConfigProvider::__invoke() method src/ConfigProvider.php15
Merges returned configuration into application config
Registers all classes listed under the commands key

This zero-configuration approach ensures all schedule management commands are available immediately upon package installation.

Sources: composer.json46-49 src/ConfigProvider.php1-27

Dependency Version Strategy

The package employs different version constraint strategies based on dependency type:

Version Constraint Table

Dependency Type	Constraint Example	Strategy	Rationale
PHP	`^8.2`	Minimum version	Requires modern language features
Hyperf packages	`~3.1.0`	Minor lock	Tight coupling to framework version
Symfony Console	`^5.4\|^6.4\|^7.0`	LTS ranges	Supports multiple Symfony LTS releases
Hypervel ecosystem	`^0.3`	Major version	Allows minor updates within v0.x
External libraries	`^7.8.2`, `^3.3.2`	Caret range	Allows non-breaking updates

The tilde (~) constraint for Hyperf packages (~3.1.0) restricts updates to patch releases only, ensuring compatibility with the specific Hyperf minor version. The caret (^) constraint for ecosystem packages (^0.3) allows any version >=0.3.0 <1.0.0, providing flexibility during the pre-1.0 development phase.

Sources: composer.json27-37

Package Metadata and Distribution

Repository Configuration

Property	Value
Issue Tracker	https://github.com/hypervel/components/issues
Source Repository	https://github.com/hypervel/components
Branch Alias	`dev-main` → `0.3-dev`

The package is distributed as part of the hypervel/components monorepo composer.json18-20 The branch alias configuration maps the dev-main branch to 0.3-dev for Composer resolution composer.json50-52

Autoloading Structure

Diagram: PSR-4 Namespace to Directory Mapping

The PSR-4 autoloading configuration composer.json22-26 maps the root namespace Hypervel\Console to the src/ directory, following standard PHP package conventions.

Sources: composer.json18-26 composer.json50-52

Refresh this wiki

URL: https://deepwiki.com/hypervel/console/2-package-structure-and-dependencies