Events Calendar Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require sitepark/atoolo-events-calendar-bundle
   

   Ensure your config/bundles.php includes:

   Sitepark\AtooloEventsCalendarBundle\AtooloEventsCalendarBundle::class => ['all' => true],
   

2. Configure Database & CMS:

   • Run migrations (if applicable) to set up event tables.
   • Configure the bundle in config/packages/atoolo_events_calendar.yaml:

     atoolo_events_calendar:
         rce:
             enabled: true
             blacklisted_dates: ['2024-12-25'] # Example: Skip holidays
         ical:
             base_url: '%env(ICAL_BASE_URL)%'
     

3. First Use Case:

   • Display Events in a Controller:

     use Sitepark\AtooloEventsCalendarBundle\Service\EventService;
     
     public function showEvents(EventService $eventService)
     {
         $events = $eventService->findBy(['active' => true], ['startDate' => 'ASC']);
         return view('events.index', compact('events'));
     }
     

   • Render Events in Twig:

     {% for event in events %}
         <div class="event">
             <h3>{{ event.title }}</h3>
             <p>{{ event.startDate|date('F j, Y') }} - {{ event.endDate|date('F j, Y') }}</p>
         </div>
     {% endfor %}
     

4. Key Documentation:

   • Official Docs
   • Focus on:
     • EventService for CRUD operations.
     • SchedulingFactory for date/time handling.
     • iCal API endpoints (/api/ical/{eventId}).

Implementation Patterns

Core Workflows

1. Event Management

• Create/Update Events: Use the EventManager service to handle event lifecycle:

  $event = $eventManager->create([
      'title' => 'Tech Conference',
      'startDate' => '2024-10-15T09:00:00',
      'endDate' => '2024-10-17T18:00:00',
      'categories' => ['tech', 'conference'],
      'venue' => 'Online',
  ]);
  $eventManager->save($event);
  

  • Tip: Use SchedulingFactory to parse raw date strings (e.g., "2024-10-15 09:00").

• Bulk Operations: Leverage the RceIndexer for external event imports (e.g., from CSV or third-party APIs):

  $indexer = $container->get('atoolo_events_calendar.rce_indexer');
  $indexer->indexEvents($externalEventsData);
  

2. Filtering & Search

• Date-Based Filtering:

  $events = $eventService->findByDateRange(
      new \DateTime('2024-01-01'),
      new \DateTime('2024-12-31')
  );
  

• Category/Keyword Search: Use the EventRepository:

  $events = $eventRepository->findBy(['categories' => 'tech']);
  

  • GraphQL: Query events via GraphQL:

    query {
      eventsTeaser(filter: {categories: ["tech"]}) {
        title
        startDate
      }
    }
    

3. iCal Integration

• Export Events to iCal:

  $icalContent = $icalService->generateForEvent($eventId, $occurrence = null);
  return response($icalContent, 200, [
      'Content-Type' => 'text/calendar',
      'Content-Disposition' => 'attachment; filename="event.ics"',
  ]);
  

  • Searchable iCal: Use /api/ical/search/{query} for dynamic iCal generation (e.g., filter by keyword).

4. Recurring Events

• Handle Recurring Patterns:

  $scheduling = $schedulingFactory->createRecurring(
      '2024-01-01T10:00:00',
      '2024-12-31T11:00:00',
      'P1W' // Weekly recurrence
  );
  $event->setScheduling($scheduling);
  

  • Gotcha: Ensure endDate is explicitly set for recurring events to avoid infinite loops.

5. CMS Integration

• Resource Channel Events (RCE): Configure RCE in config/packages/atoolo_events_calendar.yaml:

  rce:
      theme_anchor: 'events' # Customize theme anchor for RCE
      simple_category_map: true # Simplify category handling
  

  • Indexing: Use the RceIndexer to sync events with the CMS:

    $indexer->index(); // Runs on schedule or manually
    

Integration Tips

Laravel-Specific Adaptations

1. Service Container: Bind the bundle’s services to Laravel’s container in AppServiceProvider:

   public function register()
   {
       $this->app->bind('atoolo_events_calendar.event_service', function ($app) {
           return new \Sitepark\AtooloEventsCalendarBundle\Service\EventService(
               $app->make('atoolo_events_calendar.event_repository')
           );
       });
   }
   

2. Routing: Extend Laravel’s routes to include iCal endpoints:

   Route::get('/ical/{eventId}', [IcalController::class, 'generate'])->name('events.ical');
   

3. Blade Templates: Share Twig templates with Blade by creating a custom view resolver or using twig directives in Blade:

   // In AppServiceProvider
   Blade::directive('event', function ($expression) {
       return "<?php echo \$this->renderEvent($expression); ?>";
   });
   

4. Event Listeners: Hook into Laravel’s event system for post-save actions:

   Event::listen('eloquent.saved: App\Models\Event', function ($event) {
       // Trigger RCE indexing or send notifications
       $this->app->get('atoolo_events_calendar.rce_indexer')->index();
   });
   

Performance

• Caching: Cache event lists and iCal responses:

  $events = Cache::remember('events_active', now()->addHours(1), function () {
      return $eventService->findBy(['active' => true]);
  });
  

• Database Indexes: Ensure startDate, endDate, and categories are indexed in your events table.

Extending Functionality

• Custom Event Fields: Extend the Event entity or use traits:

  use Sitepark\AtooloEventsCalendarBundle\Entity\Event as BaseEvent;
  
  class CustomEvent extends BaseEvent
  {
      #[ORM\Column(type: 'json')]
      private array $customFields = [];
  }
  

• Validation: Add custom validation rules for events:

  use Illuminate\Validation\Rule;
  
  $validator = Validator::make($data, [
      'startDate' => ['required', 'date', Rule::unique('events')->ignore($event)],
      'endDate' => ['required', 'date', 'after:startDate'],
  ]);
  

Gotchas and Tips

Pitfalls

1. Date Handling Quirks:

   • Timezone Issues: The bundle uses gmdate for scheduling. Ensure your config/app.php timezone matches expectations:

     'timezone' => 'UTC', // Recommended for consistency
     

   • End Date Fallback: If endDate is missing, the bundle may default to startDate. Explicitly set endDate to null for single-day events:

     $scheduling->setEndDate(null);
     

2. RCE Indexing:

   • Blacklisted Dates: Events on blacklisted dates (e.g., holidays) are skipped during RCE indexing. Verify your blacklisted_dates config:

     rce:
         blacklisted_dates: ['2024-12-25', '2024-12-26']
     

   • Inactive Events: The bundle filters out inactive events during RCE indexing (since v1.16.0). Ensure your active flag is correctly set.

3. iCal Generation:

   • Filename Sanitization: iCal filenames are sanitized to avoid invalid characters. Customize the sanitizer if needed:

     $ical