Calendar Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require carlescliment/calendar-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

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

2. Routing: Import routes in config/routes.yaml (Symfony 4+):

   calendar:
       resource: "@BladeTesterCalendarBundle/Resources/config/routing.yml"
       prefix: /calendar
   

3. First Use Case: Create a custom bundle extending BladeTesterCalendarBundle (as shown in the README) to override default behavior. Example:

   // src/YourBundle/YourCalendarBundle.php
   namespace YourBundle;
   
   use BladeTester\CalendarBundle\BladeTesterCalendarBundle as BaseBundle;
   
   class YourCalendarBundle extends BaseBundle {
       public function getParent() { return 'BladeTesterCalendarBundle'; }
   }
   

4. Basic Usage: Inject the CalendarManager service in a controller to fetch events:

   use BladeTester\CalendarBundle\Manager\CalendarManager;
   
   class CalendarController extends Controller {
       public function index(CalendarManager $calendarManager) {
           $events = $calendarManager->getEvents();
           return $this->render('calendar/index.html.twig', ['events' => $events]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Event Management:

   • Use CalendarManager to CRUD events:

     $calendarManager->addEvent($event); // Add
     $calendarManager->updateEvent($event); // Update
     $calendarManager->deleteEvent($event); // Delete
     

   • Filter events by date range:

     $events = $calendarManager->getEventsBetween($startDate, $endDate);
     

2. View Integration:

   • Render default views (agenda, day, week, month) via Twig:

     {% render 'BladeTesterCalendarBundle:Calendar:month' with {'events': events} %}
     

   • Customize templates by overriding bundle views in templates/bundles/BladeTesterCalendarBundle/Calendar/.

3. API-Driven Logic:

   • Fetch raw event data for custom frontends:

     $events = $calendarManager->getAllEvents();
     return $this->json($events);
     

4. Symfony Forms:

   • Use the EventType form for event creation/editing:

     $form = $this->createForm(EventType::class, $event);
     

Integration Tips

• Doctrine ORM: Configure calendar.manager.entity.class in config/packages/calendar.yaml to map events to your entity (e.g., App\Entity\Event).
• Authentication: Secure routes with Symfony’s security component:

  # config/routes.yaml
  calendar:
      resource: "@BladeTesterCalendarBundle/Resources/config/routing.yml"
      prefix: /calendar
      defaults: { _security: "is_granted('ROLE_USER')" }
  

• Localization: Override date formats in config/packages/calendar.yaml:

  calendar:
      date_format: 'd/m/Y'
      time_format: 'H:i'
  

Gotchas and Tips

Pitfalls

1. Bundle Naming Conflict:

   • The README’s BladeTesterCalendarBundle is a placeholder. Replace it with Carlescliment\CalendarBundle (actual package name) in getParent() and routing.

2. Event Entity Mismatch:

   • Ensure your event entity implements BladeTester\CalendarBundle\Model\EventInterface. Common pitfalls:
     • Missing getStart()/getEnd() methods.
     • Incorrect return types (e.g., DateTime vs. string).

3. Routing Overrides:

   • If you extend routing, fully override the parent routes (don’t merge) to avoid conflicts:

     # src/Resources/config/routing.yml
     your_calendar:
         resource: "@YourBundle/Resources/config/routing.yml"
         prefix: /calendar
     

4. Twig Template Caching:

   • Clear cache after overriding templates:

     php bin/console cache:clear
     

Debugging

• Event Not Displaying?:

  • Verify the event’s start and end dates are valid DateTime objects.
  • Check Doctrine mappings if using ORM:

    php bin/console doctrine:schema:validate
    

• 404 on Routes:

  • Ensure the bundle is loaded after frameworks (e.g., WebBundle) in config/bundles.php.

Extension Points

1. Custom Views:

   • Extend the CalendarView class to add new layouts:

     class CustomCalendarView extends CalendarView {
         public function renderWeekView() { /* ... */ }
     }
     

   • Register as a service:

     # config/services.yaml
     services:
         App\Calendar\CustomCalendarView:
             tags: ['calendar.view']
     

2. Event Providers:

   • Implement BladeTester\CalendarBundle\Provider\EventProviderInterface for dynamic event sources (e.g., API calls):

     class ApiEventProvider implements EventProviderInterface {
         public function getEvents() { /* ... */ }
     }
     

   • Tag the service:

     tags: ['calendar.event_provider']
     

3. Configuration:

   • Override default settings in config/packages/calendar.yaml:

     calendar:
         default_view: 'week' # Override default view
         max_events_per_day: 10 # Limit events per day
     

Pro Tips

• Performance: Use EventProviderInterface to lazy-load events for large datasets.
• Testing: Mock CalendarManager in tests:

  $this->mockBuilder()
       ->disableOriginalConstructor()
       ->getMock()
       ->method('getEvents')
       ->willReturn([$mockEvent]);
  

• Legacy Systems: For Symfony 2, use the EventType form with Symfony\Component\Form\Extension\Core\Type\FormType for manual field mapping.