Add alarm component (#182)

Makefile

@@ -1,6 +1,8 @@
 MAKEFLAGS += --warn-undefined-variables
 SHELL := bash
 PATH := $(PATH):$(CURDIR)/vendor/bin
+PSALM_FLAGS :=
+PHPUNIT_FLAGS :=
 
 .PHONY: test
 test: test-validate-composer test-code-style test-psalm test-phpunit test-examples test-composer-normalize test-phpmd

docs/advanced/maturity-matrix.md

@@ -29,7 +29,7 @@ See [RFC 5545 section 3.6](https://tools.ietf.org/html/rfc5545#section-3.6).
 | VJOURNAL  |     ✖     |
 | VFREEBUSY |     ✖     |
 | VTIMEZONE |     ✖     |
-| VALARM    |     ✖     |
+| VALARM    |     ✔     |
 
 ## Event Component
 
@@ -69,3 +69,35 @@ See [RFC 5545 section 3.6.1](https://tools.ietf.org/html/rfc5545#section-3.6.1).
 | rdate       |     ✖     |
 | x-prop      |    (✔)    |
 | iana-prop   |    (✔)    |
+
+## Alarm Component
+
+See [RFC 5545 section 3.6.1](https://tools.ietf.org/html/rfc5545#section-3.6.6).
+
+### Audio
+
+| Property  | Supported |
+| --------- | :-------: |
+| action    |     ✔     |
+| trigger   |     ✔     |
+| duration  |     ✔     |
+| repeat    |     ✔     |
+| attach    |     ✖     |
+| x-prop    |    (✔)    |
+| iana-prop |    (✔)    |
+
+### Display
+
+| Property    | Supported |
+| ----------- | :-------: |
+| action      |     ✔     |
+| trigger     |     ✔     |
+| description |     ✔     |
+| duration    |     ✔     |
+| repeat      |     ✔     |
+| x-prop      |    (✔)    |
+| iana-prop   |    (✔)    |
+
+## Email
+
+Not yet supported.

examples/example1.php

@@ -11,9 +11,11 @@
 
 namespace Example;
 
+use DateInterval;
 use DateTimeImmutable;
 use Eluceo\iCal\Domain\Entity\Calendar;
 use Eluceo\iCal\Domain\Entity\Event;
+use Eluceo\iCal\Domain\ValueObject\Alarm;
 use Eluceo\iCal\Domain\ValueObject\DateTime;
 use Eluceo\iCal\Domain\ValueObject\TimeSpan;
 use Eluceo\iCal\Presentation\Factory\CalendarFactory;
@@ -31,6 +33,12 @@
             new DateTime(DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2030-12-24 14:30:00'))
         )
     )
+    ->addAlarm(
+        new Alarm(
+            new Alarm\DisplayAction('Reminder: the meeting starts in 15 minutes!'),
+            (new Alarm\RelativeTrigger(DateInterval::createFromDateString('-15 minutes')))->withRelationToEnd()
+        )
+    )
 ;
 
 // 2. Create Calendar domain entity.

examples/example2.php

@@ -18,6 +18,7 @@
 use Eluceo\iCal\Presentation\Component\Property\Value\TextValue;
 use Eluceo\iCal\Presentation\Factory\CalendarFactory;
 use Eluceo\iCal\Presentation\Factory\EventFactory;
+use Generator;
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
@@ -36,20 +37,15 @@ public function getMyCustomProperty(): string
 //    that can add the additional property to the presentation component.
 class CustomEventFactory extends EventFactory
 {
-    public function createComponent(Event $event): Component
+    protected function getProperties(Event $event): Generator
     {
-        $component = parent::createComponent($event);
-
+        yield from parent::getProperties($event);
         if ($event instanceof CustomEvent) {
-            $component = $component->withProperty(
-                new Property(
-                    'X-CUSTOM',
-                    new TextValue($event->getMyCustomProperty())
-                )
+            yield new Property(
+                'X-CUSTOM',
+                new TextValue($event->getMyCustomProperty())
             );
         }
-
-        return $component;
     }
 }
 

psalm.xml

@@ -12,8 +12,4 @@
             <directory name="vendor" />
         </ignoreFiles>
     </projectFiles>
-
-    <issueHandlers>
-        <LessSpecificReturnType errorLevel="info" />
-    </issueHandlers>
 </psalm>

src/Domain/Entity/Event.php

@@ -11,6 +11,7 @@
 
 namespace Eluceo\iCal\Domain\Entity;
 
+use Eluceo\iCal\Domain\ValueObject\Alarm;
 use Eluceo\iCal\Domain\ValueObject\Location;
 use Eluceo\iCal\Domain\ValueObject\Occurrence;
 use Eluceo\iCal\Domain\ValueObject\Timestamp;
@@ -25,6 +26,11 @@ class Event
     private ?Occurrence $occurrence = null;
     private ?Location $location = null;
 
+    /**
+     * @var array<Alarm>
+     */
+    private array $alarms = [];
+
     public function __construct(?UniqueIdentifier $uniqueIdentifier = null)
     {
         $this->uniqueIdentifier = $uniqueIdentifier ?? UniqueIdentifier::createRandom();
@@ -48,12 +54,10 @@ public function touch(?Timestamp $dateTime = null): self
         return $this;
     }
 
-    /**
-     * @psalm-suppress InvalidNullableReturnType
-     * @psalm-suppress NullableReturnStatement
-     */
     public function getSummary(): string
     {
+        assert($this->summary !== null);
+
         return $this->summary;
     }
 
@@ -76,12 +80,10 @@ public function unsetSummary(): self
         return $this;
     }
 
-    /**
-     * @psalm-suppress InvalidNullableReturnType
-     * @psalm-suppress NullableReturnStatement
-     */
     public function getDescription(): string
     {
+        assert($this->description !== null);
+
         return $this->description;
     }
 
@@ -145,4 +147,16 @@ public function hasLocation(): bool
     {
         return $this->location !== null;
     }
+
+    public function getAlarms(): array
+    {
+        return $this->alarms;
+    }
+
+    public function addAlarm(Alarm $alarm): self
+    {
+        $this->alarms[] = $alarm;
+
+        return $this;
+    }
 }

src/Domain/ValueObject/Alarm.php

@@ -0,0 +1,74 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject;
+
+use DateInterval;
+use Eluceo\iCal\Domain\ValueObject\Alarm\Action;
+use Eluceo\iCal\Domain\ValueObject\Alarm\Trigger;
+
+class Alarm
+{
+    private Action $action;
+    private Trigger $trigger;
+
+    private int $repeatCount = 0;
+    private ?DateInterval $repeatInterval = null;
+
+    public function __construct(Action $action, Trigger $trigger)
+    {
+        $this->action = $action;
+        $this->trigger = $trigger;
+    }
+
+    public function getAction(): Action
+    {
+        return $this->action;
+    }
+
+    public function getTrigger(): Trigger
+    {
+        return $this->trigger;
+    }
+
+    public function isRepeated(): bool
+    {
+        return $this->repeatCount > 0;
+    }
+
+    public function withRepeat(int $repeatCount, DateInterval $repeatInterval): self
+    {
+        $this->repeatCount = $repeatCount;
+        $this->repeatInterval = $repeatInterval;
+
+        return $this;
+    }
+
+    public function withoutRepeat(): self
+    {
+        $this->repeatCount = 0;
+        $this->repeatInterval = null;
+
+        return $this;
+    }
+
+    public function getRepeatCount(): int
+    {
+        return $this->repeatCount;
+    }
+
+    public function getRepeatInterval(): DateInterval
+    {
+        assert($this->repeatInterval !== null);
+
+        return $this->repeatInterval;
+    }
+}

src/Domain/ValueObject/Alarm/AbsoluteDateTimeTrigger.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject\Alarm;
+
+use Eluceo\iCal\Domain\ValueObject\Timestamp;
+
+final class AbsoluteDateTimeTrigger extends Trigger
+{
+    private Timestamp $dateTime;
+
+    public function __construct(Timestamp $dateTime)
+    {
+        $this->dateTime = $dateTime;
+    }
+
+    public function getDateTime(): Timestamp
+    {
+        return $this->dateTime;
+    }
+}

src/Domain/ValueObject/Alarm/Action.php

@@ -0,0 +1,16 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject\Alarm;
+
+abstract class Action
+{
+}

src/Domain/ValueObject/Alarm/AudioAction.php

@@ -0,0 +1,16 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject\Alarm;
+
+final class AudioAction extends Action
+{
+}

src/Domain/ValueObject/Alarm/DisplayAction.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject\Alarm;
+
+final class DisplayAction extends Action
+{
+    private string $description;
+
+    public function __construct(string $description)
+    {
+        $this->description = $description;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+}

src/Domain/ValueObject/Alarm/EmailAction.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the eluceo/iCal package.
+ *
+ * (c) 2020 Markus Poerschke <[email protected]>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Eluceo\iCal\Domain\ValueObject\Alarm;
+
+final class EmailAction extends Action
+{
+    private string $summary;
+    private string $description;
+
+    public function __construct(string $summary, string $description)
+    {
+        $this->summary = $summary;
+        $this->description = $description;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function getSummary(): string
+    {
+        return $this->summary;
+    }
+}