Calendar Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require adesigns/calendar-bundle fos/jsrouting-bundle
   

   Ensure FOSJsRoutingBundle is registered in AppKernel.php before CalendarBundle.

2. Configure the Bundle Add to config.yml:

   adesigns_calendar:
       event_loader:
           route: your_event_loader_route  # Must match your AJAX route
   

3. First Use Case: Basic Calendar View

   • Create a controller to render the calendar:

     // src/Controller/CalendarController.php
     use ADesigns\CalendarBundle\Controller\CalendarController;
     
     class CalendarController extends CalendarController
     {
         public function indexAction()
         {
             return $this->renderCalendar();
         }
     }
     

   • Define a route:

     # app/config/routing.yml
     calendar:
         resource: "@CalendarBundle/Resources/config/routing.yml"
         prefix:   /
     

   • Access /calendar to see the default FullCalendar UI.

Implementation Patterns

Core Workflow: Event Management

1. Define Event Entities Annotate your event entity with ADesigns\CalendarBundle\Model\EventInterface:

   use ADesigns\CalendarBundle\Model\EventInterface;
   
   class Event implements EventInterface
   {
       // Required fields:
       private $id;
       private $title;
       private $start;
       private $end;
       // ...
   }
   

2. Create an Event Loader Extend ADesigns\CalendarBundle\Event\EventLoaderInterface:

   use ADesigns\CalendarBundle\Event\EventLoaderInterface;
   
   class CustomEventLoader implements EventLoaderInterface
   {
       public function load($resourceId, $start, $end, $timezone, UserInterface $user = null)
       {
           return $this->getDoctrine()
               ->getRepository('AppBundle:Event')
               ->findByStartBetween($start, $end);
       }
   }
   

   Register it in services.yml:

   services:
       app.event_loader:
           class: AppBundle\Event\CustomEventLoader
           tags:
               - { name: adesigns_calendar.event_loader, resource: "events" }
   

3. Configure AJAX Endpoint Add a route for event fetching:

   # app/config/routing.yml
   app_calendar_events:
       path:     /calendar/events
       defaults: { _controller: AppBundle\Controller\CalendarController::eventsAction }
   

   Controller:

   public function eventsAction(Request $request)
   {
       return $this->get('adesigns_calendar.event_loader')->load(
           $request->query->get('resource'),
           $request->query->get('start'),
           $request->query->get('end'),
           $request->query->get('timezone')
       );
   }
   

4. Render the Calendar in Twig

   {{ render(controller('ADesignsCalendarBundle:Calendar:index', {
       'resource': 'events',
       'events': app.user
   })) }}
   

Advanced Patterns

• Dynamic Timezones Use timezone parameter in AJAX calls and handle it in the loader:

  $timezone = new \DateTimeZone($request->query->get('timezone'));
  $start->setTimezone($timezone);
  

• Custom Views Override templates in templates/ADesignsCalendarBundle/ to modify UI.

• Recurring Events Use ADesigns\CalendarBundle\Model\RecurringEventInterface and implement logic in your loader.

• Event Editing Extend ADesigns\CalendarBundle\Event\EventManagerInterface to handle CRUD operations.

Gotchas and Tips

Common Pitfalls

1. FOSJsRouting Dependency

   • Issue: Missing fos_js_routing.js causes AJAX routes to fail.
   • Fix: Ensure FOSJsRoutingBundle is installed and the JS file is included in your layout:

     {{ fos_js_routing_js() }}
     

2. Timezone Mismatches

   • Issue: Events appear at wrong times due to timezone conflicts.
   • Fix: Explicitly set timezones in both the loader and frontend:

     eventSources: [{
         url: Routing.generate('app_calendar_events', { timezone: Intl.DateTimeFormat().resolvedOptions().timeZone }),
         // ...
     }]
     

3. Event Loader Caching

   • Issue: Events not updating in real-time.
   • Fix: Disable caching in the loader or use cache invalidation:

     # config.yml
     adesigns_calendar:
         event_loader:
             cache: false  # Disable if real-time updates are needed
     

4. Archived Package Risks

   • Issue: No updates since 2019; compatibility with modern Symfony/Laravel may break.
   • Mitigation:
     • Fork the package and update dependencies (e.g., Symfony 4/5, Doctrine ORM).
     • Consider alternatives like fullcalendar-php for Laravel.

Debugging Tips

1. Check AJAX Responses Use browser dev tools to inspect the /calendar/events endpoint. Ensure:

   • The response is valid JSON.
   • The start/end parameters are correctly formatted (ISO 8601).

2. Symfony Debug Toolbar Enable the toolbar to inspect:

   • Event loader service calls.
   • Doctrine queries fired by the loader.

3. Frontend Console Errors FullCalendar logs errors to the browser console. Common issues:

   • Missing eventSources configuration.
   • Invalid event data format (e.g., missing title or start).

Extension Points

1. Custom Event Data Extend the event model to include additional fields:

   class Event implements EventInterface
   {
       private $color;  // Custom field
       // ...
   }
   

   Map it to FullCalendar:

   eventRender: function(event, element) {
       element.css('background-color', event.color);
   }
   

2. Event Categories Use event categories for filtering:

   class Event implements EventInterface
   {
       private $category;
       // ...
   }
   

   Filter in JavaScript:

   eventSources: [{
       url: '/calendar/events',
       color: 'category-specific-color',
       textColor: 'white'
   }]
   

3. Integration with Laravel (Symfony Alternative)

   • Replace EventLoaderInterface with a Laravel service provider.
   • Use Laravel’s route caching (php artisan route:cache) for FOSJsRouting.
   • Override bundle templates in resources/views/vendor/adesigns-calendar.