Broker
in package
The ITip\Broker class is a utility class that helps with processing so-called iTip messages.
iTip is defined in rfc5546, stands for iCalendar Transport-Independent Interoperability Protocol, and describes the underlying mechanism for using iCalendar for scheduling for for example through email (also known as IMip) and CalDAV Scheduling.
This class helps by:
- Creating individual invites based on an iCalendar event for each attendee.
- Generating invite updates based on an iCalendar update. This may result in new invites, updates and cancellations for attendees, if that list changed.
- On the receiving end, it can create a local iCalendar event based on a received invite.
- It can also process an invite update on a local event, ensuring that any overridden properties from attendees are retained.
- It can create a accepted or declined iTip reply based on an invite.
- It can process a reply from an invite and update an events attendee status based on a reply.
Tags
Table of Contents
- $scheduleAgentServerRules : bool
- This setting determines whether the rules for the SCHEDULE-AGENT parameter should be followed.
- $significantChangeProperties : array<string|int, string>
- The broker will try during 'parseEvent' figure out whether the change was significant.
- parseEvent() : array<string|int, mixed>
- This function parses a VCALENDAR object and figure out if any messages need to be sent.
- processMessage() : VCalendar|null
- This method is used to process an incoming itip message.
- parseEventForAttendee() : array<string|int, Message>
- Parse an event update for an attendee.
- parseEventForOrganizer() : array<string|int, mixed>
- This method is used in cases where an event got updated, and we potentially need to send emails to attendees to let them know of updates in the events.
- parseEventInfo() : array<string|int, mixed>
- Returns attendee information and information about instances of an event.
- processMessageCancel() : VCalendar|null
- Processes incoming CANCEL messages.
- processMessageReply() : VCalendar|null
- Processes incoming REPLY messages.
- processMessageRequest() : VCalendar|null
- Processes incoming REQUEST messages.
Properties
$scheduleAgentServerRules
This setting determines whether the rules for the SCHEDULE-AGENT parameter should be followed.
public
bool
$scheduleAgentServerRules
= true
This is a parameter defined on ATTENDEE properties, introduced by RFC 6638. This parameter allows a caldav client to tell the server 'Don't do any scheduling operations'.
If this setting is turned on, any attendees with SCHEDULE-AGENT set to CLIENT will be ignored. This is the desired behavior for a CalDAV server, but if you're writing an iTip application that doesn't deal with CalDAV, you may want to ignore this parameter.
$significantChangeProperties
The broker will try during 'parseEvent' figure out whether the change was significant.
public
array<string|int, string>
$significantChangeProperties
= ['DTSTART', 'DTEND', 'DURATION', 'DUE', 'RRULE', 'RDATE', 'EXDATE', 'STATUS']
It uses a few different ways to do this. One of these ways is seeing if certain properties changed values. This list of specified here.
This list is taken from:
- http://tools.ietf.org/html/rfc5546#section-2.1.4
Methods
parseEvent()
This function parses a VCALENDAR object and figure out if any messages need to be sent.
public
parseEvent([VCalendar|string $calendar = null ], string|array<string|int, mixed> $userHref[, VCalendar|string $oldCalendar = null ]) : array<string|int, mixed>
A VCALENDAR object will be created from the perspective of either an attendee, or an organizer. You must pass a string identifying the current user, so we can figure out who in the list of attendees or the organizer we are sending this message on behalf of.
It's possible to specify the current user as an array, in case the user has more than one identifying href (such as multiple emails).
It $oldCalendar is specified, it is assumed that the operation is updating an existing event, which means that we need to look at the differences between events, and potentially send old attendees cancellations, and current attendees updates.
If $calendar is null, but $oldCalendar is specified, we treat the operation as if the user has deleted an event. If the user was an organizer, this means that we need to send cancellation notices to people. If the user was an attendee, we need to make sure that the organizer gets the 'declined' message.
Parameters
- $calendar : VCalendar|string = null
- $userHref : string|array<string|int, mixed>
- $oldCalendar : VCalendar|string = null
Return values
array<string|int, mixed> —processMessage()
This method is used to process an incoming itip message.
public
processMessage(Message $itipMessage[, VCalendar $existingObject = null ]) : VCalendar|null
Examples:
-
A user is an attendee to an event. The organizer sends an updated meeting using a new iTip message with METHOD:REQUEST. This function will process the message and update the attendee's event accordingly.
-
The organizer cancelled the event using METHOD:CANCEL. We will update the users event to state STATUS:CANCELLED.
-
An attendee sent a reply to an invite using METHOD:REPLY. We can update the organizers event to update the ATTENDEE with its correct PARTSTAT.
The $existingObject is updated in-place. If there is no existing object (because it's a new invite for example) a new object will be created.
If an existing object does not exist, and the method was CANCEL or REPLY, the message effectively gets ignored, and no 'existingObject' will be created.
The updated $existingObject is also returned from this function.
If the iTip message was not supported, we will always return false.
Parameters
Return values
VCalendar|null —parseEventForAttendee()
Parse an event update for an attendee.
protected
parseEventForAttendee(VCalendar $calendar, array<string|int, mixed> $eventInfo, array<string|int, mixed> $oldEventInfo, string $attendee) : array<string|int, Message>
This function figures out if we need to send a reply to an organizer.
Parameters
- $calendar : VCalendar
- $eventInfo : array<string|int, mixed>
- $oldEventInfo : array<string|int, mixed>
- $attendee : string
Return values
array<string|int, Message> —parseEventForOrganizer()
This method is used in cases where an event got updated, and we potentially need to send emails to attendees to let them know of updates in the events.
protected
parseEventForOrganizer(VCalendar $calendar, array<string|int, mixed> $eventInfo, array<string|int, mixed> $oldEventInfo) : array<string|int, mixed>
We will detect which attendees got added, which got removed and create specific messages for these situations.
Parameters
- $calendar : VCalendar
- $eventInfo : array<string|int, mixed>
- $oldEventInfo : array<string|int, mixed>
Return values
array<string|int, mixed> —parseEventInfo()
Returns attendee information and information about instances of an event.
protected
parseEventInfo([VCalendar $calendar = null ]) : array<string|int, mixed>
Returns an array with the following keys:
- uid
- organizer
- organizerName
- organizerScheduleAgent
- organizerForceSend
- instances
- attendees
- sequence
- exdate
- timezone - strictly the timezone on which the recurrence rule is based on.
- significantChangeHash
- status
Parameters
- $calendar : VCalendar = null
Return values
array<string|int, mixed> —processMessageCancel()
Processes incoming CANCEL messages.
protected
processMessageCancel(Message $itipMessage[, VCalendar $existingObject = null ]) : VCalendar|null
This is a message from an organizer, and means that either an attendee got removed from an event, or an event got cancelled altogether.
Parameters
Return values
VCalendar|null —processMessageReply()
Processes incoming REPLY messages.
protected
processMessageReply(Message $itipMessage[, VCalendar $existingObject = null ]) : VCalendar|null
The message is a reply. This is for example an attendee telling an organizer he accepted the invite, or declined it.
Parameters
Return values
VCalendar|null —processMessageRequest()
Processes incoming REQUEST messages.
protected
processMessageRequest(Message $itipMessage[, VCalendar $existingObject = null ]) : VCalendar|null
This is message from an organizer, and is either a new event invite, or an update to an existing one.