| currentMenu | title |
|---|---|
components/event |
Event Component |
The event domain object \Eluceo\iCal\Domain\Entity\Event represents a scheduled amount of time on a calendar.
For example, it can be an one-hour lunch meeting from 12:00 to 13:00 on 24th of december.
When creating a new instance with the static method Event::create, the optional parameter $uniqueIdentifier can be set.
If it is not set, then a random, but unique identifier is created.
use Eluceo\iCal\Domain\Entity\Event;
$event = new Event();To set the properties, a fluent interface can be used:
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\Date;
use Eluceo\iCal\Domain\ValueObject\SingleDay;
$event = (new Event())
->setSummary('Lunch Meeting')
->setDescription('Lorem Ipsum...')
->setOccurrence(new SingleDay(new Date()));The following sections explain the properties of the domain object:
A unique identifier must be a globally unique value. When the value is generated, you must guarantee that it is unique. Mostly this can be accomplished by adding the domain name to the identifier.
Given, the event id is stored in $myEventUid, than the event can be created using that id with the following code:
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\UniqueIdentifier;
$myEventUid = 'example.com/event/1234';
$uniqueIdentifier = new UniqueIdentifier($myEventUid);
$event = new Event($uniqueIdentifier);The $touchedAt property is a Timestamp that indicates when the event was changed.
If the event was just created, the value is equal to the creation time.
Therefore, the default value will be the current time.
The value can be changed using the touch method.
use Eluceo\iCal\Domain\ValueObject\Timestamp;
use Eluceo\iCal\Domain\Entity\Event;
$event = new Event();
$event->touch(new Timestamp());A timestamp object can be also created from an object that implements \DateTimeInterface like this:
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\Timestamp;
$event = new Event();
$dateTime = DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-24');
$timestamp = new Timestamp($dateTime);
$event->touch($timestamp);The summary of an event is a short, single line text, that describes the event.
use Eluceo\iCal\Domain\Entity\Event;
$event = new Event();
$event->setSummary('Lunch Meeting');In addition to the summary, the description gives more information about the event.
use Eluceo\iCal\Domain\Entity\Event;
$event = new Event();
$event->setDescription('Lorem Ipsum Dolor...');The occurrence property of an event defines, when the event takes place. There are currently three different types of occurrences possible:
The event will take place all day on the specified date.
The following example shows how to set the occurrence for an event that takes place on 24th of December 2019:
use Eluceo\iCal\Domain\ValueObject\SingleDay;
use Eluceo\iCal\Domain\ValueObject\Date;
use Eluceo\iCal\Domain\Entity\Event;
$date = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-24'));
$occurrence = new SingleDay($date);
$event = new Event();
$event->setOccurrence($occurrence);A multi day event will take place on more than one consecutive day. The multi day occurrence defines a span of days.
The constructor MultiDay($firstDay, $lastDay) accepts two dates:
- The
$firstDayattribute defines the first inclusive day, the event will take place. - The
$lastDayattribute defines the last inclusive day, the event will take place.
The given example
use Eluceo\iCal\Domain\ValueObject\MultiDay;
use Eluceo\iCal\Domain\ValueObject\Date;
use Eluceo\iCal\Domain\Entity\Event;
$firstDay = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-24'));
$lastDay = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-26'));
$occurrence = new MultiDay($firstDay, $lastDay);
$event = new Event();
$event->setOccurrence($occurrence);will create an event that takes place on the 24th, 25th and 26th of december 2019.
Unlike the previous types of occurrence, the timespan will consider the actual time, the event takes place. A timespan defines the start and end time of an event. These times define the span within the event will take place.
The following code example
use Eluceo\iCal\Domain\ValueObject\TimeSpan;
use Eluceo\iCal\Domain\ValueObject\DateTime;
use Eluceo\iCal\Domain\Entity\Event;
$start = new DateTime(DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2020-01-03 13:00:00'), false);
$end = new DateTime(DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2020-01-03 14:00:00'), false);
$occurrence = new TimeSpan($start, $end);
$event = new Event();
$event->setOccurrence($occurrence);describes an event that takes place between 1pm and 2pm on 3rd of january 2020.
The location defines where an event takes place. The value can be a generic name like the name of a meeting room or an address. As an optional property, the exact geographic position can be added.
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\Location;
use Eluceo\iCal\Domain\ValueObject\GeographicPosition;
$location = new Location('North Pole');
// optionally you can create a location with a title for X-APPLE-STRUCTURED-LOCATION attribute
$location = new Location('North Pole', 'Middle of nowhere');
// optionally a location with a geographical position can be created
$location = $location->withGeographicPosition(new GeographicPosition(64.751111, 147.349444));
$event = new Event();
$event->setLocation($location);A document can be associated with an event. It can be either be added as a URI or directly embedded as binary content. It is strongly recommended to use the URI attachment, since binary content is not supported by all calendar applications.
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\Attachment;
use Eluceo\iCal\Domain\ValueObject\BinaryContent;
use Eluceo\iCal\Domain\ValueObject\Uri;
$urlAttachment = new Attachment(
new Uri('https://example.com/test.txt'),
'text/plain'
);
$binaryContentAttachment = new Attachment(
new BinaryContent(file_get_contents('test.txt')),
'text/plain'
);
$event = new Event();
$event->addAttachment($urlAttachment);
$event->addAttachment($binaryContentAttachment);