Task Scheduling

Purpose and Scope

This document explains the task scheduling integration within Hypervel's Console Kernel. Task scheduling in Hypervel allows applications to define recurring console commands and jobs that execute on a schedule. The scheduling system is provided by the hypervel/console package, and the Foundation package provides the integration points, configuration resolution, and lifecycle management.

For information about console command registration and execution, see Console Kernel and Command Execution. For command discovery mechanisms, see Command Discovery and Registration.

Sources: src/Console/Kernel.php1-438

---

Schedule Definition Interface

Applications define their scheduled tasks by extending the Console Kernel and overriding the schedule() method. This method receives a Schedule instance and allows the application to register recurring tasks using the schedule's fluent API.

The schedule() method is defined in both the contract and concrete implementation:

Component	Location	Default Behavior
Contract Method	src/Console/Contracts/Kernel.php23	Defines the interface signature
Concrete Method	src/Console/Kernel.php257-259	Empty implementation (no-op)
Schedule Class	Hypervel\Console\Scheduling\Schedule	Provided by hypervel/console package

Applications typically define schedules in App\Console\Kernel by overriding the method:

Sources: src/Console/Kernel.php257-259 src/Console/Contracts/Kernel.php23

---

Schedule Instance Resolution

The Console Kernel creates and configures Schedule instances through two related methods: resolveConsoleSchedule() and defineConsoleSchedule().

Schedule Resolution Method

The resolveConsoleSchedule() method creates a new Schedule instance with timezone and cache configuration applied:

resolveConsoleSchedule() → new Schedule(timezone) → useCache(store) → return

This method:

1. Creates a Schedule instance with the configured timezone from scheduleTimezone()
2. Calls useCache() with the cache store from scheduleCache()
3. Invokes the application's schedule() method to register tasks
4. Returns the configured Schedule instance

Sources: src/Console/Kernel.php264-269

Container Binding

The defineConsoleSchedule() method registers the Schedule class in the dependency injection container. This binding is established during the kernel's construction lifecycle:

The binding occurs in the app->booted() callback, ensuring that all service providers have been registered and booted before the schedule is defined. The container binding uses a factory closure that creates a fresh Schedule instance each time it's resolved.

Sources: src/Console/Kernel.php77-90 src/Console/Kernel.php274-281

---

Timezone Configuration

The schedule system allows configuring the timezone used for evaluating scheduled task timing. The scheduleTimezone() method resolves the timezone from application configuration with a fallback hierarchy.

Configuration Resolution

Timezone Configuration Hierarchy

Priority	Configuration Key	Description
1 (highest)	app.schedule_timezone	Schedule-specific timezone override
2 (fallback)	app.timezone	Application default timezone
3 (default)	null	Uses PHP's default timezone

The timezone is read from the application's configuration during Schedule instantiation. If no specific schedule timezone is configured, the application's general timezone setting is used.

Sources: src/Console/Kernel.php286-291

---

Cache Configuration for Scheduling Mutexes

The scheduling system uses a cache store to manage mutexes that prevent overlapping task execution. The scheduleCache() method resolves which cache store to use.

Cache Store Resolution

Cache Configuration Sources

Priority	Source	Configuration Method	Default
1 (highest)	cache.schedule_store	Configuration file	N/A
2 (fallback)	SCHEDULE_CACHE_DRIVER	Environment variable	N/A
3 (default)	null	None specified	Default cache driver

When a cache store is specified, the Schedule instance uses it to coordinate task execution across multiple servers or processes. The useCache() method is called during schedule initialization to configure this behavior.

Sources: src/Console/Kernel.php296-299

---

Schedule Initialization Lifecycle

The schedule initialization occurs during the Console Kernel's construction and follows a specific lifecycle to ensure proper timing relative to the application bootstrap process.

Initialization Flow

Lifecycle Stages

Stage	Method/Event	Description
1. Kernel Construction	Kernel::__construct()	Kernel instance created
2. Boot Event	BootApplication dispatched	Signals bootstrap start
3. Booted Callback	app->booted(callable)	Registers deferred callback
4. Bootstrap Complete	Providers all booted	Application ready
5. Schedule Binding	defineConsoleSchedule()	Schedule class bound to container

The schedule is not immediately created during kernel construction. Instead, the binding is registered in a deferred callback that executes after the application has fully booted. This ensures that all configuration and services are available when the schedule is accessed.

Sources: src/Console/Kernel.php77-90 src/Console/Kernel.php274-281

---

Schedule Method Invocation

The application's schedule() method is invoked automatically when the Schedule instance is resolved from the container or explicitly created through resolveConsoleSchedule(). The method receives a fully configured Schedule instance.

Method Signature and Contract

Applications override this method to define their scheduled tasks. The Schedule instance passed to this method has already been configured with:

• The application's schedule timezone
• The cache store for mutex management

Configuration Application Flow

The schedule() method is called as part of the factory function that creates Schedule instances, ensuring that application-defined tasks are registered whenever a Schedule instance is created.

Sources: src/Console/Kernel.php257-259 src/Console/Kernel.php264-269 src/Console/Kernel.php277-278

---

Complete Configuration and Integration Diagram

This diagram illustrates the complete flow from configuration sources through kernel methods to Schedule instance creation. Configuration values are resolved through the scheduleTimezone() and scheduleCache() methods, which implement fallback hierarchies. The Schedule instance is created via a container binding that's registered during application boot, and the application's schedule() method is invoked to register tasks.

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

---

Key Integration Points Summary

Integration Point	Method	Purpose
Schedule Definition	schedule(Schedule $schedule)	Override to register scheduled tasks
Container Binding	defineConsoleSchedule()	Binds Schedule class to container
Instance Creation	resolveConsoleSchedule()	Creates configured Schedule instance
Timezone Resolution	scheduleTimezone()	Determines timezone for schedule evaluation
Cache Resolution	scheduleCache()	Determines cache store for mutexes

The scheduling integration is designed to be extended by applications while providing sensible defaults and clear configuration points. All schedule-related methods are protected, allowing subclasses to customize behavior while maintaining the framework's contract.

Sources: src/Console/Kernel.php257-299 src/Console/Contracts/Kernel.php23