iCal Calendar Feed for WordPress Events with eluceo/ical
A site lists its events, one event post each, with a start date, an end date and a venue stored as post meta: the event post type and the start_date, end_date and venue fields built in the events catalog recipe. Visitors want them in their own calendar. An “Add to calendar” button per event covers one event at a time, and it goes stale the moment an event moves. A calendar feed covers all of them: the visitor subscribes to one URL once, and their calendar app fetches it again on its own schedule, so a rescheduled meetup shows up at its new time without anyone doing anything.
Why this needs a package
Section titled “Why this needs a package”An .ics file looks like plain text, and it is, but the format (RFC 5545) has its own rules: commas and semicolons escaped inside values, long lines folded at 75 octets, a stable UID per event, date formats that change meaning depending on whether a time zone is attached. eluceo/ical builds the file from plain PHP objects, and handles all of that itself.
The route
Section titled “The route”<?php
declare(strict_types=1);
use Eluceo\iCal\Domain\Entity\Calendar;use Eluceo\iCal\Domain\Entity\Event;use Eluceo\iCal\Domain\ValueObject\DateTime;use Eluceo\iCal\Domain\ValueObject\Location;use Eluceo\iCal\Domain\ValueObject\TimeSpan;use Eluceo\iCal\Domain\ValueObject\UniqueIdentifier;use Eluceo\iCal\Domain\ValueObject\Uri;use Eluceo\iCal\Presentation\Factory\CalendarFactory;use Loopress\Api\Attribute\Permission;
#[Permission(public: true)]class EventsCalendar{ public function get(): void { $utc = new DateTimeZone('UTC'); $events = [];
foreach (get_posts(['post_type' => 'event', 'post_status' => 'publish', 'numberposts' => 100]) as $post) { $start = get_post_meta($post->ID, 'start_date', true); $end = get_post_meta($post->ID, 'end_date', true);
if ($start === '' || $end === '') { continue; }
try { $startDate = new DateTimeImmutable($start, wp_timezone()); $endDate = new DateTimeImmutable($end, wp_timezone()); } catch (Exception $e) { continue; }
$event = (new Event(new UniqueIdentifier('event-' . $post->ID . '@' . wp_parse_url(home_url(), PHP_URL_HOST)))) ->setSummary(html_entity_decode(get_the_title($post), ENT_QUOTES, 'UTF-8')) ->setUrl(new Uri(get_permalink($post))) ->setOccurrence(new TimeSpan( new DateTime($startDate->setTimezone($utc), true), new DateTime($endDate->setTimezone($utc), true), ));
$venue = get_post_meta($post->ID, 'venue', true); if ($venue !== '') { $event->setLocation(new Location($venue)); }
$events[] = $event; }
$calendar = (new CalendarFactory())->createCalendar(new Calendar($events));
header('Content-Type: text/calendar; charset=utf-8'); header('Content-Disposition: inline; filename="events.ics"'); echo $calendar; exit; }}{ "require": { "eluceo/ical": "2.14.0" }}lps composer push && lps cpt push && lps meta push && lps api pushThe pushes after composer are the events catalog’s own: the post type and its meta must exist before the route reads them. eluceo/ical is pinned to 2.14.0: 2.15 needs PHP 8.3 and 2.16 needs PHP 8.4, while 2.14 runs on PHP 8.2 with the same API. If your events live under other meta keys (an events plugin, an ACF field group), only the three get_post_meta() calls change.
A few choices worth knowing about:
- The feed holds the 100 most recently published events.
get_posts()sorts by publish date, newest first, so once more than 100 newereventposts exist, an older upcoming event drops out of the feed without any error. Events with an empty date count toward the 100 before they are skipped. Raisenumberpostsor paginate the query if your site has more. - An event with an unreadable date is skipped. The meta values are free text, so a value such as
not a datewould makeDateTimeImmutablethrow and break the feed for every subscriber. The route catches that and leaves the event out. - The title is decoded.
get_the_title()runs WordPress’s typographic filters, so a title written with straight quotes comes back as“live”. An.icsfile is plain text, not HTML, sohtml_entity_decode()turns those back into real characters before the package escapes them. - Times are converted to UTC. The meta values are read in the site’s own time zone (
wp_timezone(), from Settings > General), then written as UTC (DTSTART:20261215T163000Z). ATZID=Europe/Parisvalue would also be valid, but only alongside aVTIMEZONEblock describing that zone’s rules, which some calendar apps require and this route would then have to generate. UTC needs no such block, and every calendar app displays it in the viewer’s own local time. - The
UIDis derived from the post id and the site’s host, so it never changes for a given event. That’s what lets a calendar app recognize a rescheduled event as the same event, moved, instead of a new one next to a stale copy. - The route answers raw bytes, not JSON. A void verb method that sets its own headers and calls
exitis how a route streams a file instead of JSON. Calendar apps never send anAcceptheader WordPress could use, they expecttext/calendarstraight away.
Now subscribe to it
Section titled “Now subscribe to it”curl -i https://your-site.com/wp-json/loopress-api/v1/events-calendarHTTP/1.1 200 OKContent-Disposition: inline; filename="events.ics"Content-Type: text/calendar; charset=utf-8
BEGIN:VCALENDARPRODID:-//eluceo/ical//2.0/ENVERSION:2.0CALSCALE:GREGORIANBEGIN:VEVENTUID:event-16@your-site.comDTSTAMP:20261113T171015ZSUMMARY:Headless Meetup #4URL:https://your-site.com/events/headless-meetup-4/DTSTART:20261215T163000ZDTEND:20261215T190000ZLOCATION:La Cordée\, LyonEND:VEVENTEND:VCALENDARLines end with CRLF, as RFC 5545 requires, and a long title is folded at 75 octets. Note the escaped comma in LOCATION, one of the details the package handles for you. In Google Calendar, “Other calendars > From URL” takes the same address. On Apple devices, the same URL with webcal:// instead of https:// opens the subscription dialog directly, which makes a good link for a “Subscribe” button on the events page.
Permission
Section titled “Permission”A calendar app subscribing to a feed can’t log in to WordPress, so the route is public: #[Permission(public: true)]. That’s fine here because it only ever lists published events, the same information the events page already shows to any visitor. Drafts, private events and anything else behind a login never reach it. If a feed ever needs to be private (a members-only schedule), put a long random secret in the URL and check it in a permission() method, calendar apps can’t send any other kind of credential.
A missing package is scoped to this route
Section titled “A missing package is scoped to this route”Without eluceo/ical installed, Calendar and CalendarFactory are undefined classes, an ordinary PHP error on this one request. Loopress only catches and logs a corrupted or missing vendor/autoload.php itself, not a single package missing from an otherwise intact one, install it through Composer dependency management before pushing this route.
What this opens up
Section titled “What this opens up”Rescheduling an event changes its DTSTART and DTEND and keeps its UID, so a subscribed calendar moves the event instead of duplicating it. The same shape serves any schedule that already lives in WordPress: a venue’s opening hours as recurring events, a course’s session dates, a team’s on-call rota kept as a custom post type. It pairs naturally with ticket QR codes: one route puts the event in the attendee’s calendar, the other gets them through the door.
Related docs
Section titled “Related docs”Custom API Routes and Composer dependency management ship with Loopress Full, a free WordPress plugin and CLI for managing custom code and dependencies as version-controlled files instead of pasting into wp-admin.
Getting Started walks through connecting it to your site in under a minute. Writing Route Files covers the complete file reference.