Schedule Management Commands

This document covers the command-line interface for managing, testing, and monitoring scheduled tasks in the Hypervel Console framework. These commands provide administrators and developers with tools to inspect, control, and troubleshoot the task scheduling system.

For information about the core scheduling framework, see page 7. For details on schedule registration, see page 7.1. For event execution lifecycle, see page 7.2. For the main scheduler daemon, see page 7.6.

Overview

The schedule management commands provide CLI utilities for inspecting and controlling the task scheduling system. Four commands are provided: schedule:list, schedule:test, schedule:clear-cache, and schedule:stop. Each extends the base Command class and integrates with the Schedule registry or CacheFactory for operations.

Command Architecture

The four schedule management commands extend Hypervel\Console\Command and interact with scheduling components through dependency injection:

Command Class Hierarchy

Sources: src/Commands/ScheduleListCommand.php41-45 src/Commands/ScheduleTestCommand.php30 src/Commands/ScheduleClearCacheCommand.php25 src/Commands/ScheduleStopCommand.php30-34

Command Registry

The four commands are registered via ConfigProvider and serve distinct operational purposes:

Command Class	Signature	Primary Purpose	Key Dependencies
ScheduleListCommand	schedule:list	Inspect scheduled events	Schedule, CronExpression, Terminal
ScheduleTestCommand	schedule:test	Execute event for testing	Schedule, CallbackEvent
ScheduleClearCacheCommand	schedule:clear-cache	Remove mutex locks	Schedule, EventMutex
ScheduleStopCommand	schedule:stop	Signal daemon shutdown	CacheFactory

Sources: src/Commands/ScheduleListCommand.php26-34 src/Commands/ScheduleTestCommand.php18-23 src/Commands/ScheduleClearCacheCommand.php15-20 src/Commands/ScheduleStopCommand.php16-23

ScheduleListCommand

The ScheduleListCommand class displays all registered events from the Schedule registry with timing and status information.

Execution Flow

Sources: src/Commands/ScheduleListCommand.php52-79 src/Commands/ScheduleListCommand.php104-157

Output Format

The listEvent() method formats each event into a single line containing:

Component	Method	Line Reference
Cron expression	formatCronExpression()	src/Commands/ScheduleListCommand.php214-221
Repeat interval	getRepeatExpression()	src/Commands/ScheduleListCommand.php162-165
Command string	event->command or getClosureLocation()	src/Commands/ScheduleListCommand.php110-120
Next due date	getNextDueDateForEvent()	src/Commands/ScheduleListCommand.php180-207
Mutex status	mutex->exists(event)	src/Commands/ScheduleListCommand.php132

For CallbackEvent instances, the command location is resolved via reflection to display the closure's file path and line number.

Options

Option	Type	Purpose	Default
--timezone	string	Display timezone for date calculations	config('app.timezone')
--next	boolean	Sort by next due date ascending	false

Sources: src/Commands/ScheduleListCommand.php26-29 src/Commands/ScheduleListCommand.php68 src/Commands/ScheduleListCommand.php104-157

ScheduleTestCommand

The ScheduleTestCommand class executes a selected event from the schedule registry in foreground mode for testing purposes.

Execution Flow

Sources: src/Commands/ScheduleTestCommand.php28-81

Selection Mechanism

The getSelectedCommandByIndex() method handles duplicate command names by appending array indexes to make them unique for selection:

Duplicate Handling Logic

When duplicate names exist, the command appends [0], [1], etc. to each command name, then extracts the original index from the user's selection using a regular expression.

Sources: src/Commands/ScheduleTestCommand.php86-104

ScheduleClearCacheCommand

The ScheduleClearCacheCommand class removes all active mutex locks from the cache for scheduled events. This is useful for recovering from stuck locks.

Execution Flow

Implementation Details

The command operates on the Schedule instance passed as a method parameter:

Operation	Method Call	Line Reference
Get all events	$schedule->events()	src/Commands/ScheduleClearCacheCommand.php29
Check mutex existence	$event->mutex->exists($event)	src/Commands/ScheduleClearCacheCommand.php30
Delete mutex	$event->mutex->forget($event)	src/Commands/ScheduleClearCacheCommand.php33

The mutex property on each Event instance references an EventMutex implementation, typically CacheEventMutex.

Sources: src/Commands/ScheduleClearCacheCommand.php25-42

ScheduleStopCommand

The ScheduleStopCommand class signals the ScheduleRunCommand daemon to stop by setting a cache key. This provides graceful shutdown without killing the process.

Execution Flow

Cache Signal Details

The command sets a temporary cache key that ScheduleRunCommand polls in its daemon loop:

Parameter	Value	Purpose
Cache Key	'hypervel:schedule:stop'	Signal identifier checked by daemon
Cache Value	true	Boolean flag indicating stop request
TTL	Date::now()->addMinutes(minutes)	Auto-expiry to prevent permanent stop state
Default TTL	1 minute	From --minutes option default

The ScheduleRunCommand::shouldStop() method checks for this cache key on each iteration of its polling loop.

Sources: src/Commands/ScheduleStopCommand.php39-49 src/Commands/ScheduleStopCommand.php16-18

Dependency Integration

The management commands interact with scheduling components through well-defined interfaces:

Component Dependencies

Sources: src/Commands/ScheduleListCommand.php8-19 src/Commands/ScheduleListCommand.php41-45 src/Commands/ScheduleTestCommand.php7-11 src/Commands/ScheduleTestCommand.php30 src/Commands/ScheduleClearCacheCommand.php7-8 src/Commands/ScheduleStopCommand.php7-9 src/Commands/ScheduleStopCommand.php30-34

Usage Patterns

Development Workflow

1. List Tasks: Use schedule:list to see all scheduled tasks
2. Test Tasks: Use schedule:test to verify task execution
3. Clear Cache: Use schedule:clear-cache to reset mutex state
4. Stop Workers: Use schedule:stop to gracefully halt processing

Production Monitoring

The commands provide essential production monitoring capabilities:

• Task Visibility: schedule:list --next shows upcoming tasks
• Mutex Status: Identify locked tasks that may need intervention
• Emergency Stop: schedule:stop provides graceful shutdown mechanism

Sources: src/Commands/ScheduleListCommand.php26-29 src/Commands/ScheduleStopCommand.php16-18