Skip to content
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@balazscsaba @anyt
162 lines (141 sloc) 6.56 KB

Recurring Events

Table of content


This functionality allows to manage recurring events. In common case recurring event is saved as a single instance of event along with 'recurrence' field where recurring pattern is stored. Based on this pattern Calendar UI expands instance of one recurring event into a sequence of occurrences.

Currently recurring events can be managed only using API. UI exposes these events but has limitations to manage them. For instance only title and description fields of recurring event could be edited using UI. Also it's not possible to create recurring event using UI at the moment.

Recurrence Pattern

Each calendar event has recurrence field. This is a dictionary containing fields related to the event recurrence. Some fields are mandatory for all recurrence patterns, and some fields are required only for some patterns. The fields are described in the following table:

Field Name Recurrence Pattern
Daily Weekly Monthly MonthNth Yearly YearNth
recurrenceType daily weekly monthly monthnth yearly yearnth
interval Number of day Number of week Number of month Number of month (a multiple of 12, i.e. 12, 24, 36, 48 etc.
instance Not used Not used Not used A value from 1 to 5 Not used A value from 1 to 5
dayOfWeek Not used Array of week days Not used Array containing one week day Not used Array containing one week day
dayOfMonth Not used Not used Day of month Not used Day of month Not used
monthOfYear Not used Not used Not used Not used Month number from 1 to 12
startTime Range of recurrence - Start (mandatory)
endTime Range of recurrence - End (mandatory)
occurrences Range of recurrence - End after X occurrences (optional)
timeZone The time zone in which the time is specified (mandatory)

In common case for recurring event only one entity of OroCalendarBundle:CalendarEvent is created with reference to entity of OroCalendarBundle:Recurrence. When API request with date range will be send to server, it will dynamically expand each instance of recurring event into occurrences of this recurring event. Each occurrence event will have the same data as original recurring event, but with dynamically calculated start and end dates.


Each occurrence of a recurrent event can be modified so it differs from other occurrences. Such event has it's own step and called "exception" event. These exceptions are represented by separate event entities with additional fields. The standard event fields (title, description, start, end, etc.) can differ from the parent recurrence event fields. Here is the list of additional fields which are applicable only for exception events:

  • recurringEventId – the id of the parent recurring event.
  • originalStart – the original start date and time of this occurrence. It may differ from the actual start date for the recurrence.
  • isCancelled – A boolean field indicating whether the occurrence was cancelled (removed from the user’s calendar).

Recurrence Validation

To make sure that Recurrence pattern has all needed data it can be validated with recurrence model:

use Oro\Bundle\CalendarBundle\Model\Recurrence as RecurrenceModel;

/** @var \Symfony\Component\Validator\Validator\ValidatorInterface $validator */
/** @var \Oro\Bundle\CalendarBundle\Entity\Recurrence $recurrence */
$model = new RecurrenceModel($this->validator);

Key Classes

Here is a list of key classes:



  • Model/Recurrence - Model represents domain logic related to recurrence. Recurrence entity is passed to model in most cases to fulfill it's responsibilities. Can be used by client code in the application.

Model / Strategies Strategies implements different types of recurrence patterns. Model uses strategies to delegate responsibilities related to different recurrence patterns. Strategies should not be used directly in application client code.

You can’t perform that action at this time.