Calendar Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oro/calendar-bundle
   

   Ensure your AppKernel.php includes the bundle:

   $bundles[] = new Oro\Bundle\CalendarBundle\OroCalendarBundle();
   

2. Database Migrations: Run migrations to create required tables:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case:

   • User Calendar: Automatically created for each user. Access via /calendar (default route).
   • System Calendar: Create via admin UI (/calendar/system-calendar/create).

Key Routes

Initial Configuration

• Twig Extensions: Automatically registered for date formatting and recurrence rules.
• ACL: Default capabilities (oro_calendar_view, oro_calendar_edit) are pre-configured.

Implementation Patterns

Core Workflows

1. Event Creation (User/System)

// Create a one-time event
$event = new CalendarEvent();
$event->setTitle('Team Meeting')
      ->setStartDate(new \DateTime('2023-12-25 10:00:00'))
      ->setEndDate(new \DateTime('2023-12-25 11:00:00'))
      ->setDescription('Weekly sync')
      ->setCalendar($user->getDefaultCalendar()); // User calendar
$em->persist($event);
$em->flush();

// Create a recurring event (weekly)
$event->setRecurrenceRule('FREQ=WEEKLY;BYDAY=MO,WE,FR');

2. System Calendar Integration

// Assign a system calendar to an event
$systemCalendar = $em->getRepository(SystemCalendar::class)->findOneBy(['name' => 'Holidays']);
$event->setCalendar($systemCalendar);

3. Custom Event Types

Extend CalendarEvent via inheritance:

class CustomEvent extends CalendarEvent
{
    private $customField;

    // Add getters/setters for custom fields
    public function getCustomField(): ?string
    {
        return $this->customField;
    }
}

Update config.yml:

oro_calendar:
    entities:
        calendar_event:
            custom_event:
                class: App\Entity\CustomEvent
                label: 'Custom Event'

4. Recurrence Rules

Use iCal-style rules (e.g., FREQ=MONTHLY;BYDAY=1FR for "first Friday of the month"):

$event->setRecurrenceRule('FREQ=MONTHLY;BYDAY=1FR');

5. DataGrid Integration

Customize event lists via YAML:

# config/oro/datagrids/calendar_event.yml
oro_calendar_event:
    source:
        type: orm
        query:
            select: [e.id, e.title, e.startDate, e.endDate]
            from: [Oro\Bundle\CalendarBundle\Entity\CalendarEvent e]
    columns:
        title:
            label: oro.calendar.entity_event.field_title
        startDate:
            type: datetime

Integration Tips

• Frontend: Use oro_calendar Twig functions for rendering:

  {{ oro_calendar.render_event(event) }}
  

• API: Expose events via API Platform or custom controllers:

  #[Route('/api/events', methods: ['GET'])]
  public function getEvents(CalendarEventRepository $repo): JsonResponse
  {
      return new JsonResponse($repo->findAll());
  }
  

• Sync with External Calendars: Implement Oro\Bundle\CalendarBundle\Model\CalendarSyncInterface for custom sync logic.

Gotchas and Tips

Common Pitfalls

1. ACL Misconfigurations:

   • Default capabilities (oro_calendar_view, oro_calendar_edit) must be granted to roles.
   • System calendars require oro_calendar_system_manage capability.
   • Fix: Use php bin/console oro:security:check to validate ACLs.

2. Recurrence Rule Parsing:

   • Invalid rules (e.g., FREQ=DAILY;INTERVAL=0) break event generation.
   • Tip: Validate rules with Oro\Bundle\CalendarBundle\Provider\RecurrenceRuleParser.

3. Time Zone Issues:

   • Events use the system timezone. Override in config.yml:

     oro_calendar:
         timezone: 'America/New_York'
     

4. Search Indexing:

   • Changes to event links (e.g., v5.0.0) require reindexing:

     php bin/console oro:search:reindex --class="Oro\Bundle\CalendarBundle\Entity\CalendarEvent"
     

5. Deprecated Services:

   • Avoid oro_calendar.twig.dateformat (private in v2.1.0+). Use Twig filters directly:

     {{ event.startDate|date('Y-m-d H:i') }}
     

Debugging Tips

• Event Generation:
  • Check recurrence rules with:

    $parser = $this->container->get('oro_calendar.provider.recurrence_rule_parser');
    $parser->parse('FREQ=WEEKLY;BYDAY=MO');
    

• Database Issues:
  • Verify calendar_event and calendar tables exist. Run migrations if missing.
• Frontend Rendering:
  • Clear cache after customizing Twig templates:

    php bin/console cache:clear
    

Extension Points

1. Custom Event Fields:

   • Extend CalendarEvent and update oro_calendar.entities.calendar_event config.
   • Example: Add a priority field and filter events in DataGrid:

     columns:
         priority:
             type: twig
             template: OroCalendarBundle:Event:priority.html.twig
     

2. Event Validation:

   • Override Oro\Bundle\CalendarBundle\Validator\Constraints\Event for custom rules:

     use Oro\Bundle\CalendarBundle\Validator\Constraints as OroCalendarAssert;
     
     /**
      * @OroCalendarAssert\Event(
      *     customMessage = "Event must be at least 30 minutes long."
      * )
      */
     

3. Calendar Sync:

   • Implement CalendarSyncInterface for external sync (e.g., Google Calendar):

     class GoogleCalendarSync implements CalendarSyncInterface
     {
         public function syncEvents(Calendar $calendar): void
         {
             // Fetch from Google API and update local events
         }
     }
     

   • Register as a service:

     services:
         app.google_calendar_sync:
             class: App\Service\GoogleCalendarSync
             tags:
                 - { name: oro_calendar.sync_provider }
     

4. Custom Views:

   • Override Twig templates in templates/OroCalendarBundle/ (e.g., event/list.html.twig).
   • Extend controllers via event subscribers:

     class CustomCalendarSubscriber implements EventSubscriberInterface
     {
         public static function getSubscribedEvents(): array
         {
             return [
                 CalendarEvents::EVENT_PRE_CREATE => 'onPreCreate',
             ];
         }
     
         public function onPreCreate(CreateEvent $event): void
         {
             $event->getEntity()->setCustomField('default_value');
         }
     }
     

Configuration Quirks

• Default Calendar:
  • Users without a default calendar will see an error. Set one via:

    $user->setDefaultCalendar($user->getCalendars()->first());
    

• Recurrence End Dates:
  • Use untilDate for finite recurrences:

    $event->setRecurrenceRule('FREQ=DAILY;UNTIL=20231231T235959Z');
    

• Event Overlaps:
  • The bundle does not enforce overlaps by default. Add validation:

    $validator = $this->container->get('validator');
    $errors = $validator->validate($event, [
        new EventOverlap(['calendar' => $event->getCalendar()]),
    ]);