Task Scheduling

Purpose and Scope

This document explains the task scheduling system in Hypervel Components, which provides a programmatic interface for defining recurring tasks (similar to cron jobs). The scheduler integrates with the Console Kernel to manage command execution on a schedule using cron expression syntax and frequency helpers.

For information about console command registration and discovery, see Console Kernel and Command Discovery. For general service layer management patterns, see Service Layer.

---

Architecture Overview

The scheduling system is built around the Hypervel\Console\Scheduling\Schedule class, which is integrated into the Console Kernel lifecycle. Developers define their application's scheduled tasks by overriding the schedule() method in their kernel class.

Core Components

Component	Class/Interface	Purpose
Kernel	Hypervel\Foundation\Console\Kernel	Manages schedule lifecycle and configuration
Schedule	Hypervel\Console\Scheduling\Schedule	Defines and stores scheduled tasks
Kernel Contract	Hypervel\Foundation\Console\Contracts\Kernel	Defines schedule() interface
Events	Hyperf\Framework\Event\BootApplication	Triggers schedule initialization

Schedule Lifecycle Flow

Sources: src/foundation/src/Console/Kernel.php77-90 src/foundation/src/Console/Kernel.php257-281 src/foundation/src/Console/Contracts/Kernel.php23

Schedule Factory Pattern

The schedule is created using a factory pattern bound to the container at src/foundation/src/Console/Kernel.php276-280:

This pattern ensures that every resolution of Schedule from the container receives:

1. Correct timezone configuration via scheduleTimezone()
2. Correct cache store via scheduleCache()
3. Application-defined tasks via schedule() method

Sources: src/foundation/src/Console/Kernel.php77-90 src/foundation/src/Console/Kernel.php257-281

---

Schedule Definition in Console Kernel

The Console Kernel provides the schedule() method as the primary entry point for defining scheduled tasks. This method receives a fully configured Schedule instance and should be overridden by the application's kernel.

Schedule Method Hierarchy

Method	Signature	Location	Purpose
schedule()	schedule(Schedule $schedule): void	src/foundation/src/Console/Kernel.php257-259	Template method for defining application schedules
resolveConsoleSchedule()	resolveConsoleSchedule(): Schedule	src/foundation/src/Console/Kernel.php264-269	Creates and configures a Schedule instance on-demand
defineConsoleSchedule()	defineConsoleSchedule(): void	src/foundation/src/Console/Kernel.php274-281	Binds Schedule to container during application boot
scheduleTimezone()	scheduleTimezone(): ?string	src/foundation/src/Console/Kernel.php286-291	Resolves timezone for scheduled tasks
scheduleCache()	scheduleCache(): ?string	src/foundation/src/Console/Kernel.php296-299	Resolves cache store for mutex management

Implementation Pattern

The schedule() method is a template method following the Template Method design pattern. The base implementation at src/foundation/src/Console/Kernel.php257-259 is intentionally empty:

Applications extend Hypervel\Foundation\Console\Kernel and override this method:

The schedule() method is called automatically during Schedule resolution at src/foundation/src/Console/Kernel.php267 and src/foundation/src/Console/Kernel.php278

Sources: src/foundation/src/Console/Kernel.php257-259 src/foundation/src/Console/Kernel.php264-269 src/foundation/src/Console/Kernel.php274-281 src/foundation/src/Console/Contracts/Kernel.php23

---

Schedule Configuration

The scheduling system is configured through two primary mechanisms: timezone settings and cache store configuration for mutex management.

Timezone Configuration

The scheduler uses timezone configuration to determine when tasks should execute. The timezone resolution follows this priority chain:

Implementation: src/foundation/src/Console/Kernel.php286-291

The scheduleTimezone() method implementation:

This allows applications to use a different timezone for scheduled tasks than the general application timezone, which is useful for:

• Applications serving multiple time zones
• Centralizing task execution times regardless of server location
• Separating business logic timezone from infrastructure timezone

Cache Store for Mutexes

Scheduled tasks use a cache store to implement mutexes (mutual exclusion locks), which prevent overlapping executions of the same task. The cache store is resolved through:

Implementation: src/foundation/src/Console/Kernel.php296-299

The scheduleCache() method implementation:

Mutex Usage Pattern

Mutexes prevent race conditions when multiple scheduler instances might attempt to run the same task simultaneously. The cache-based mutex works as follows:

1. Before task execution, acquire lock in cache with task identifier
2. If lock exists, skip execution (task already running)
3. Execute task if lock acquired successfully
4. Release lock after task completes or times out

The cache store choice impacts mutex behavior:

Cache Driver	Mutex Characteristics	Use Case
redis	Distributed, persistent	Multi-server deployments
file	Local, persistent	Single-server deployments
array	In-memory, non-persistent	Testing, single-process

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

