Cadence Laravel Package

Product Decisions This Supports

• Per-record cadence vs. system-wide cron. Cadence's core value is that a schedule belongs to a row, not to a deploy. This is the deciding factor for features where the cadence legitimately varies per entity: workspace digests, per-tenant report regeneration, per-subscription billing reminders, trial-expiry nudges, per-record cache refresh or retention cleanup. If the answer to "how often?" is the same for every customer, this package is the wrong tool and Laravel's own Schedule facade is the right one.
• Scheduling as self-serve product configuration. The schedules table (type, expression, timezone, next_run_at, disabled_at) is effectively a persisted product feature, not infrastructure. It decides whether "let customers choose their digest frequency" is a UI ticket or an engineering epic. Adopting it moves a class of recurring requests ("can we get this weekly instead of daily?") out of the backlog entirely.
• Timezone-correct delivery for global tenants. Because timezone is a column and next_run_at is precomputed, "9am in the customer's local time" is achievable without per-tenant cron entries — which is the alternative, and it's not one you want to own. This makes international/local-time delivery a launch-ready capability rather than a follow-up.
• Pause/resume as a first-class control. The v1.1.0 enable/disable API maps directly to a "pause my weekly digest" toggle. Decision supported: ship pause as a non-destructive product control (no data loss, no re-onboarding flow) instead of forcing cancel-and-recreate. Note the semantic — re-enabling computes the next occurrence from now, so a paused schedule won't fire a backlog. That's usually the desired behavior, but it's a product-copy decision, not just an implementation detail.
• Build vs. buy for recurrence logic. What you'd otherwise build is not the table — it's correct cron/RRULE resolution, DST and timezone edge cases, "next occurrence after a given instant," and the dispatch loop. That's the expensive, bug-prone 20%. MIT license plus a documented resolveNextOccurrence() base class means the buy side is cheap and the exit is clean. Recommendation: buy, but wrap it.
• One primitive instead of N bespoke features. Cadence gives you a reusable "scheduled thing" abstraction (polymorphic schedulable). Roadmap implication: subsequent scheduling-adjacent features (exports, reminders, digests) extend the same table and event rather than each adding a last_sent_at column and its own cron entry. This is a platform-consolidation decision as much as a feature decision.

When to Consider This Package

Adopt when all of these hold:

• Recurrence is per-entity and dynamic — set or changed by users, tenants, or business rules at runtime, not at deploy time.
• You need one or many schedules per model, with independent timezones and independent on/off state.
• You want a single audit/visibility surface ("what's scheduled to run, and when?") that non-engineers can inspect.
• You're on Laravel ≥11 / PHP ≥8.2 and comfortable with the event + queued-listener pattern (ScheduleTriggered carries SerializesModels as of v1.0.1, so queued listeners re-fetch the model — good).
• You're willing to own a small dependency: 58 stars, 0 dependents, a single maintainer, first release v1.0.0. This is a "vendorable utility," not a platform bet. Keep your integration surface to one internal wrapper class so replacing it is a day, not a quarter.

Look elsewhere when:

• The schedule is global. A single nightly job, one weekly report for the whole company — use Laravel's Schedule facade. Adding a table, a migration, and an every-minute polling command for this is pure overhead.
• You need durable execution, retries, or state machines. This dispatches an event and advances next_run_at; it does not guarantee delivery, track run outcomes, or retry failed work. Workflow/orchestration needs (Temporal, Laravel Workflow, robust queue topology) are a different purchase.
• You need "run once in 30 minutes." That's a delayed job on a queue, not a recurrence.
• You need a user-facing calendar/recurrence editor. Cadence stores expressions; it doesn't help users construct or visualize them. You'll still pick a frontend RRULE library and design the UX.
• Schedule cardinality is extreme. schedules:run polls next_run_at <= now() every minute. At hundreds of thousands of schedules, validate indexing and query cost before committing; at millions, build a partitioned/queue-based design instead.
• Compliance or multi-tenant isolation requires per-tenant storage. One shared schedules table may not satisfy strict isolation requirements.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed library that turns "scheduling" from an engineering task into a product capability. Today, every request like "can this report go out weekly, in my timezone, and can I pause it?" is a backlog item. With roughly a table, a trait, and a listener, those become settings. Cost is measured in days, not weeks, and we avoid hand-rolling recurrence math — timezone/DST/cron parsing — which is exactly the kind of code that produces silent, customer-visible failures at 3am. The strategic framing: it establishes a reusable scheduling primitive so future recurring features don't each get their own bespoke implementation.

To engineering: The integration surface is genuinely thin: implement Schedulable and HasSchedules on the models you care about, publish one migration, register schedules:run every minute with withoutOverlapping(), and handle ScheduleTriggered in small queued listeners with shouldQueue() predicates. The cron driver rides on dragonmantank/cron-expression, already a Laravel core transitive dependency, so the simple path adds no net dependency; RRULE support is opt-in via rlanvin/php-rrule or simshaun/recurr. Drivers auto-register when their library is present, and there's a documented base class plus a tap() hook for bespoke recurrence and library configuration.

The honest risk slide: This is a young, low-adoption package — 58 stars, zero dependents, a single maintainer, v1.0.0 in the recent past. We should not treat it as infrastructure we can't live without. Mitigations: (1) confine all Cadence calls behind one internal Scheduler service so the blast radius of a swap is one file; (2) it's MIT and small enough to vendor if upstream stalls; (3) next_run_at in our own table is plain data we keep, so the state survives any replacement. Also budget for the sharp edges: a missing driver library fails at addSchedule() time with a non-obvious error, so we add a startup/config assertion; and the README's listener example has a typo (= instead of ===) — read the source, not the snippet.

Recommendation: Adopt for per-entity, user-configurable recurrence; decline for global jobs. Fund it as a spike behind a feature flag on one model (a per-workspace digest is the ideal proving ground), measure the polling cost at realistic schedule volume, and only then generalize.