Skip to content

schedule-events.md

Latest commit

 

History

History
311 lines (252 loc) · 8.07 KB

schedule-events.md

File metadata and controls

311 lines (252 loc) · 8.07 KB

Scheduler

The Schedule attribute provides an elegant way to create and manage WordPress cron jobs. It allows you to easily schedule recurring tasks in your WordPress application using multiple approaches: predefined schedules, enum values, or custom intervals.

Basic Usage

To schedule a recurring task, simply add the Schedule attribute to your method:

use Pollora\Attributes\Schedule;

class Maintenance
{
    #[Schedule('daily')]
    public function cleanupDatabase(): void
    {
        // This method will run once per day
        // The hook name will be: maintenance_cleanup_database
    }
}

Using the Every Enum (Recommended)

The framework provides an Every enum for type-safe scheduling with predefined intervals:

use Pollora\Attributes\Schedule;
use Pollora\Schedule\Every;

class Maintenance
{
    #[Schedule(Every::HOUR)]
    public function pingSlack(): void
    {
        // Runs every hour
    }

    #[Schedule(Every::DAY)]
    public function dailyBackup(): void
    {
        // Runs once per day
    }

    #[Schedule(Every::WEEK)]
    public function weeklyReport(): void
    {
        // Runs once per week
    }

    #[Schedule(Every::MONTH)]
    public function monthlyCleanup(): void
    {
        // Runs once per month (custom schedule automatically registered)
    }

    #[Schedule(Every::YEAR)]
    public function yearlyArchive(): void
    {
        // Runs once per year (custom schedule automatically registered)
    }
}

Available Every Options

  • Every::HOUR - Runs once every hour (uses WordPress hourly)
  • Every::TWICE_DAILY - Runs twice per day (uses WordPress twicedaily)
  • Every::DAY - Runs once per day (uses WordPress daily)
  • Every::WEEK - Runs once per week (uses WordPress weekly)
  • Every::MONTH - Runs once per month (automatically creates custom schedule)
  • Every::YEAR - Runs once per year (automatically creates custom schedule)

Built-in Schedule Intervals (Legacy)

WordPress provides several default scheduling intervals that you can still use with strings:

  • hourly - Runs once every hour
  • twicedaily - Runs twice per day
  • daily - Runs once per day
  • weekly - Runs once per week

Custom Intervals with Interval Class

For precise timing control, use the Interval class which provides a fluent API:

use Pollora\Attributes\Schedule;
use Pollora\Schedule\Interval;

class Maintenance
{
    #[Schedule(new Interval(hours: 3, minutes: 30))]
    public function checkFeeds(): void
    {
        // Runs every 3 hours and 30 minutes
    }

    #[Schedule(new Interval(
        days: 1,
        hours: 12,
        minutes: 15,
        display: 'Daily plus 12h15m'
    ))]
    public function complexTask(): void
    {
        // Runs every 1 day, 12 hours, and 15 minutes
    }

    #[Schedule(new Interval(weeks: 2, display: 'Bi-weekly'))]
    public function biweeklyTask(): void
    {
        // Runs every 2 weeks
    }
}

Interval Constructor Parameters

  • seconds: int = 0 - Additional seconds
  • minutes: int = 0 - Additional minutes
  • hours: int = 0 - Additional hours
  • days: int = 0 - Additional days
  • weeks: int = 0 - Additional weeks
  • display: string = 'Custom schedule' - Human-readable description

Custom Scheduling (Legacy Array Syntax)

For backward compatibility, you can still create custom schedules using arrays:

class Maintenance
{
    #[Schedule(
        ['interval' => 3600 * 6, 'display' => '6 hours']
    )]
    public function performCheck(): void
    {
        // Runs every 6 hours
    }
}

The custom schedule array requires:

  • interval: Time in seconds between executions
  • display: Human-readable name for the schedule

Custom Hook Names

By default, the hook name is generated from the class and method names, but you can specify a custom hook name:

use Pollora\Schedule\Every;
use Pollora\Schedule\Interval;

