Calendar Holidays Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require aiskander/calendar-holidays-bundle
   

   Ensure your composer.json aligns with the package's PHP/Symfony version constraints (e.g., Symfony 3.4/4.0, PHP 7.0+).

2. Register the Bundle

   • Symfony 2.8–3.x: Add to AppKernel.php:

     new \Aiskander\CalendarHolidaysBundle\AiskanderCalendarHolidaysBundle(),
     

   • Symfony 4.x: Add to config/bundles.php:

     \Aiskander\CalendarHolidaysBundle\AiskanderCalendarHolidaysBundle::class => ['all' => true],
     

3. Import Routes Add to config/routes.yaml:

   aiskander_calendar_holidays:
       resource: "@AiskanderCalendarHolidaysBundle/Resources/config/routing.yml"
   

4. First Use Case: Check a Holiday Inject the service into a controller or service:

   use Aiskander\CalendarHolidaysBundle\Service\HolidayService;
   
   class MyController extends AbstractController {
       public function checkHoliday(HolidayService $holidayService) {
           $isHoliday = $holidayService->isHoliday(new \DateTime('2023-12-25'));
           return new Response($isHoliday ? 'Holiday!' : 'Workday');
       }
   }
   

Implementation Patterns

Core Workflows

1. Holiday Validation Use HolidayService to check dates:

   $holidayService->isHoliday(\DateTime::createFromFormat('Y-m-d', '2023-01-01')); // New Year's Day
   

2. Fetching Holidays for a Year Retrieve all holidays for a specific year (e.g., Egypt-specific):

   $holidays = $holidayService->getHolidays(2023);
   // Returns array of \DateTime objects or holiday entities.
   

3. Custom Holiday Regions The bundle appears Egypt-focused (per composer.json keywords). Extend for other regions by:

   • Overriding the default HolidayProvider service.
   • Implementing a custom provider (see Extension Points).

4. Doctrine Integration Holidays are stored in Doctrine entities (per doctrine/orm dependency). Query via repository:

   $holidayRepo = $this->getDoctrine()->getRepository(Holiday::class);
   $holidays = $holidayRepo->findByYear(2023);
   

Integration Tips

• Twig Integration: Pass the service to templates for dynamic UI:

  {% if app.service('aiskander_calendar_holidays.holiday_service').isHoliday(date) %}
      <p>Holiday: {{ date|date('l, F j') }}</p>
  {% endif %}
  

• Command-Line Tools: Use the HolidayCommand (if exposed) to bulk-add holidays:

  php bin/console aiskander:holidays:add 2023-01-01 "New Year's Day"
  

• Event Listeners: Trigger actions on holidays (e.g., send notifications):

  // config/services.yaml
  App\EventListener\HolidayListener:
      tags:
          - { name: kernel.event_listener, event: aiskander.holiday, method: onHoliday }
  

Gotchas and Tips

Pitfalls

1. Incomplete Documentation

   • The bundle is not production-ready (README states "under active development").
   • Assume missing features (e.g., no clear API for custom holiday regions).
   • Workaround: Inspect src/Service/HolidayService.php and src/Entity/Holiday.php for undocumented methods.

2. Doctrine Dependency

   • Holidays are stored in a Doctrine entity (Holiday). If you’re not using Doctrine, this bundle is incompatible.
   • Alternative: Fork the bundle and replace Doctrine logic with a flat file or database of your choice.

3. Region-Specific Data

   • The bundle defaults to Egypt holidays (per composer.json keywords). Overriding this requires custom logic (see Extension Points).

4. Routing Conflicts

   • The bundle registers routes (routing.yml). Ensure they don’t clash with your existing routes:

     # config/routes.yaml
     aiskander_calendar_holidays:
         resource: "@AiskanderCalendarHolidaysBundle/Resources/config/routing.yml"
         prefix: /api/holidays  # Avoid conflicts
     

Debugging

• Check Service Availability:

  php bin/console debug:container | grep aiskander
  

  Verify aiskander_calendar_holidays.holiday_service is registered.

• Database Issues: If holidays aren’t loading, check:

  • Doctrine migrations (php bin/console doctrine:migrations:status).
  • Entity mappings (src/Entity/Holiday.php).

• Date Handling: The bundle likely uses DateTime objects. Ensure your input dates match:

  $holidayService->isHoliday(new \DateTime('2023-12-25')); // Correct
  $holidayService->isHoliday('2023-12-25'); // May fail (type mismatch)
  

Extension Points

1. Custom Holiday Provider Override the default provider in config/services.yaml:

   services:
       aiskander_calendar_holidays.holiday_provider:
           class: App\Service\CustomHolidayProvider
           arguments:
               - '@doctrine.orm.entity_manager'
   

   Implement Aiskander\CalendarHolidaysBundle\Provider\HolidayProviderInterface.

2. Adding New Holiday Types Extend the Holiday entity (e.g., add isPublicHoliday field):

   // src/Entity/Holiday.php
   class Holiday {
       // ...
       private bool $isPublic = false;
       // Add getter/setter and update migrations.
   }
   

3. Localization The bundle lacks i18n support. Add translations manually:

   # config/packages/translation.yaml
   imports:
       - { resource: '%kernel.project_dir%/config/holidays/translations.yaml' }
   

Configuration Quirks

• No config/packages/ Setup: The bundle doesn’t include a default config/packages/aiskander_calendar_holidays.yaml. Create one if you need customization:

  # config/packages/aiskander_calendar_holidays.yaml
  aiskander_calendar_holidays:
      default_region: 'eg'  # Hypothetical config key (check source)
  

• Environment-Specific Holidays: Load holidays dynamically based on environment (e.g., APP_ENV):

  // src/Service/CustomHolidayProvider.php
  public function getHolidays(int $year): array {
      if ($_ENV['APP_ENV'] === 'prod') {
          return $this->fetchFromDatabase($year);
      }
      return $this->fetchFromTestData($year);
  }