README

A powerful yet lightweight library for scheduling and executing command-line tasks in PHP using flexible cron syntax.

Features

Supports tasks with CronTab Syntax for scheduling
Debug Mode to monitor scheduled task execution
Built-in, configurable PSR-3 Logging (default: logs to STDOUT/STDERR)
Fully compatible with ReactPHP for asynchronous task execution
Captures and logs exceptions without breaking execution
Simple API for defining, managing, and running tasks
Task Runner Status Tracking for monitoring execution statistics 📊

Installation

Install the library using Composer:

composer require johnsear/task-scheduler

Usage

Here's how to quickly get started with the task scheduler:

1. Basic Initialization Example:

<?php

use JohnSear\TaskScheduler\Runner;
use JohnSear\TaskScheduler\Task;

// Include Composer autoload
require_once __DIR__ . '/../vendor/autoload.php';

// Initialize the Runner
$runner = new Runner();

// Define a Task (running every 5 minutes)
$task1 = new Task("*/5 * * * *", "echo 'Running every 5 minutes'");

// Add the task to the scheduler
$runner->addTask($task1);

// Start the Task Scheduler (runs until stopped manually)
$runner->startScheduler();

2. Advanced Usage:

You can further customize the scheduler by:

Adding a custom PSR-3 logger.
Configuring tasks with names, descriptions, or additional options.

Example:

<?php

use My\CoolLogger;

// Create a task with detailed options
$complexTask = new Task(
    "0 */1 * * *",                    // CronTab: Every hour
    "echo 'Hourly logs updated'",     // Command
    "Hourly Logger",                  // Name
    "Logs progress to stdout hourly"  // Description
);

// Disable command output (silent execution)
$complexTask->setOutput(false);

// Use your custom PSR-3 Logger implementation
$runner->setLogger(new CoolLogger());

// Enable Debug Mode (optional)
$runner->setDebug(true);

// Add the task to the scheduler
$runner->addTask($task1);

// Start the Task Scheduler (runs until stopped manually)
$runner->startScheduler();

3. Runner Status Tracking 📊

The Task Scheduler supports automatic Runner Status Tracking, which tracks:

Start time and run duration of the scheduler.
All tasks with their status (e.g., completed, active, etc.).
Task-specific metadata like run count and description.

This information is stored in JSON format for analysis or monitoring.

How to enable Runner Status Tracking?

By default, status tracking is enabled. You have fine-grained control over it!

<?php

use JohnSear\TaskScheduler\Runner;
use JohnSear\TaskScheduler\Task;

// Initialize the Runner
$runner = new Runner('My Custom Runner');

// Set a custom status directory (optional)
$runner->setStatusDir('/custom/path/to/track_status/');

// Define and add tasks
$task1 = new Task("*/5 * * * *", "echo 'Task 1 running every 5 minutes'");
$runner->addTask($task1);

// Start runner and track status
$runner->startScheduler();

What does the status file contain?

The tracked status is saved as a JSON file. The file is called runner_<name>_status.json and is located in the system's temporary directory by default (can be customized).

Example status JSON file:

{
    "startTime": "2024-01-15 08:00:00",
    "runDuration": "3600 seconds",
    "totalTasks": 2,
    "tasks": {
        "task1": {
            "name": "Task 1",
            "description": "Task 1 running every 5 minutes",
            "cronTab": "*/5 * * * *",
            "runCount": 12,
            "isRunning": false
        },
        "task2": {
            "name": "Task 2",
            "description": "Another periodic task",
            "cronTab": "0 * * * *",
            "runCount": 1,
            "isRunning": true
        }
    },
    "activeTasks": {
        "task2": {
            "name": "Task 2",
            "startedAt": "2024-01-15 09:00:00"
        }
    }
}

Turning Off Status Tracking

If you prefer not to track status, you can disable it explicitly:

$runner->trackStatus(false);

Why is status tracking useful?

Real-Time Monitoring: Monitor what tasks are running and for how long.
Debugging: Simplify debugging with detailed task metadata.
Analytics: Collect run statistics that help optimize tasks (e.g., which tasks run most often).

Important Notes

⚠ Important:

This library is not suitable for CPU-intensive or long-running tasks, as asynchronous execution can cause resource bottlenecks.
Ensure all tasks are lightweight and quick to execute.

johnsear / task-scheduler

Maintainers

Details