README

Fluent task scheduler for WPZylos Framework — schedule recurring tasks, cron jobs, and queue dispatches with an expressive API built on WP-Cron.

📖 Full Documentation | 🐛 Report Issues

✨ Features

⏰ Fluent Scheduling — Expressive frequency methods (everyMinute, hourly, daily, weekly, monthly)
🔄 WP-Cron Integration — Automatically hooks into WordPress cron for reliable execution
🔒 Overlap Prevention — Transient-based locks prevent tasks from overlapping
📋 Task Registry — Central Schedule class manages all registered tasks
🎯 Conditional Execution — when(), skip(), and between() constraints
📦 Job Dispatching — Schedule queue jobs alongside closures and commands
🖥️ WP-CLI Support — Schedule WP-CLI commands as recurring tasks
🌐 Multisite Aware — onOneServer() for single-site execution in multisite setups

📋 Requirements

Requirement	Version
PHP	^8.0
WordPress	6.0+

🚀 Installation

composer require wpdiggerstudio/wpzylos-scheduler

📖 Quick Start

use WPZylos\Framework\Scheduler\Schedule;

// Resolve the scheduler from the container
$schedule = $app->make(Schedule::class);

// Schedule a daily cleanup task
$schedule->call(function () {
    // Clean expired tokens
    $wpdb = $GLOBALS['wpdb'];
    $wpdb->query("DELETE FROM {$wpdb->prefix}tokens WHERE expires_at < NOW()");
})->daily()->name('clean-tokens');

// Schedule a task at a specific time
$schedule->call(function () {
    // Send daily digest emails
    $users = get_users(['meta_key' => 'daily_digest', 'meta_value' => '1']);
    foreach ($users as $user) {
        wp_mail($user->user_email, 'Daily Digest', 'Your daily summary...');
    }
})->dailyAt('08:00')->name('daily-digest')->withoutOverlapping();

// Schedule a queue job every 5 minutes
$schedule->job(ProcessPendingOrders::class)
    ->everyFiveMinutes()
    ->name('process-orders');

🏗️ Core Features

Frequency Methods

$schedule->call($callback)->everyMinute();
$schedule->call($callback)->everyFiveMinutes();
$schedule->call($callback)->everyTenMinutes();
$schedule->call($callback)->everyFifteenMinutes();
$schedule->call($callback)->everyThirtyMinutes();
$schedule->call($callback)->hourly();
$schedule->call($callback)->hourlyAt(15);           // At :15 past the hour
$schedule->call($callback)->daily();                 // At midnight
$schedule->call($callback)->dailyAt('13:00');        // At 1:00 PM
$schedule->call($callback)->weekly();                // Sunday at midnight
$schedule->call($callback)->weeklyOn(1, '08:00');    // Monday at 8:00 AM
$schedule->call($callback)->monthly();               // 1st at midnight
$schedule->call($callback)->monthlyOn(15, '09:30');  // 15th at 9:30 AM

Task Types

// Closure/callback tasks
$schedule->call(function () {
    // Your task logic
})->daily()->name('my-task');

// WP-CLI command tasks
$schedule->command('cache flush')
    ->hourly()
    ->name('flush-cache');

// Queue job tasks
$schedule->job(SendNewsletterJob::class)
    ->weeklyOn(1, '06:00')
    ->name('weekly-newsletter');

Constraints & Conditions

// Only run between specific times
$schedule->call($callback)
    ->everyFiveMinutes()
    ->between('09:00', '17:00')
    ->name('business-hours-only');

// Conditional execution
$schedule->call($callback)
    ->daily()
    ->when(fn() => get_option('feature_enabled'))
    ->name('conditional-task');

// Skip execution
$schedule->call($callback)
    ->hourly()
    ->skip(fn() => wp_doing_cron() === false)
    ->name('cron-only-task');

Overlap Prevention

// Prevent task from running if previous execution hasn't finished
$schedule->call(function () {
    // Long-running import process
    $this->importExternalData();
})->everyFiveMinutes()
  ->withoutOverlapping()          // Default: 24 hour lock expiry
  ->name('data-import');

// Custom lock expiration (in minutes)
$schedule->call($callback)
    ->hourly()
    ->withoutOverlapping(60)      // Lock expires after 60 minutes
    ->name('safe-task');

Multisite Support

// Only execute on one site in a multisite network
$schedule->call($callback)
    ->daily()
    ->onOneServer()
    ->name('global-cleanup');

📦 Related Packages

Package	Description
wpzylos-queue	Job queue system
wpzylos-hooks	WordPress hooks manager
wpzylos-core	Application foundation

📖 Documentation

For comprehensive documentation, tutorials, and API reference, visit wpzylos.com.

☕ Support the Project

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ by WPDiggerStudio

wpdiggerstudio / wpzylos-scheduler

Maintainers

Package info

Fund package maintenance!

Statistics

Security