class Maintenance
{
    // With string schedule
    #[Schedule('hourly', hook: 'custom_maintenance_hook')]
    public function performTask(): void
    {
        // Uses 'custom_maintenance_hook' instead of 'maintenance_perform_task'
    }

    // With Every enum
    #[Schedule(Every::DAY, hook: 'daily_cleanup')]
    public function cleanup(): void
    {
        // Uses 'daily_cleanup' hook name
    }

    // With Interval class
    #[Schedule(new Interval(hours: 6), hook: 'six_hourly_check')]
    public function checkSystem(): void
    {
        // Uses 'six_hourly_check' hook name
    }
}

Schedule with Arguments

You can pass additional arguments to your scheduled function with any schedule type:

use Pollora\Schedule\Every;
use Pollora\Schedule\Interval;

class Maintenance
{
    // With string schedule
    #[Schedule(
        'daily',
        hook: 'cleanup_task',
        args: ['type' => 'full', 'force' => true]
    )]
    public function cleanup(array $args): void
    {
        $type = $args['type']; // 'full'
        $force = $args['force']; // true
        
        // Perform cleanup based on arguments
    }

    // With Every enum and arguments
    #[Schedule(Every::DAY, hook: 'custom_hook', args: ['type' => 'full'])]
    public function updateIndex(array $args): void
    {
        // Process with arguments
    }

    // With Interval class and arguments
    #[Schedule(
        new Interval(hours: 2, minutes: 30),
        hook: 'data_sync',
        args: ['source' => 'api', 'batch_size' => 100]
    )]
    public function syncData(array $args): void
    {
        // Sync data with specified parameters
    }
}

All-in-One Example

Here's a comprehensive example showing various ways to use the Schedule attribute:

use Pollora\Attributes\Schedule;
use Pollora\Schedule\Every;
use Pollora\Schedule\Interval;

class SystemMaintenance
{
    // Using Every enum (recommended)
    #[Schedule(Every::DAY)]
    public function dailyCleanup(): void
    {
        // Daily cleanup using enum
    }

    // Custom interval using Interval class
    #[Schedule(new Interval(hours: 4, display: '4 hours'))]
    public function systemHealthCheck(): void
    {
        // Runs every 4 hours
    }

    // Monthly schedule with custom hook (auto-registered)
    #[Schedule(Every::MONTH, hook: 'monthly_reports')]
    public function generateReports(): void
    {
        // Monthly report generation
    }

    // Complex interval with arguments
    #[Schedule(
        new Interval(hours: 2, minutes: 30),
        hook: 'data_sync',
        args: ['type' => 'incremental', 'source' => 'api']
    )]
    public function syncData(array $args): void
    {
        // Runs every 2.5 hours with arguments
    }

    // Legacy string syntax (still supported)
    #[Schedule('twicedaily')]
    public function legacyTask(): void
    {
        // Backward compatibility
    }

    // Legacy array syntax (still supported)
    #[Schedule(
        ['interval' => 3600 * 6, 'display' => '6 hours'],
        hook: 'legacy_check'
    )]
    public function legacyCustomTask(): void
    {
        // Backward compatibility with arrays
    }
}

Schedule Type Summary

Type Syntax Use Case Custom Registration
Every Enum Every::DAY Type-safe, predefined intervals Auto for MONTH/YEAR
Interval Class new Interval(hours: 2) Precise custom timing Always
String 'daily' WordPress built-ins Never
Array ['interval' => 3600] Legacy custom intervals Always

Important Notes

  1. Hook names are automatically generated in snake_case format if not specified:

    • For a class DatabaseMaintenance with method cleanupOldRecords
    • The generated hook name would be database_maintenance_cleanup_old_records

  2. The Schedule attribute ensures that events are only registered once through automatic discovery.

  3. Custom schedules are automatically registered when using:

    • Every::MONTH and Every::YEAR enum values
    • Interval class instances
    • Legacy array syntax with custom intervals

  4. All syntax variations support the same parameters:

    • hook: string - Custom hook name
    • args: array - Arguments passed to the scheduled method