Ux Calendar Link Laravel Package

Getting Started

• Install with composer require symfony/ux-calendar-link. The package is Symfony UX, not Laravel, but the underlying pattern (build an event value object, hand it to a link generator, render an anchor) ports directly to Laravel controllers and Blade views.
• First places to read: Symfony\UX\CalendarLink\CalendarLinkInterface, CalendarLinkFactory, and the CalendarEvent model. The Twig extension and <twig:CalendarLink> component are thin wrappers over these.
• Minimal first use case: an "Add to calendar" pair of buttons on an event detail page. Pass a CalendarEvent (title, start, end, description, location, timezone) plus a provider name (google, outlook, yahoo, ical) and render the returned URL into an <a href>.
• If you are porting to Laravel: keep the same shape — a DTO for the event, a small service that returns provider URLs, and a Blade partial that loops over providers. Do not reach for a JS calendar widget first; this package is link generation only.

Implementation Patterns

• Entity → DTO mapping: write one mapper (Event::toCalendarEvent()) and reuse it everywhere links appear (detail page, confirmation email, API payload). Keep the mapping in one class so timezone and all-day rules stay consistent.
• Provider loop in the view: build a small array of providers and render buttons in a loop rather than hardcoding each anchor. Add new providers by config, not by editing templates.
• Download (.ics) route: for ical, expose a controller route that returns the generated payload with Content-Type: text/calendar; charset=UTF-8 and a Content-Disposition: attachment filename. Generate absolute URLs (URL::to() / url()) so links work in emails.
• Email integration: generate links server-side at send time and store the resulting URLs on the queued job payload, or regenerate in the mailable. Avoid generating at render time in a queued context if the host/port config differs between workers and web.
• Livewire/Blade equivalent of the component: a Blade partial taking $event, $providers, and an optional $variant (button row, dropdown, icon links). Same partial serves both pages and mailables when you pass inline styles.
• Reusable service: bind a CalendarLinkService in the container that wraps provider generation and caches per-event-per-provider output for the request. Calendar links are pure functions of the event data, so memoizing is safe.
• Testing: assert the generated URL contains the expected encoded title, dates in UTC YYYYMMDDTHHMMSSZ form, and location. Freeze the clock (Carbon::setTestNow()) so date assertions are stable across midnight and DST boundaries.

Gotchas and Tips

• Timezone identifiers are the main source of bugs. v3.6.0 fixes UTC detection for VTIMEZONE, which means the library previously mis-detected some UTC-ish zone names. If you upgraded from 3.5.0, re-check any event where timezone is UTC, Etc/UTC, GMT, or a fixed-offset string — output can shift. Prefer IANA names (Europe/Paris) over abbreviations (CET) and avoid Windows names (Romance Standard Time).
• The v3.6.0 change is a bugfix, not a BC break. No API changes; safe to bump in a patch release. Still pin ^3.6 rather than * so future timezone fixes come through predictably.
• Z suffix vs VTIMEZONE block: for UTC events, expect timestamps ending in Z and no timezone block. If you see both, you are mixing UTC-normalized DateTime objects with a non-UTC timezone argument — make them agree.
• All-day events: pass dates without times and set the all-day flag rather than midnight-to-midnight times. Google and Outlook interpret these differently, and a midnight range often renders as a two-day event.
• URL length: Google links put the description in the query string. Long descriptions (agendas, HTML fragments) can exceed practical limits. Strip HTML and truncate for google; keep the full text for the .ics download.
• Escaping: newlines in description must be \n in the iCal payload but %0A in a URL. Let the generator handle it and never hand-concatenate query strings.
• Missing assets: the Twig component's optional JS/CSS come via Symfony UX asset mapper or Webpack Encore. If buttons render unstyled, check importmap/encore entries before blaming the package.
• Download route security: if the .ics route takes an event ID, authorize it like any other resource. Calendar clients fetch these URLs without session cookies in some flows, so prefer signed URLs for public sharing.
• Extension point: implement CalendarLinkInterface with a getProviderName() and getCalendarUrl() to add providers (Teams, Calendly deep links) without forking. Register with the ux_calendar_link.provider tag if autoconfiguration is off.