Emit VTIMEZONE components for referenced TZIDs

[alies-dev]

Context and Purposes

Since #233 an event whose endpoints sit in two different timezones is written with a TZID parameter on each endpoint:

DTSTART;TZID=Asia/Tokyo:20270315T090000
DTEND;TZID=America/Los_Angeles:20270315T093000

The file carried no definition of those zones. RFC 5545 §3.6.5 makes that a MUST: "An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value specified in the iCalendar object."

Google Calendar and Apple Calendar happen to resolve bare IANA identifiers and import the event correctly, so the omission is invisible there. Older Outlook desktop versions (2007 through 2013) do not: they either refuse the import or read the values as floating local times, which shifts the event by the whole offset. Strict validators reject the file outright.

This emits the missing components. Every zone named by a TZID now gets a VTIMEZONE at the VCALENDAR level, after the calendar properties and before BEGIN:VEVENT:

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
...

How the observances are derived

The offsets come from PHP's own zone database, through DateTimeZone::getTransitions(), rather than a rule table that would need maintaining every time 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 a STANDARD and a DAYLIGHT observance while staying small. It is derived from the event's own dates and never from the current date, so the output is stable and snapshot tests do not drift.
• At most one observance of each type is emitted: the latest onset that is already in effect by the end of the event. An observance without an RRULE applies from its DTSTART onwards until the next one begins (§3.6.5), so that pair describes exactly the period the event falls in.
• DTSTART inside an observance is a local time read against the offset being left behind, per §3.8.2.4, so it is computed as the transition instant plus TZOFFSETFROM.
• A zone that holds one offset all year (Asia/Kolkata, UTC) has no daylight saving to describe and gets a STANDARD observance alone, with TZOFFSETFROM equal to TZOFFSETTO.
• Components are keyed on the unique TZID value, not on the properties that reference it, so a zone named twice is defined once.

Scope

Only the path that actually writes TZID parameters is affected, which is Link::hasDistinctTimezones(). An event whose ends share a zone, and an all-day event, are still written as before with plain UTC instants and no VTIMEZONE. The other generators are untouched.

Note for whoever merges this alongside #234

A VTIMEZONE is only meaningful when a property in the file references it, so the components and the TZID parameters have to be gated on the same condition. #234 narrows the condition for writing TZID, because an offset style zone name such as +02:00 cannot appear in a param-value (no unquoted colon) and no service resolves it, so those events fall back to plain UTC endpoints. If the two gates drift apart, such an event gets components defining zones the file never names.

To keep that merge to a single edit, the condition here is hoisted into Ics::shouldDefineTimezones() rather than left inline. Once both land, that one method needs the same narrowing #234 applies to the TZID condition, and nothing else in this change moves. The docblock on the method says so, and a test pins the behaviour by closing the gate from a subclass and asserting no component survives.

referencedTimezones(), generateTimezoneComponents() and generateTimezoneComponent() are protected, matching the additionalCalendarProperties() and additionalEventProperties() seams already in Ics, so a subclass can add a zone or replace the whole component.

Fixes #235