Task Scheduling System

Purpose and Scope

This document provides a high-level overview of the task scheduling system in the hypervel/console package. The scheduling system allows developers to define and execute recurring tasks using a fluent API with cron-like expressions. This page covers the core architecture, key components, and execution flow.

For detailed information about specific aspects of the scheduling system, see:

• Schedule event registration and management: Schedule Registry
• Event execution details and lifecycle hooks: Event Execution and Lifecycle
• Cron expression building and frequency definitions: Defining Schedule Frequencies
• Event configuration options: Execution Attributes and Configuration
• Overlap prevention and multi-server coordination: Concurrency and Mutex Management
• Running the scheduler daemon: Running the Scheduler
• Management commands for inspecting and controlling schedules: Schedule Management Commands

Overview

The task scheduling system provides a programmatic way to define recurring tasks that run at specified intervals. Instead of managing multiple cron entries, developers define all scheduled tasks in code using a fluent API. The system supports:

• Command scheduling (both console commands and system shell commands)
• Closure/callback scheduling
• Job dispatching (queue integration)
• Flexible frequency definitions (hourly, daily, weekly, custom cron expressions)
• Concurrency control (prevent overlapping executions)
• Multi-server coordination (single-server execution)
• Conditional execution based on filters and environments

The scheduler runs as either a long-running daemon or in one-time mode (suitable for system cron integration).

Sources: src/Scheduling/Schedule.php1-413 src/Scheduling/Event.php1-738

Core Architecture

Component Overview

The scheduling system consists of two primary classes that work together:

Sources: src/Scheduling/Schedule.php32-118 src/Scheduling/Event.php35-104

Class Responsibilities

Class	Purpose	Location
Schedule	Central registry that manages collections of scheduled events. Provides factory methods for creating different task types.	src/Scheduling/Schedule.php32
Event	Represents a single scheduled task with its cron expression, command, callbacks, and configuration.	src/Scheduling/Event.php35
CallbackEvent	Specialized event for executing PHP closures.	Referenced in src/Scheduling/Schedule.php123-135
ManagesFrequencies	Trait providing fluent API for building cron expressions (daily, hourly, etc.).	src/Scheduling/Event.php39
ManagesAttributes	Trait providing configuration methods (environments, maintenance mode, user context).	src/Scheduling/Event.php38
EventMutex	Contract for preventing overlapping executions of the same event.	src/Scheduling/Event.php21
SchedulingMutex	Contract for single-server execution coordination.	src/Scheduling/Schedule.php18

Sources: src/Scheduling/Schedule.php32-118 src/Scheduling/Event.php35-104

Task Registration Flow

Creating Scheduled Tasks

The Schedule class provides factory methods for registering different types of tasks:

Sources: src/Scheduling/Schedule.php123-153 src/Scheduling/Schedule.php273-286

Task Types

The Schedule class supports four primary task types:

Method	Task Type	Description	Example
call()	Closure	Executes a PHP closure	$schedule->call(fn() => cleanup())->hourly()
command()	Console Command	Runs a registered console command	$schedule->command('emails:send')->daily()
job()	Queue Job	Dispatches a job to the queue	$schedule->job(new ProcessPodcast)->everyFiveMinutes()
exec()	System Command	Executes a shell command	$schedule->exec('node script.js')->everyMinute()

Sources: src/Scheduling/Schedule.php123-178 src/Scheduling/Schedule.php239-250

Event Lifecycle and Execution

Eligibility Determination

Before an event executes, it passes through multiple gates to determine eligibility:

Sources: src/Scheduling/Event.php247-309 src/Scheduling/Event.php129-133 src/Scheduling/Schedule.php331-334

Execution Process

Once an event is eligible, it follows this execution sequence:

Sources: src/Scheduling/Event.php111-124 src/Scheduling/Event.php156-196 src/Scheduling/Event.php213-222

Code-to-Concept Mapping

Key Classes and Their Roles

Sources: src/Scheduling/Schedule.php123-250 src/Scheduling/Event.php35-738

Property and State Management

The Event class maintains several key properties that control execution:

Property	Type	Purpose	Set By
command	?string	Command or closure identifier	Constructor src/Scheduling/Event.php98
expression	string	Cron expression defining schedule	ManagesFrequencies trait methods
mutex	EventMutex	Mutex implementation for overlap prevention	Constructor src/Scheduling/Event.php97
withoutOverlapping	bool	Whether to prevent overlapping executions	withoutOverlapping() method
onOneServer	bool	Whether to run on single server only	onOneServer() method
beforeCallbacks	array	Callbacks to run before execution	before(), pingBefore() src/Scheduling/Event.php56
afterCallbacks	array	Callbacks to run after execution	after(), then() src/Scheduling/Event.php61
exitCode	?int	Exit status of last execution	Set during finish() src/Scheduling/Event.php78
output	?string	Output file path	sendOutputTo() src/Scheduling/Event.php46
lastChecked	?Carbon	Last eligibility check time	Set during filtersPass() src/Scheduling/Event.php73

Sources: src/Scheduling/Event.php43-88

Integration Points

Container and Dependency Resolution

The scheduling system integrates deeply with the dependency injection container:

Sources: src/Scheduling/Schedule.php100-118 src/Scheduling/Event.php172-180 src/Scheduling/Event.php227-242

External System Integration

Events can integrate with external systems through callbacks:

Integration	Method	Description
HTTP Webhooks	pingBefore(), thenPing(), pingOnSuccess(), pingOnFailure()	Send HTTP GET requests to URLs src/Scheduling/Event.php458-517
Email Notifications	emailOutputTo(), emailOutputOnFailure()	Send output via email src/Scheduling/Event.php377-414
Queue System	Schedule::job()	Dispatch jobs to queue workers src/Scheduling/Schedule.php158-178
File System	sendOutputTo(), appendOutputTo()	Write output to log files src/Scheduling/Event.php324-370

Sources: src/Scheduling/Event.php377-547

Use Cases

Common Scheduling Patterns

The task scheduling system supports various common patterns:

1. Database Maintenance

2. Cache Warming

3. Report Generation

4. System Health Checks

5. Multi-Server Safe Tasks

Sources: src/Scheduling/Schedule.php123-250 src/Scheduling/Event.php1-738

System Dependencies

The scheduling system requires and integrates with several components:

Sources: src/Scheduling/Schedule.php1-28 src/Scheduling/Event.php1-34