Add documentation for ALARM component

[markuspoerschke]

No description provided.

[JorisDebonnet]

Any hint you can give already? When I try:

$event->addAlarm(
	new Alarm(
		new Alarm\DisplayAction('Reminder: this task is scheduled now.'),
		new Alarm\RelativeTrigger(new \DateInterval('PT1M'))
	)
);

Then the output is:

BEGIN:VALARM
ACTION:DISPLAY
DESCRIPTION:Reminder: this task is scheduled now.
TRIGGER:PT1M
END:VALARM

But that doesn't do anything in any of the calendar apps I have tested. Also, I notice in online examples that the trigger usually starts with a - sign (to indicate "before" rather than "after" the DTSTART, I assume), but I cannot create a negative DateInterval, so not sure how to implement that here.

[markuspoerschke]

@JorisDebonnet Here you can find a working example

<?php

use Eluceo\iCal\Domain\Entity\Calendar;

require_once __DIR__ . '/../vendor/autoload.php';

$event = new \Eluceo\iCal\Domain\Entity\Event();
$event->setSummary('Alarm Test');
$event->setOccurrence(
    new \Eluceo\iCal\Domain\ValueObject\TimeSpan(
        new \Eluceo\iCal\Domain\ValueObject\DateTime(new DateTimeImmutable('2021-04-25 17:30:00'), true),
        new \Eluceo\iCal\Domain\ValueObject\DateTime(new DateTimeImmutable('2021-04-25 17:45:00'), true),
    )
);

$alarmInterval = new DateInterval('PT1M');
$alarmInterval->invert = 1;
$event->addAlarm(
    new \Eluceo\iCal\Domain\ValueObject\Alarm(new \Eluceo\iCal\Domain\ValueObject\Alarm\AudioAction(),
        new \Eluceo\iCal\Domain\ValueObject\Alarm\RelativeTrigger($alarmInterval)
    )
);

// 2. Create Calendar domain entity.
$calendar = new Calendar([$event]);

echo (new \Eluceo\iCal\Presentation\Factory\CalendarFactory())->createCalendar($calendar);

The clue is indeed to make the date interval negative.

There are the following ways in PHP to make DateTimeInterval negative:

$alarmInterval = new DateInterval('PT1M');
$alarmInterval->invert = 1;

or

$alarmInterval = DateInterval::createFromDateString('1 minute ago');

[u01jmg3]

Hello. I landed on this issue after looking for upgrade documentation on setting up an alarm and this was super helpful. Is this something that could go into the main website docs as it seems to be missing? Happy to start an initial PR on configuring an alarm and its display action.