feat: emit VTIMEZONE components for referenced TZIDs

An event with distinct start and end timezones is written with a TZID
parameter on each endpoint, but the file carried no definition of those
zones. RFC 5545 section 3.6.5 requires one VTIMEZONE per unique TZID.
Clients that resolve bare IANA identifiers imported the event anyway,
while older Outlook desktop versions read the endpoints as floating
local times and shifted the event.

The observances are derived from DateTimeZone::getTransitions() over a
window reaching a year either side of the event, so a zone that changes
its clocks contributes both STANDARD and DAYLIGHT while a fixed offset
zone contributes STANDARD alone. The window comes from the event's own
dates rather than the current date, keeping the output deterministic.

Author: alies-dev

README.md

@@ -133,7 +133,7 @@ DTSTART;TZID=Asia/Tokyo:20270315T090000
 DTEND;TZID=America/Los_Angeles:20270315T093000
 ```
 
-`DTSTAMP` stays in UTC, as RFC 5545 requires.
+`DTSTAMP` stays in UTC, as RFC 5545 requires. Each zone named this way also gets its own `VTIMEZONE` component, placed before the event and holding the offsets in force around it, so the file stands on its own for a client that does not resolve bare IANA names (older Outlook desktop, for instance).
 
 Nothing needs switching on. An event whose two ends share a zone is generated exactly as before, and so is an all-day event, which has no clock time to place in a zone. Yahoo has no timezone parameter and Outlook accepts only UTC or the viewer's own zone, so both keep their current output.
 

src/Generators/Ics.php

@@ -70,6 +70,17 @@ public function generate(Link $link): string
             'VERSION:2.0', // @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.7.4
             'PRODID:'.($this->options['PRODID'] ?? 'Spatie calendar-links'), // @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.7.3
             ...$this->additionalCalendarProperties($link),
+        ];
+
+        // Properties precede components at the VCALENDAR level, which is why this sits after the
+        // calendar properties and before the event.
+        // @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+        if ($this->shouldDefineTimezones($link)) {
+            $url = [...$url, ...$this->generateTimezoneComponents($link)];
+        }
+
+        $url = [
+            ...$url,
             'BEGIN:VEVENT',
             'UID:'.($this->options['UID'] ?? $this->generateEventUid($link)),
             'SUMMARY:'.$this->escapeString($link->title),
@@ -302,6 +313,167 @@ protected function additionalEventProperties(Link $link): array
         return [];
     }
 
+    /**
+     * Whether the file needs VTIMEZONE components at all.
+     *
+     * This must stay in step with the condition in generate() that decides whether the endpoints are
+     * written with a TZID parameter, because a VTIMEZONE is only meaningful when a property in the
+     * file references it. Narrowing that condition has to narrow this one with it, or the file ends
+     * up carrying an orphan component that defines a zone nothing names.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+     */
+    protected function shouldDefineTimezones(Link $link): bool
+    {
+        return $link->hasDistinctTimezones();
+    }
+
+    /**
+     * Extension point: the zones the generated file names with a TZID parameter, in the order their
+     * VTIMEZONE components should appear. Repeated names are collapsed by the caller, so an override
+     * is free to list a zone it cannot rule out being there already.
+     *
+     * @return list<\DateTimeZone>
+     */
+    protected function referencedTimezones(Link $link): array
+    {
+        return [$link->fromTimezone, $link->toTimezone];
+    }
+
+    /**
+     * "An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter
+     * value specified in the iCalendar object." Without them the file is invalid, and a client that
+     * does not resolve bare IANA identifiers (older Outlook desktop) reads the endpoints as floating
+     * local times, which shifts the event.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+     * @return list<string>
+     */
+    protected function generateTimezoneComponents(Link $link): array
+    {
+        $components = [];
+        $definedTimezones = [];
+
+        foreach ($this->referencedTimezones($link) as $timezone) {
+            $tzid = $timezone->getName();
+
+            // Unique is per TZID value, not per referencing property, so an event that departs and
+            // lands in one zone still gets a single component.
+            if (isset($definedTimezones[$tzid])) {
+                continue;
+            }
+
+            $definedTimezones[$tzid] = true;
+
+            $components = [...$components, ...$this->generateTimezoneComponent($timezone, $link)];
+        }
+
+        return $components;
+    }
+
+    /**
+     * @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+     * @return list<string>
+     */
+    protected function generateTimezoneComponent(\DateTimeZone $timezone, Link $link): array
+    {
+        $component = ['BEGIN:VTIMEZONE'];
+        $component[] = 'TZID:'.$timezone->getName();
+
+        foreach ($this->generateTimezoneObservances($timezone, $link) as $observance) {
+            $component = [...$component, ...$observance];
+        }
+
+        $component[] = 'END:VTIMEZONE';
+
+        return $component;
+    }
+
+    /**
+     * At most one STANDARD and one DAYLIGHT observance, read from the zone's own transition table
+     * rather than a hardcoded rule set, so the file needs no maintenance when a country changes its
+     * mind about summer time. The window reaches a year either side of the event, which is wide
+     * enough for a zone that changes its clocks to contribute both observances while staying small
+     * and free of the current date, so the output stays the same on every run.
+     *
+     * An observance carries no RRULE here, so it applies from its DTSTART onwards until the next one
+     * begins. Keeping the latest onset that has already happened by the end of the event therefore
+     * describes exactly the period the event falls in. A zone that holds one offset all year round
+     * has no daylight saving to describe and contributes STANDARD alone.
+     *
+     * That last case has no real transition to point at, so its onset is the opening of the window,
+     * which is where PHP reports the offset already in effect. The epoch such a zone is often given
+     * instead would claim the offset has held since 1970, and for a zone that settled only recently
+     * that is false: Europe/Moscow kept summer time until 2011 and moved from +0400 to +0300 in
+     * 2014, so an epoch onset would misplace every date in between, which a recurrence resolved
+     * against this component can reach. Opening at the window claims less and stays true.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+     * @return list<list<string>>
+     */
+    private function generateTimezoneObservances(\DateTimeZone $timezone, Link $link): array
+    {
+        $transitions = $timezone->getTransitions(
+            $link->from->modify('-1 year')->getTimestamp(),
+            $link->to->modify('+1 year')->getTimestamp(),
+        );
+
+        $eventEnd = $link->to->getTimestamp();
+        $observances = [];
+        $previousOffset = null;
+
+        foreach ($transitions as $transition) {
+            // The first entry describes the offset already in effect when the window opens instead of
+            // a change, so there is no earlier offset to move away from.
+            $offsetFrom = $previousOffset ?? $transition['offset'];
+            $previousOffset = $transition['offset'];
+            $type = $transition['isdst'] ? 'DAYLIGHT' : 'STANDARD';
+
+            // Transitions come back in chronological order, so overwriting until the event is passed
+            // leaves the latest onset in effect, or the earliest one when a whole group lies ahead.
+            if (isset($observances[$type]) && $transition['ts'] > $eventEnd) {
+                continue;
+            }
+
+            $observances[$type] = [
+                'BEGIN:'.$type,
+                // An onset is a local time read against the offset being left behind.
+                // @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.2.4
+                'DTSTART:'.gmdate(self::LOCAL_DATETIME_FORMAT, $transition['ts'] + $offsetFrom),
+                'TZOFFSETFROM:'.$this->formatUtcOffset($offsetFrom),
+                'TZOFFSETTO:'.$this->formatUtcOffset($transition['offset']),
+                'TZNAME:'.$this->escapeString($transition['abbr']),
+                'END:'.$type,
+            ];
+        }
+
+        // A fixed order, rather than the order the transitions happened to arrive in, keeps one zone
+        // rendering identically whichever side of a clock change the event sits on.
+        return array_values(array_filter([
+            $observances['STANDARD'] ?? null,
+            $observances['DAYLIGHT'] ?? null,
+        ]));
+    }
+
+    /**
+     * A UTC offset is signed hours and minutes, with seconds appended only when a zone needs them,
+     * which in practice means the local mean times that predate standardised zones.
+     *
+     * @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.14
+     */
+    private function formatUtcOffset(int $offsetInSeconds): string
+    {
+        $absoluteOffset = abs($offsetInSeconds);
+        $seconds = $absoluteOffset % 60;
+
+        return sprintf(
+            '%s%02d%02d',
+            $offsetInSeconds < 0 ? '-' : '+',
+            intdiv($absoluteOffset, 3600),
+            intdiv($absoluteOffset % 3600, 60),
+        ).($seconds !== 0 ? sprintf('%02d', $seconds) : '');
+    }
+
     /**
      * @param \Spatie\CalendarLinks\Link $link
      * @return list<string>

tests/Generators/IcsGeneratorTest.php

@@ -186,6 +186,114 @@ public function it_rejects_a_dtstamp_that_is_not_a_date_time_through_the_link():
         $link->ics(['DTSTAMP' => '2026-01-01'], ['format' => Ics::FORMAT_FILE]);
     }
 
+    #[Test]
+    public function it_defines_a_vtimezone_for_every_referenced_tzid(): void
+    {
+        // @see https://datatracker.ietf.org/doc/html/rfc5545#section-3.6.5
+        $output = $this->generator()->generate($this->createFlightWithDistinctTimezonesLink());
+
+        $this->assertSame(2, substr_count($output, 'BEGIN:VTIMEZONE'));
+        $this->assertStringContainsString("BEGIN:VTIMEZONE\r\nTZID:Asia/Tokyo\r\n", $output);
+        $this->assertStringContainsString("BEGIN:VTIMEZONE\r\nTZID:America/Los_Angeles\r\n", $output);
+
+        // A component is only useful to a client that reads it before the event that leans on it.
+        $this->assertLessThan(strpos($output, 'BEGIN:VEVENT'), strpos($output, 'BEGIN:VTIMEZONE'));
+        $this->assertLessThan(strpos($output, 'BEGIN:VEVENT'), strpos($output, 'END:VTIMEZONE'));
+    }
+
+    #[Test]
+    public function it_describes_both_observances_of_a_zone_that_changes_its_clocks(): void
+    {
+        // The flight lands on 2027-03-15, the day after Los Angeles moved to daylight saving time,
+        // so the pair of observances brackets the event and the later of the two applies to it.
+        $output = $this->generator()->generate($this->createFlightWithDistinctTimezonesLink());
+
+        $this->assertStringContainsString(
+            implode("\r\n", [
+                'BEGIN:STANDARD',
+                'DTSTART:20261101T020000',
+                'TZOFFSETFROM:-0700',
+                'TZOFFSETTO:-0800',
+                'TZNAME:PST',
+                'END:STANDARD',
+                'BEGIN:DAYLIGHT',
+                'DTSTART:20270314T020000',
+                'TZOFFSETFROM:-0800',
+                'TZOFFSETTO:-0700',
+                'TZNAME:PDT',
+                'END:DAYLIGHT',
+            ]),
+            $output
+        );
+    }
+
+    #[Test]
+    public function it_describes_a_zone_that_keeps_one_offset_with_a_standard_observance_alone(): void
+    {
+        // Neither zone observes daylight saving time, so there is no DAYLIGHT rule to state.
+        $link = Link::create(
+            'Bengaluru to Reykjavik',
+            new DateTime('2027-07-01 09:00', new DateTimeZone('Asia/Kolkata')),
+            new DateTime('2027-07-01 15:30', new DateTimeZone('Atlantic/Reykjavik')),
+        );
+
+        $output = $this->generator()->generate($link);
+
+        $this->assertSame(2, substr_count($output, 'BEGIN:VTIMEZONE'));
+        $this->assertSame(2, substr_count($output, 'BEGIN:STANDARD'));
+        $this->assertStringNotContainsString('BEGIN:DAYLIGHT', $output);
+
+        // A zone that never changes leaves and arrives at the same offset.
+        $this->assertStringContainsString("TZOFFSETFROM:+0530\r\nTZOFFSETTO:+0530\r\nTZNAME:IST", $output);
+        $this->assertStringContainsString("TZOFFSETFROM:+0000\r\nTZOFFSETTO:+0000\r\nTZNAME:GMT", $output);
+    }
+
+    #[Test]
+    public function it_defines_a_zone_referenced_twice_only_once(): void
+    {
+        // The rule is one component per unique TZID, not one per property that names a zone.
+        $generator = new class ([], ['format' => Ics::FORMAT_FILE]) extends Ics {
+            #[\Override]
+            protected function referencedTimezones(Link $link): array
+            {
+                return [new DateTimeZone('Asia/Tokyo'), new DateTimeZone('Asia/Tokyo')];
+            }
+        };
+
+        $output = $generator->generate($this->createFlightWithDistinctTimezonesLink());
+
+        $this->assertSame(1, substr_count($output, 'BEGIN:VTIMEZONE'));
+        $this->assertSame(1, substr_count($output, 'TZID:Asia/Tokyo'));
+    }
+
+    #[Test]
+    public function it_defines_no_timezone_when_the_gate_is_closed(): void
+    {
+        // The components and the TZID parameters that reference them are gated together, so a
+        // narrower gate must leave no component behind naming a zone the file never mentions.
+        $generator = new class ([], ['format' => Ics::FORMAT_FILE]) extends Ics {
+            #[\Override]
+            protected function shouldDefineTimezones(Link $link): bool
+            {
+                return false;
+            }
+        };
+
+        $output = $generator->generate($this->createFlightWithDistinctTimezonesLink());
+
+        $this->assertStringNotContainsString('VTIMEZONE', $output);
+    }
+
+    #[Test]
+    public function it_defines_no_timezone_when_the_endpoints_share_a_zone(): void
+    {
+        // Both endpoints are written as UTC instants, so no TZID is referenced and nothing needs defining.
+        $output = $this->generator()->generate($this->createShortEventLink());
+
+        $this->assertStringNotContainsString('VTIMEZONE', $output);
+        $this->assertStringContainsString('DTSTART:20180201T090000Z', $output);
+    }
+
     #[Test]
     public function it_can_generate_a_recurring_event(): void
     {

tests/Generators/__snapshots__/IcsGeneratorTest__it_can_generate_an_event_with_separate_start_and_end_timezones__1.txt

@@ -1,6 +1,30 @@
 BEGIN:VCALENDAR
 VERSION:2.0
 PRODID:Spatie calendar-links
+BEGIN:VTIMEZONE
+TZID:Asia/Tokyo
+BEGIN:STANDARD
+DTSTART:20260315T090000
+TZOFFSETFROM:+0900
+TZOFFSETTO:+0900
+TZNAME:JST
+END:STANDARD
+END:VTIMEZONE
+BEGIN:VTIMEZONE
+TZID:America/Los_Angeles
+BEGIN:STANDARD
+DTSTART:20261101T020000
+TZOFFSETFROM:-0700
+TZOFFSETTO:-0800
+TZNAME:PST
+END:STANDARD
+BEGIN:DAYLIGHT
+DTSTART:20270314T020000
+TZOFFSETFROM:-0800
+TZOFFSETTO:-0700
+TZNAME:PDT
+END:DAYLIGHT
+END:VTIMEZONE
 BEGIN:VEVENT
 UID:950b3e39f0e8344ccd3a11a310eb193c
 SUMMARY:NH 106 Tokyo to Los Angeles