adds support for X-PUBLISHED-TTL property.

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   Support `X-PUBLISHED-TTL` property on calendars [#413](https://github.com/markuspoerschke/iCal/pull/413)
+
 ## [2.6.0] - 2022-06-17
 
 ### Added

src/Domain/Entity/Calendar.php

@@ -11,6 +11,7 @@
 
 namespace Eluceo\iCal\Domain\Entity;
 
+use DateInterval;
 use Eluceo\iCal\Domain\Collection\Events;
 use Eluceo\iCal\Domain\Collection\EventsArray;
 use Eluceo\iCal\Domain\Collection\EventsGenerator;
@@ -21,6 +22,8 @@ class Calendar
 {
     private string $productIdentifier = '-//eluceo/ical//2.0/EN';
 
+    private ?DateInterval $publishedTTL = null;
+
     private Events $events;
 
     /**
@@ -56,6 +59,16 @@ private function ensureEventsObject($events = []): Events
         throw new InvalidArgumentException('$events must be an array, an object implementing Iterator or an instance of Events.');
     }
 
+    public function getPublishedTTL(): ?DateInterval
+    {
+        return $this->publishedTTL;
+    }
+
+    public function setPublishedTTL(?DateInterval $ttl): void
+    {
+        $this->publishedTTL = $ttl;
+    }
+
     public function getProductIdentifier(): string
     {
         return $this->productIdentifier;

src/Presentation/Factory/CalendarFactory.php

@@ -14,6 +14,7 @@
 use Eluceo\iCal\Domain\Entity\Calendar;
 use Eluceo\iCal\Presentation\Component;
 use Eluceo\iCal\Presentation\Component\Property;
+use Eluceo\iCal\Presentation\Component\Property\Value\DurationValue;
 use Eluceo\iCal\Presentation\Component\Property\Value\TextValue;
 use Generator;
 
@@ -56,5 +57,10 @@ private function getProperties(Calendar $calendar): Generator
         yield new Property('VERSION', new TextValue('2.0'));
         /* @see https://www.ietf.org/rfc/rfc5545.html#section-3.7.1 */
         yield new Property('CALSCALE', new TextValue('GREGORIAN'));
+        $publishedTTL = $calendar->getPublishedTTL();
+        if ($publishedTTL) {
+            /* @see http://msdn.microsoft.com/en-us/library/ee178699(v=exchg.80).aspx */
+            yield new Property('X-PUBLISHED-TTL', new DurationValue($publishedTTL));
+        }
     }
 }

tests/Unit/Domain/Entity/CalendarTest.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2022 Markus Poerschke <markus@poerschke.nrw>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Unit\Domain\Entity;
+
+use DateInterval;
+use Eluceo\iCal\Domain\Entity\Calendar;
+use PHPUnit\Framework\TestCase;
+
+class CalendarTest extends TestCase
+{
+    public function provideGetSetPublishedTTLTestData(): array
+    {
+        return [
+            [new DateInterval('P1W')],
+            [null],
+        ];
+    }
+
+    /**
+     * @dataProvider provideGetSetPublishedTTLTestData
+     * @covers \Eluceo\iCal\Domain\Entity\Calendar::getPublishedTTL
+     * @covers \Eluceo\iCal\Domain\Entity\Calendar::setPublishedTTL
+     *
+     * @param ?DateInterval $ttl
+     */
+    public function testGetSetPublishedTTL($ttl): void
+    {
+        $calendar = new Calendar();
+        $calendar->setPublishedTTL($ttl);
+        self::assertSame($calendar->getPublishedTTL(), $ttl);
+    }
+}

tests/Unit/Presentation/Factory/CalendarFactoryTest.php

@@ -11,6 +11,7 @@
 
 namespace Eluceo\iCal\Test\Unit\Presentation\Factory;
 
+use DateInterval;
 use DateTimeImmutable;
 use DateTimeZone;
 use Eluceo\iCal\Domain\Entity\Calendar;
@@ -74,4 +75,24 @@ public function testRenderWithEvents()
 
         self::assertSame($expected, (string) (new CalendarFactory())->createCalendar($calendar));
     }
+
+    /**
+     * @covers \Eluceo\iCal\Presentation\Factory\CalendarFactory::createCalendar
+     */
+    public function testRenderWithPublishedTTL(): void
+    {
+        $calendar = new Calendar();
+        $calendar->setPublishedTTL(new DateInterval('P1D'));
+        $expected = implode(ContentLine::LINE_SEPARATOR, [
+            'BEGIN:VCALENDAR',
+            'PRODID:' . $calendar->getProductIdentifier(),
+            'VERSION:2.0',
+            'CALSCALE:GREGORIAN',
+            'X-PUBLISHED-TTL:P1D',
+            'END:VCALENDAR',
+            '',
+        ]);
+
+        self::assertSame($expected, (string) (new CalendarFactory())->createCalendar($calendar));
+    }
 }

website/docs/non-standard-properties.md

@@ -0,0 +1,17 @@
+---
+title: Non-standard Properties
+---
+
+## X-PUBLISHED-TTL
+
+The [`X-PUBLISHED-TTL`](http://msdn.microsoft.com/en-us/library/ee178699(v=exchg.80).aspx) property specifies a suggested iCalendar file download frequency for clients and servers with sync capabilities.
+
+Use the `setPublishedTTL()` method with a [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations)-formatted string to set this duration.
+
+```php
+use Eluceo\iCal\Domain\Entity\Calendar;
+
+$calendar = new Calendar();
+// set the duration to 2 hours
+$calendar->setPublishedTTL(new DateInterval('PT2H'))
+```

website/sidebars.js

@@ -17,7 +17,7 @@ module.exports = {
         {
             type: "category",
             label: "Advanced",
-            items: ["custom-properties", "maturity-matrix"],
+            items: ["custom-properties", "non-standard-properties", "maturity-matrix"],
         },
     ],
 };