Product Decisions This Supports
- Feature scope for "recurring" anything. This library answers one question reliably — "given a human-readable rule, what are the next N occurrence dates?" That directly underpins recurring bookings, reminders, task repetition, subscription and invoice cadences, scheduled digests and reports, maintenance windows, shift rosters, and admin-configurable automation.
- Roadmap sequencing. Recurrence is the kind of feature that looks like three days of work and becomes three weeks of bug-fixing once DST, month-end, leap day, and "last Friday of the month" enter the picture. A small dependency here is the difference between shipping a scheduled-reports beta next sprint or next quarter.
- Build vs. buy. Buy. Recurrence is a commodity problem with a well-known, well-documented tail of edge cases; in-house implementations are cheap to write and expensive to own. The only real build-vs-buy axis is which recurrence representation you standardize on, not whether to write one.
- Data model decision: readable DSL vs. RRULE strings. This package stores rules in its own expressive syntax (e.g. "every other Tuesday", "the 1st and 15th of every month"). That is friendly for admin UIs and logs, but it is not portable. Choosing it implicitly decides that calendar export (ICS, Google/Outlook sync) is a later, separate integration rather than a freebie.
- Self-serve configuration. Because rules are declarative text, non-engineers can create and preview schedules without code deploys — a meaningful lever for enterprise/ops customers and for reducing support tickets.
- Preview UI as a product surface. The generator makes "show me the next five occurrences" trivial, which is the single highest-value affordance in any scheduling UI and the fastest way to build trust in an automation feature.
When to Consider This Package
Consider it when:
- You are on PHP/Laravel, recurrence is an enabling feature rather than the product, and your team would rather spend the sprint on the surrounding UX than on date math.
- You want a compact, MIT-licensed library with no runtime services, no per-seat cost, and no vendor relationship.
- You need readable, human-authorable rules and occurrence generation — not calendar interoperability.
- Your team can absorb a small, single-maintainer dependency and wrap it behind an internal interface.
Look elsewhere when:
- You need calendar interop. If exporting to ICS, syncing with Google/Outlook, or importing existing calendars is on the roadmap, standardize on RFC 5545 RRULE (
rlanvin/php-rrule or simshaun/recurr) instead. Retrofitting RRULE semantics onto a bespoke DSL is a migration, not a refactor.
- You need cron semantics — use
dragonmantank/cron-expression; the two solve different problems and are often both needed.
- You need heavy timezone correctness or scale. Per-user local-time rendering, business-calendar holidays, and millions of computed occurrences point toward Carbon's period APIs, a dedicated scheduling service, or a hosted API.
- Dependency governance is strict. Provenance here is unresolved — the repository field is unverified and this is effectively a single-maintainer package with a low release cadence. In a regulated, security-reviewed, or long-horizon codebase, that is a pre-adoption finding to close (verify canonical upstream, PHP 8.2/8.3 and Laravel 10/11 compatibility, last-commit date, open-issue triage) before committing.
How to Pitch It (Stakeholders)
Executives. Recurrence is the highest-leverage hidden cost in any scheduling feature: it appears trivial, then consumes weeks on edge cases that only surface once a year, in production, in front of customers. This is a tiny MIT-licensed library that already encodes those edge cases. It costs nothing to adopt, requires no vendor or contract, and compresses a multi-week engineering item into days — moving a differentiating scheduling capability earlier on the roadmap at essentially zero incremental spend. The exit cost is low because we will isolate it behind our own interface.
Engineering. Do not hand-roll this. The package parses a compact rule syntax and yields occurrence dates; that is a narrow, testable contract. We will wrap it in our own schedule value object and generator interface so the parser is a swappable detail, store rules alongside a rendered human-readable description, and add table-driven tests specifically for DST transitions, month-end rollover, leap day, and nth-weekday rules. Pin the version, vendor or fork if upstream goes quiet, and verify PHP/Laravel compatibility in CI before the first merge.
Risk framing. Small footprint, permissive license, replaceable in roughly a day thanks to the abstraction boundary. The genuine risks are upstream maintenance and standard non-portability — both known, both bounded, and both cheap to reverse if we decide later that calendar interop matters more than authoring ergonomics.