Model-Based Scheduling for Laravel with Cadence

Cadence by Steve Bauman takes a different approach to scheduling in Laravel. Rather than centralising all timed tasks in a single scheduler file, it lets you attach one or many schedules directly to individual Eloquent model instances, each with its own expression and timezone, and fires events when they're due.

#How It Works

After installing the package and publishing the migration, you get a schedules table that holds a polymorphic reference to any model, the schedule expression, an optional timezone, and precomputed next_run_at / last_run_at timestamps.

Add the Schedulable interface and HasSchedules trait to any model you want to schedule:

use DirectoryTree\Cadence\HasSchedules;
use DirectoryTree\Cadence\Schedulable;

class Subscription extends Model implements Schedulable
{
    use HasSchedules;
}

Then attach a schedule to a model instance. Cadence ships with drivers for cron expressions and RRULE patterns, and you pick which libraries to install:

# For cron expressions
composer require dragonmantank/cron-expression

# For RRULE (pick one)
composer require rlanvin/php-rrule
# or
composer require simshaun/recurr

A cron-based schedule is straightforward:

use DirectoryTree\Cadence\Drivers\CronSchedule;

// Bill this subscription every month on the 1st at midnight
$subscription->addSchedule(new CronSchedule('0 0 1 * *'));

For more expressive recurrence, RRULE gives you a lot more control over things that are awkward to express in cron:

use DirectoryTree\Cadence\Drivers\RruleSchedule;

// Every two weeks on Tuesday and Thursday
$subscription->addSchedule(new RruleSchedule('FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH'));

Schedules are timezone-aware, so users in different regions get the right local time:

$subscription->addSchedule(
    new CronSchedule('0 8 * * 1', 'Australia/Sydney') // Monday 8am Sydney time
);

#Dispatching and Reacting

Cadence provides a schedules:run Artisan command that you register with Laravel's scheduler to run every minute:

// routes/console.php
Schedule::command('schedules:run')->withoutOverlapping()->everyMinute();

Each time it runs, it finds all records where next_run_at is past due, fires a ScheduleTriggered event for each one, and advances the next occurrence. Your application reacts through a listener:

use DirectoryTree\Cadence\Events\ScheduleTriggered;

class ProcessDueSubscription
{
    public function handle(ScheduleTriggered $event): void
    {
        $subscription = $event->schedule->schedulable;

        $subscription->processRenewal();
    }
}

The event carries the schedule record, giving you access to the parent model, the expression, and timestamps for branching on model type or logging what ran and when.

#Extensibility

If neither cron nor RRULE fits, you can implement a custom driver by extending the base Schedule class and implementing resolveNextOccurrence(), which receives a CarbonInterface and returns the next occurrence. Drivers are registered by name, so swapping or extending them later is straightforward.

You can learn more and view the source code on GitHub.