README

中文文档

PHP 8.2+ task scheduler with a fluent API and full lifecycle management.

Features

• Cron expressions — standard 5-field or 6-field (with seconds); supports */n, ranges, lists, weekday/month names, @daily aliases
• Fluent API — second(3), minute(5), hour(2), dailyAt('8:30'), weeklyOn('monday')
• Constraints — time range between(), environment environments(), condition when()/skip()
• Lifecycle hooks — before(), after(), onSuccess(), onFailure()
• Overlap prevention — withoutOverlapping() via file-based mutex
• Timezone support — global per-daemon and per-task
• Three task types — Closure, shell command, Class@method
• Daemon mode — continuous loop with second precision, auto-fork to background

Requirements

ext-pcntl and ext-posix are CLI-only and unavailable in Web SAPI. If ext-posix is missing, stop falls back to exec("kill ...").

Installation

composer require wolfcode/php-cron

Quick Start

<?php
require __DIR__ . '/vendor/autoload.php';

use PhpCron\Scheduler;
use PhpCron\Timezone;

Scheduler::run(function (Scheduler $s) {
    $s->call(function () {
        echo date('Y-m-d H:i:s') . " heartbeat\n";
    })->minute(1)->name('heartbeat');

    $s->command('df -h')
        ->hourly()
        ->appendOutputTo(__DIR__ . '/disk-usage.log');

    $s->call(function () {
        // Send daily report at 9 AM on weekdays
    })->dailyAt('9:00')->weekdays()->name('daily-report');
}, Timezone::AMERICA_NEW_YORK);

php my-cron.php            # Start (background, auto-fork)
php my-cron.php status     # List tasks
php my-cron.php stop       # Stop daemon

Timezone

Two levels:

• Global timezone — second argument of Scheduler::run(). Affects started_at in status output, all date() calls, and every task's scheduling
• Per-task timezone — ->timezone(). Overrides scheduling timezone for that task only; does NOT affect date()

use PhpCron\Timezone;

// Global timezone: all date() + status time + scheduling use Eastern time
Scheduler::run(function (Scheduler $s) {
    $s->call(function () {
        file_put_contents('log.txt', date('Y-m-d H:i:s') . "\n", FILE_APPEND);
    })->minute(1);
}, Timezone::AMERICA_NEW_YORK);

// Per-task timezone: only affects when this task triggers, not date()
$s->call(fn() => doSomething())
    ->timezone(Timezone::AMERICA_NEW_YORK)
    ->dailyAt('9:00');

API Reference

Frequency Methods (Parameter-based)

Semantic Methods

Custom Expression

->cron('0 9 * * 1')     // Every Monday at 9 AM
->cron('*/5 * * * * *') // Every 5 seconds (6-field)

Constraints

->between('9:00', '17:00')          // Only between 9 AM and 5 PM
->unlessBetween('23:00', '6:00')    // Skip during specified hours
->when(fn() => someCondition())      // Run when truthy
->skip(fn() => holidayCheck())       // Skip when truthy
->environments('production')         // Only in given environments
->timezone(Timezone::ASIA_SHANGHAI)  // Per-task timezone

Hooks

->before(function () { /* before task */ })
->after(function () { /* after task (always) */ })
->onSuccess(function ($output) { /* on success */ })
->onFailure(function (\Throwable $e) { /* on failure */ })

Others

->withoutOverlapping()           // Prevent overlapping runs
->sendOutputTo('/path/to.log')   // Write output to file
->appendOutputTo('/path/to.log') // Append output to file
->name('task-name')              // Task identifier

License

MIT