Schedule

A high-performance, modular task scheduling ecosystem for PHP 8.4+.

---

✨ Overview

MonkeysLegion Schedule is a modern scheduling engine designed for high reactivity and developer happiness. It bridges the gap between traditional Crontab one-shots and modern reactive daemons, supporting both Attribute-based Discovery and a Fluent API.

🚀 Key Features

• 🧩 Hybrid Discovery: Automatic class-scanning via Attributes or manual registration via Service Providers.
• ⚡ High Reactivity: Support for Sub-Minute (Second-Level) precision.
• 👹 Daemon Mode: A persistent worker loop that polls for "pushed" ad-hoc tasks.
• 🧵 Multi-Process execution: Task isolation using proc_open to prevent bottlenecks.
• 📡 Lifecycle Events: Global event dispatching and per-task fluent callbacks (onStart, onSuccess, etc.).
• 📦 Driver Agnostic: State persistence and task queuing via Redis or Cache.

---

🛠 Installation

composer require monkeyscloud/monkeyslegion-schedule

---

📖 Core Concepts

1. Task Registration

Attribute-Based (Declarative)

Just add the #[Scheduled] attribute to any class with an __invoke method or to specific class methods.

use MonkeysLegion\Schedule\Attributes\Scheduled;

#[Scheduled(expression: '* * * * * *')] // Second-precision!
class HeartbeatAction
{
    public function __invoke()
    {
        // Runs every second
    }
}

Manual Registration (Dynamic)

Ideal for Closures or raw CLI commands registered inside your Service Providers.

$schedule->command('report:generate --daily')->dailyAt('00:00');

$schedule->call(function() {
    return "Pulse sent.";
})->everyFiveMinutes();

2. Execution Modes

Mode	Command	Frequency	Best For
Normal	php ml schedule:run	Run once per execution	Standard system maintenance.
Daemon	php ml schedule:work	Continuous (1s Pulse)	Real-time tasks & Ad-hoc pushed jobs.

---

🎮 CLI Command Palette

Command	Description
schedule:run	The Heartbeat. Execute all tasks that are currently due.
schedule:work	The Daemon. Persistent loop with 1s pulse and Redis polling.
schedule:optimize	The Cache. Warm up task discovery for production performance.
schedule:list	The Dashboard. View all registered tasks, their expressions, and next run times.
schedule:test {id}	The Sandbox. Manually trigger a specific task for debugging.
schedule:clear-locks	The Eraser. Clear all task locks or a specific task lock.

---

🔔 Events & Callbacks

Monitor your ecosystem with high-level dispatcher events or task-specific hooks.

• System Events: TaskStarting, TaskFinished, TaskFailed.
• Fluent Hooks: ->onStart(), ->onSuccess(), ->onFailure(), ->after().

[!TIP] Check the full Events Documentation for custom event object overrides and metadata handling.

---

🗺 Roadmap

Phase 4: Atomic Locking (Prevention) ✅

• LockProvider: Interfacing with Redis/Cache for distributed locking.
• Overlapping Prevention: ->withoutOverlapping() logic to ensure task exclusivity.
• Self-Healing: TTL-based lock expiry for automatic cleanup of stale locks.

Completed Milestones ✅

• Core Architecture: Task Value Objects and the Registry.
• Discovery Engine: Attribute scanning and dynamic loading.
• Sub-Minute Precision: 6-segment Cron support.
• Multi-Process isolation: Non-blocking task execution.
• Redis Integration: Pushed ad-hoc task support via Redis drivers.
• Logger & Monitoring: Seamless monkeyslegion/logger integration.
• Atomic Locking: Fully implemented overlapping prevention via LockProvider.

---

🤝 Contributing

We welcome monkeys from all forests! Please read our Contributing Guide before submitting PRs.

---

⚖️ License

Developed by the MonkeysCloud Team. Released under the MIT License.