Weave Code
Cadence Laravel Package
directorytree/cadence
Cadence adds model-based scheduling to Laravel. Attach one or more cron or RRULE schedules to any Eloquent model, track due runs, and dispatch events when schedules trigger. Driver-based design supports cron, php-rrule, Recurr, or custom drivers.
Model-based scheduling for Laravel
Frequently asked questions about Cadence
- How do I attach a cron schedule to a Laravel Eloquent model using Cadence?
- Use the `HasSchedules` trait on your model and define schedules in a `getSchedules()` method. For example, add `public function getSchedules(): array { return ['daily-backup' => '0 3 * * *']; }` to your model. Cadence will store and manage these schedules automatically.
- What’s the difference between Cadence and Laravel’s built-in `Schedule` facade?
- Cadence is model-centric, letting you tie schedules to specific Eloquent records (e.g., user-specific tasks), while Laravel’s `Schedule` facade is global and runs system-wide cron jobs. Cadence also supports RRULE recurrence and custom drivers.
- Can I use RRULE (recurrence rules) with Cadence, and which driver should I pick?
- Yes, Cadence supports RRULE via two drivers: `php-rrule` (lightweight) or `Recurr` (more feature-rich). For complex recurrence (e.g., 'every 2nd Monday'), use `php-rrule`. For simpler cases, `Recurr` may suffice. Install either via Composer.
- How do I run pending schedules in production? Should I use a cron job?
- Run `php artisan schedules:run` via a cron job (e.g., `* * * * * cd /path-to-project && php artisan schedules:run`). For high-volume apps, optimize with database indexing on `next_run_at` and batch processing (e.g., 100 schedules per run).
- Does Cadence support timezones, and how do I configure them for global apps?
- Yes, Cadence uses Carbon for timezone handling. Set schedules with timezones (e.g., `Schedule::cron('* * * * *', 'America/New_York')`), and ensure your Laravel `APP_TIMEZONE` config matches your app’s default. Test edge cases like DST transitions.
- How do I listen for when a schedule triggers and dispatch a job or event?
- Create a listener for `ScheduleTriggered` events. In your listener, access the triggered schedule via `$event->schedule` and dispatch a job (e.g., `dispatch(new ProcessBackupJob($event->schedule->schedulable))`). Use queues to avoid blocking.
- What’s the performance impact of Cadence for large-scale apps (e.g., 10K+ schedules)?
- Cadence queries all due schedules on `schedules:run`. Mitigate performance issues by indexing the `next_run_at` column, using read replicas, and batching runs. Test with your expected scale to validate query times.
- Can I create a custom schedule driver for domain-specific logic (e.g., 'run 7 days after order')?
- Yes, extend Cadence’s `Schedule` class and implement `resolveNextOccurrence()`. For example, create a `PostOrderDriver` that calculates `next_run_at` based on order creation time. Register it via the `CadenceServiceProvider`.
- How do I migrate existing cron jobs to Cadence for model-bound tasks?
- Audit your cron jobs to identify model-specific tasks (e.g., user notifications). Replace them with Cadence schedules attached to Eloquent models. Use the `schedules` table’s polymorphic relations to link schedules to records. Run `php artisan migrate` after publishing Cadence’s migrations.
- What Laravel versions and PHP versions does Cadence support, and are there breaking changes?
- Cadence supports Laravel 11+ and PHP 8.2+. Check the [release notes](https://github.com/DirectoryTree/Cadence/releases) for breaking changes (e.g., v1.1.0 added `disabled_at`). Always test upgrades in staging, as migrations may introduce schema changes.
Weaver
How can I help you explore Laravel packages today?