Yasumi Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require azuyalabs/yasumi
   

   Add the service provider to config/app.php (if not auto-discovered):

   'providers' => [
       Yasumi\YasumiServiceProvider::class,
   ],
   

2. First Use Case: Basic Holiday Calculation

   use Yasumi\Yasumi;
   
   $holidays = Yasumi::create('US', 'en_US');
   $holidays->setDate(new DateTime('2023-12-25')); // Christmas
   $isHoliday = $holidays->isHoliday(); // true
   

3. Key Files to Explore

   • vendor/azuyalabs/yasumi/src/Yasumi.php (Core class)
   • vendor/azuyalabs/yasumi/src/Providers/YasumiServiceProvider.php (Service provider)
   • vendor/azuyalabs/yasumi/src/Exceptions/ (Error handling)

Implementation Patterns

Common Workflows

1. Country-Specific Holiday Lookups

// Initialize for a country (e.g., Japan)
$holidays = Yasumi::create('JP', 'ja_JP');

// Check if a date is a holiday
$isHoliday = $holidays->isHoliday(new DateTime('2023-01-01')); // New Year's Day

// Get all holidays for a year
$holidaysList = $holidays->holidays();

2. Custom Holiday Rules

// Add a custom holiday (e.g., company-specific)
$holidays->addHoliday('Company Anniversary', new DateTime('2023-05-15'));

// Remove a default holiday (e.g., override a national holiday)
$holidays->removeHoliday('US', 'Independence Day');

3. Integration with Laravel Scheduling

// Skip jobs on holidays (e.g., in a scheduled task)
if ($holidays->isHoliday()) {
    $this->skipIfHoliday();
}

4. Localization and Timezones

// Set timezone and locale
$holidays = Yasumi::create('DE', 'de_DE', 'Europe/Berlin');

5. Batch Processing Holidays

// Generate holidays for a range of years
$holidays->setDateRange(new DateTime('2023-01-01'), new DateTime('2024-12-31'));
$holidaysList = $holidays->holidays();

Integration Tips

Laravel Facade

Use the Yasumi facade for cleaner syntax:

use Yasumi\Facades\Yasumi as YasumiFacade;

$isHoliday = YasumiFacade::create('GB')->isHoliday();

Caching Holidays

Cache holiday lists to improve performance:

$cachedHolidays = Cache::remember('holidays_'.date('Y'), now()->addYear(), function () {
    return Yasumi::create('US')->holidays();
});

Dynamic Country Selection

Store country codes in a database and fetch dynamically:

$countryCode = $user->country_code;
$holidays = Yasumi::create($countryCode);

API Responses

Return formatted holiday data in API responses:

return response()->json([
    'holidays' => collect(Yasumi::create('CA')->holidays())
        ->map(fn ($holiday) => [
            'name' => $holiday->name,
            'date' => $holiday->date->format('Y-m-d'),
        ])
        ->values()
]);

Gotchas and Tips

Pitfalls

1. Date Handling Quirks

   • Yasumi uses DateTime objects, so ensure your input dates are timezone-aware.
   • Example of timezone mismatch:

     $holidays = Yasumi::create('US', 'en_US', 'America/New_York');
     $holidays->setDate(new DateTime('2023-11-23', new DateTimeZone('UTC'))); // May fail
     

     Fix: Use the same timezone as the Yasumi instance.

2. Holiday Overrides

   • Custom holidays added via addHoliday() are not persisted. Re-add them if the Yasumi instance is recreated.
   • Example:

     $holidays = Yasumi::create('US');
     $holidays->addHoliday('Custom Day', new DateTime('2023-10-10'));
     
     // Later...
     $holidays = Yasumi::create('US'); // Custom holiday is lost!
     

     Fix: Store custom holidays in a database or config file.

3. Locale-Specific Names

   • Holiday names are locale-dependent. Switching locales mid-use may yield unexpected results.
   • Example:

     $holidays = Yasumi::create('FR', 'fr_FR');
     $holiday = $holidays->getHoliday(new DateTime('2023-07-14')); // "Fête Nationale"
     $holidays->setLocale('en_US');
     $holiday->name; // Still "Fête Nationale" (not updated dynamically)
     

     Fix: Re-fetch holidays after changing the locale.

4. Performance with Large Date Ranges

   • Calculating holidays for wide date ranges (e.g., 100 years) can be slow.
   • Fix: Limit the range or cache results.

5. Static Method Caching

   • Yasumi caches static method calls (e.g., Yasumi::create()). Reusing the same country/locale may return cached data.
   • Fix: Use unique instances for different contexts:

     $holidays1 = Yasumi::create('US');
     $holidays2 = Yasumi::create('US'); // May return cached data
     

Debugging Tips

1. Check Holiday Existence Use hasHoliday() to verify if a holiday exists before checking:

   if ($holidays->hasHoliday(new DateTime('2023-12-25'))) {
       $holiday = $holidays->getHoliday(new DateTime('2023-12-25'));
   }
   

2. Inspect Holiday Data Dump holiday objects to debug:

   dd($holidays->holidays()); // View all holidays
   dd($holidays->getHoliday(new DateTime('2023-01-01'))->toArray());
   

3. Enable Yasumi Logging Add debug logging for holiday calculations:

   Yasumi::setLogger(function ($message) {
       \Log::debug($message);
   });
   

4. Validate Country Codes Ensure country codes are correct (e.g., 'US' vs 'USA'). Use Yasumi::supportedCountries() to list valid codes.

Extension Points

1. Custom Holiday Providers Extend Yasumi by creating custom holiday providers:

   use Yasumi\Holiday\HolidayProviderInterface;
   
   class CompanyHolidayProvider implements HolidayProviderInterface
   {
       public function getHolidays(Yasumi $yasumi)
       {
           return [
               new Holiday('Team Building Day', new DateTime('2023-09-15')),
           ];
       }
   }
   
   // Register the provider
   Yasumi::addHolidayProvider(new CompanyHolidayProvider());
   

2. Override Default Holidays Replace default holidays for a country:

   Yasumi::overrideHolidays('US', [
       new Holiday('Custom Thanksgiving', new DateTime('2023-11-23')),
   ]);
   

3. Add Custom Holiday Types Extend the Holiday class or create a decorator:

   class ExtendedHoliday extends Holiday
   {
       public function isCompanyHoliday()
       {
           return in_array($this->name, ['Company Anniversary', 'Team Day']);
       }
   }
   
   // Use in custom logic
   $holiday = $holidays->getHoliday(new DateTime('2023-05-15'));
   if ($holiday instanceof ExtendedHoliday && $holiday->isCompanyHoliday()) {
       // Handle company-specific logic
   }
   

4. Integrate with Laravel Events Trigger events when holidays are detected:

   event(new HolidayDetected($holiday));
   

5. Localization Hooks Override holiday names or descriptions dynamically:

   Yasumi::setHolidayNameOverride('US',