Events Laravel Package

Getting Started

1. Install: composer require transformstudios/events. Statamic auto-discovers the service provider; no manual registration needed on Statamic 3/4/5.
2. Publish anything it ships: run php artisan vendor:publish --provider="TransformStudios\Events\ServiceProvider" and check for config/events.php and any publishable views/fieldsets. Read that config first — it usually tells you which collection handle and field handles the addon expects.
3. Create the collection: make an events collection (or whatever handle the config points to) and attach the addon's blueprint/fieldset. This is where the recurring/multi-day semantics live — the fieldset defines start date/time, end date/time, all-day flag, and recurrence (RRULE-style) options.
4. Seed one of each shape: a single-day event, a multi-day event, and a recurring event. Recurring behavior is the part most likely to surprise you, so validate it against real entries before building templates.
5. First use case: an "Upcoming events" list. Query the collection for entries whose next occurrence is in the future, loop them in Antlers, and render the next occurrence date. This exercises the whole addon: collection setup, date fields, recurrence expansion, and filtering.

Before writing templates, skim src/ — with a small addon like this, the tag/facade names and the recurrence expander are the source of truth, and they're quicker to read than to search for docs.

Implementation Patterns

• Entry-as-event model. One entry represents the event; the addon derives occurrences from its date and recurrence fields. Treat the entry as the stable record and occurrences as computed values — don't try to create one entry per occurrence.
• Query by window, not by "all". For listings and calendars, always scope to a date range (this month, next 30 days). That keeps recurrence expansion bounded and avoids pathological RRULEs.
• Separate "listing" and "detail" concerns. On index pages, show the next occurrence (or the original start/end for single and multi-day events). On the detail page, show the full occurrence list. The addon's recurring support makes those two different queries.
• Multi-day handling. For multi-day events, render a human range (Mar 4–6) rather than start and end independently, and decide explicitly whether the end date is inclusive in your display logic — don't infer it from the stored timestamps.
• Antlers + PHP side by side. Use the addon's tag for simple listings, but drop to PHP (Entry::query()->where('collection', 'events') plus the addon's scopes/traits) when you need pagination, JSON output, or a calendar feed.
• Calendar/JSON feeds. A common pattern is an events.ics or /events.json route that reuses the same window query. Recurring events map cleanly to iCal if the addon already stores RRULE data — reuse it rather than re-deriving rules.
• Blueprint reuse. If you have multiple event-ish collections (workshops, screenings), attach the same fieldset. Centralizing the field handles keeps the addon's expectations intact.
• Cache the expensive parts. Occurrence expansion is the cost center. Cache rendered month/list fragments and invalidate on EntrySaved/EntryDeleted for the events collection.

Gotchas and Tips

• Timezones are the #1 source of bugs. Statamic stores dates in the site timezone; PHP and the RRULE expander may operate in UTC or server time. Verify that "today's event" is correct around midnight and across DST boundaries — spring-forward/fall-back can shift recurring occurrences by an hour or drop one entirely.
• Recurrence termination. Confirm how UNTIL and COUNT interact with an event's end date. A rule that "never ends" plus an unbounded query is a hang waiting to happen — always cap the query window.
• Recurring exceptions. Check the source for support for excluded/cancelled occurrence dates. If it isn't there, you'll need a custom field or a small extension to filter occurrences at render time; don't assume the addon handles it.
• Past vs future filtering. Entries remain published after the event passes. Filter on occurrence date, not published or entry date, or your "upcoming" list will slowly fill with expired events.
• All-day events. The all-day flag usually means start/end times are placeholders. Assert on this in templates rather than printing a misleading 00:00.
• Multi-day end-date semantics. Establish once, in a test, whether the stored end date is inclusive or exclusive, then apply that convention consistently in listing, detail, and JSON output.
• Static caching. Pages that say "next event in 3 days" or filter on now will be stale under Statamic's static cache. Either exclude event listing pages from static caching or add explicit invalidation.
• Version drift. With a small dependent base, you're effectively the QA. Pin the addon and Statamic versions together in composer.json, and run the three entry shapes above as a smoke test after every upgrade.
• Debugging. php artisan tinker plus Entry::query()->where('collection', 'events')->get() for raw data, then call the addon's occurrence/expansion methods directly in tinker to see exactly where a rule diverges from what you expect — faster than round-tripping through templates.
• Extension points. Publishable views and the collection/field-handle config are usually the cheapest customizations. If you need new recurrence rules or an extra output format, extend the addon's tag rather than forking it — the package is small enough that a subclass or a wrapper service will survive upgrades better than a vendor patch.