---

Container Integration

The Schedule instance is bound to the service container during the application boot process, making it available for dependency injection throughout the application.

Schedule Binding Process

The binding occurs in two distinct stages:

Stage 1: Deferred Binding Setup src/foundation/src/Console/Kernel.php87-89

• Kernel constructor registers callback via app->booted()
• Ensures Schedule binding happens after all providers boot
• Delays schedule definition until application is fully initialized

Stage 2: Schedule Factory Registration src/foundation/src/Console/Kernel.php276-280

The factory closure:

1. Creates new Schedule($this->scheduleTimezone())
2. Calls $schedule->useCache($this->scheduleCache())
3. Invokes $this->schedule($schedule) for task definition
4. Returns fully configured Schedule instance

Container Resolution Methods

The Schedule instance can be resolved through multiple approaches:

Resolution Method	Code Example	Use Case
Type Hinting	public function __construct(Schedule $schedule)	Dependency injection in classes
Container Direct	$app->make(Schedule::class)	Manual resolution
Kernel Method	$kernel->resolveConsoleSchedule()	Creating ad-hoc Schedule instances
Array Access	$app[Schedule::class]	Alternative container access

resolveConsoleSchedule() Method

The resolveConsoleSchedule() method at src/foundation/src/Console/Kernel.php264-269 provides direct Schedule creation without container:

This method:

• Creates a fresh Schedule instance each call
• Does not use the container binding
• Useful for testing or creating temporary schedules
• Applies same configuration (timezone, cache, tasks) as container-bound instance

Key Difference: Container-bound Schedule is singleton per resolution cycle, while resolveConsoleSchedule() always creates new instance.

Sources: src/foundation/src/Console/Kernel.php77-90 src/foundation/src/Console/Kernel.php264-281

---

Integration Points with Console Kernel

The scheduling system integrates with the Console Kernel at multiple lifecycle points, ensuring proper initialization and configuration.

Kernel Lifecycle Integration

Bootstrap Sequence

The Console Kernel defines its bootstrap sequence at src/foundation/src/Console/Kernel.php71-75:

The Schedule definition occurs after all bootstrappers have executed, ensuring:

• All service providers are registered
• All service providers are booted
• Application configuration is fully loaded
• Cache drivers are available for mutex storage

Kernel Method Summary

Method	Visibility	Line Reference	Purpose
__construct()	public	77-90	Initialize kernel, register schedule callback
schedule()	public	257-259	Template method for task definition
resolveConsoleSchedule()	public	264-269	Create configured Schedule instance
defineConsoleSchedule()	protected	274-281	Bind Schedule to container
scheduleTimezone()	protected	286-291	Resolve timezone configuration
scheduleCache()	protected	296-299	Resolve cache store configuration

Sources: src/foundation/src/Console/Kernel.php71-90 src/foundation/src/Console/Kernel.php257-299

---

Configuration Reference

Application Configuration

The scheduling system reads configuration from the application's config/app.php file:

Configuration Key	Type	Default	Purpose
app.schedule_timezone	`string	null`	null
app.timezone	string	System default	Application-wide timezone, used as fallback

Cache Configuration

Mutex storage configuration is read from config/cache.php:

Configuration Key	Type	Default	Purpose
cache.schedule_store	`string	null`	null

Environment Variables

The scheduler supports the following environment variable:

Variable	Type	Purpose
SCHEDULE_CACHE_DRIVER	`string	null`

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

---

Extension and Customization

Applications can customize the scheduling system by extending the Console Kernel and overriding specific methods. The kernel provides several template methods designed for customization.

Customization Points

Common Customization Patterns

1. Environment-Based Timezone

Different environments may require different task execution times:

2. Environment-Based Cache Store

Different environments may need different mutex strategies:

3. Dynamic Schedule Definition

Conditional task registration based on configuration:

4. Integrating Scheduled Tasks with Commands

The kernel's commands() method can register commands that are then scheduled:

Advanced Customization: Custom Schedule Resolution

For complete control over Schedule creation, override resolveConsoleSchedule():

Sources: src/foundation/src/Console/Kernel.php257-259 src/foundation/src/Console/Kernel.php264-269 src/foundation/src/Console/Kernel.php286-299 src/foundation/src/Console/Kernel.php304-306

---

Related Systems

The task scheduling system integrates with several other Hypervel subsystems:

System	Relationship	Reference Page
Console Kernel	Parent system managing command lifecycle	4.1
Cache System	Provides mutex storage for overlap prevention	5.1
Service Container	Manages Schedule instance lifecycle	2.1
Configuration Management	Provides timezone and cache settings	2.3

Sources: src/foundation/src/Console/Kernel.php1-438