Calendar Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require agantarcom/calendar-bundle
   

   For non-Flex projects, manually add the bundle to config/bundles.php:

   AgantarCom\CalendarBundle\CalendarBundle::class => ['all' => true],
   

2. First Use Case: Generate a basic calendar view in a Twig template:

   {{ render(controller('AgantarComCalendarBundle:Calendar:index')) }}
   

   This renders a default monthly calendar with no customization.

3. Where to Look First:

   • Documentation: Check the README for basic usage.
   • Twig Templates: Explore templates/AgantarComCalendarBundle/Calendar/ for customization hooks.
   • Services: The bundle provides a calendar.manager service for programmatic calendar generation.

Implementation Patterns

Core Workflows

1. Dynamic Calendar Rendering: Use the calendar.manager service to generate calendars dynamically:

   // src/Controller/CalendarController.php
   use AgantarCom\CalendarBundle\Manager\CalendarManager;
   
   class CalendarController extends AbstractController {
       public function show(CalendarManager $calendarManager, int $year, int $month) {
           $calendar = $calendarManager->generate($year, $month);
           return $this->render('calendar/index.html.twig', ['calendar' => $calendar]);
       }
   }
   

2. Twig Integration: Extend the default Twig templates by overriding them in your project:

   templates/AgantarComCalendarBundle/Calendar/
   ├── index.html.twig       # Override full layout
   ├── _calendar.html.twig   # Override calendar table
   └── _day.html.twig        # Override individual day cells
   

3. Event Integration: Pass events to the calendar manager to highlight dates:

   $events = [
       ['date' => '2024-10-15', 'title' => 'Team Meeting', 'class' => 'event-success'],
       ['date' => '2024-10-20', 'title' => 'Deadline', 'class' => 'event-danger'],
   ];
   $calendar = $calendarManager->generate($year, $month, $events);
   

4. Localization: Override the default date format or month names via Twig:

   {% set calendar = calendar|calendar_format('d M Y', 'en_US') %}
   

Integration Tips

• Symfony Forms: Combine with Symfony’s form components for interactive calendars.
• APIs: Use the CalendarManager in APIs to return calendar data as JSON:

  return $this->json($calendarManager->generateAsArray($year, $month));
  

• Caching: Cache generated calendars for static pages:

  $cacheKey = "calendar_{$year}_{$month}";
  if (!$calendar = $cache->get($cacheKey)) {
      $calendar = $calendarManager->generate($year, $month);
      $cache->set($cacheKey, $calendar, 3600);
  }
  

Gotchas and Tips

Pitfalls

1. Template Overrides:

   • Forgetting to clear the cache after overriding Twig templates (php bin/console cache:clear).
   • Incorrect template paths (must match AgantarComCalendarBundle/Calendar/ structure).

2. Date Handling:

   • The bundle assumes DateTime objects or Y-m-d strings. Invalid formats may throw exceptions.
   • Timezone-sensitive operations (e.g., generate()) default to the server’s timezone. Explicitly set it if needed:

     $calendarManager->generate($year, $month, [], 'Europe/London');
     

3. Event Data:

   • Events must include a date key (string or DateTime). Missing or malformed data will be ignored silently.
   • Custom event classes (e.g., class for styling) are not validated; ensure they match your CSS.

4. Symfony Flex Compatibility:

   • If using Symfony <5.0, manually register the bundle in AppKernel.php (though the bundle claims Flex compatibility).

Debugging

• No Calendar Rendered?: Check if the bundle is enabled (config/bundles.php) and the route exists (php bin/console debug:router). Verify the Twig template path is correct.

• Styling Issues: Inspect the generated HTML for missing classes or IDs. Override _day.html.twig to add custom classes:

  <td class="day {{ day.class }}">{{ day.date|date('d') }}</td>
  

Extension Points

1. Custom Calendar Types: Extend the CalendarManager to support weekly/yearly views:

   // src/Service/CustomCalendarManager.php
   class CustomCalendarManager extends CalendarManager {
       public function generateWeekly(int $year, int $week) { ... }
   }
   

   Register it as a service and replace the default manager in config/services.yaml:

   services:
       AgantarCom\CalendarBundle\Manager\CalendarManager:
           alias: custom_calendar_manager
   

2. Event Providers: Create a custom event provider to fetch events from a database:

   // src/Event/DatabaseEventProvider.php
   class DatabaseEventProvider implements EventProviderInterface {
       public function getEvents(int $year, int $month): array {
           return $entityManager->getRepository(Event::class)->findByMonth($year, $month);
       }
   }
   

   Bind it to the calendar.manager service in services.yaml:

   services:
       App\Event\DatabaseEventProvider:
           tags: ['agantar_com.calendar.event_provider']
   

3. Configuration: Override default settings (e.g., start day of week) in config/packages/agantar_com_calendar.yaml:

   agantar_com_calendar:
       first_day_of_week: 1  # Monday
       show_week_numbers: true
   

Pro Tips

• Lazy Loading: Use the generateAsArray() method to build calendars client-side with JavaScript.
• Accessibility: Add ARIA attributes in _day.html.twig for screen readers:

  <td aria-label="{{ day.date|date('d MMMM Y') }}">{{ day.date|date('d') }}</td>
  

• Testing: Mock the CalendarManager in PHPUnit:

  $this->mockBuilder()
       ->disableOriginalConstructor()
       ->getMock()
       ->method('generate')
       ->willReturn($mockCalendarData);