Holidays Laravel Package

## Getting Started
### Minimal Setup
1. **Installation**:
   ```bash
   composer require spatie/holidays

Requires PHP 8.4+.

2. First Use Case: Fetch all holidays for Belgium in 2024:

   use Spatie\Holidays\Holidays;
   
   $holidays = Holidays::for('be', year: 2024)->get();
   foreach ($holidays as $holiday) {
       echo $holiday->name . ' (' . $holiday->date->format('Y-m-d') . ')';
   }
   

   Outputs:

   Nieuwjaar (2024-01-01)
   Dodenherdenking (2024-05-27)
   ...
   

3. Key Classes:

   • Holidays: Facade for country-specific holiday queries.
   • Holiday: Represents a holiday with name, date, type, and region.
   • Country classes (e.g., Belgium, Germany, Ethiopia) for region-specific logic.

Where to Look First

• Country Support: Check supported countries (now includes Ethiopia).
• API Reference: Focus on Holidays::for() methods (get(), getInRange(), isHoliday(), etc.).
• Holiday Types: HolidayType enum (National, Regional, Religious, etc.).
• New Feature: Ethiopian holidays now support locale-specific names (e.g., Amharic).

Implementation Patterns

Core Workflows

1. Fetching Holidays

• All Holidays:

  $holidays = Holidays::for('us', year: 2024)->get();
  

• Range Query:

  $holidays = Holidays::for('ca', year: 2024)->getInRange('2024-07-01', '2024-08-31');
  

• Upcoming Holidays:

  $upcoming = Holidays::for('jp')->getUpcoming(5); // Next 5 holidays
  

2. Regional Holidays

// Ethiopia (now with locale support)
$holidays = Holidays::for('et', year: 2024, locale: 'am')->get(); // Amharic names

• Dynamic Region Handling:

  use Spatie\Holidays\Countries\Ethiopia;
  $ethiopia = Ethiopia::make();
  $holidays = Holidays::for($ethiopia, year: 2024, locale: 'en')->get(); // English names
  

3. Observed Holidays

• Automatically adjusts weekends (e.g., US holidays):

  Holidays::for('us')->isHoliday('2024-07-04'); // true (Independence Day)
  Holidays::for('us')->isHoliday('2024-07-06'); // true (Observed, falls on Saturday)
  

4. Long Weekends

$longWeekends = Holidays::for('au', year: 2024)->getLongWeekends(4); // Min 4 days
foreach ($longWeekends as $weekend) {
    echo $weekend->startDate->format('Y-m-d') . ' to ' .
         $weekend->endDate->format('Y-m-d');
}

5. Localization (Expanded)

// Ethiopia with Amharic locale
$holidays = Holidays::for('et', locale: 'am')->get();
foreach ($holidays as $holiday) {
    echo $holiday->name; // e.g., "የኢትዮጵያ አዲስ አዘያም" (Ethiopian New Year)
}

Integration Tips

Laravel-Specific Patterns

1. Service Provider Binding: Bind the Holidays facade in AppServiceProvider for global access:

   public function register()
   {
       $this->app->bind('holidays', function () {
           return new \Spatie\Holidays\Holidays();
       });
   }
   

2. Model Observers: Add holiday checks to models (e.g., Event):

   class EventObserver
   {
       public function saving(Event $event)
       {
           if ($event->is_workday && Holidays::for('et')->isHoliday($event->date)) {
               throw new \Exception('Cannot schedule events on Ethiopian holidays!');
           }
       }
   }
   

3. API Responses: Format holidays for JSON APIs (now with locale support):

   return response()->json([
       'holidays' => Holidays::for('et', year: 2024, locale: 'am')->get()->map(fn ($h) => [
           'name' => $h->name,
           'date' => $h->date->format('Y-m-d'),
           'type' => $h->type->value,
           'locale' => 'am', // Explicitly include locale
       ]),
   ]);
   

4. Caching: Cache holiday data for performance (e.g., 1 year):

   $holidays = Cache::remember("holidays.{$country}.{$year}.{$locale}", now()->addYear(), function () use ($country, $year, $locale) {
       return Holidays::for($country, year: $year, locale: $locale)->get();
   });
   

Common Use Cases

Gotchas and Tips

Pitfalls

1. Region-Specific Quirks:

   • Some countries (e.g., Germany) have state-level holidays. Always specify regions when needed:

     // ❌ Missing region (may return incomplete data)
     Holidays::for('de')->get();
     
     // ✅ Correct
     Holidays::for('de', region: 'DE-BW')->get();
     

2. Observed Holidays:

   • Not all countries observe holidays on weekends. Test edge cases:

     // US observes Memorial Day (May 27, 2024) on Monday if it falls on weekend
     Holidays::for('us')->isHoliday('2024-05-27'); // true (if weekend)
     

3. Year Range Limits:

   • Some countries (e.g., Islamic calendar) have predefined year ranges. Querying outside this range returns empty results:

     Holidays::for('sa', year: 2050)->get(); // [] (if 2050 is unsupported)
     

4. Locale Fallbacks:

   • Missing translations return original names. Verify locales (now includes Amharic for Ethiopia):

     Holidays::for('et', locale: 'es')->get(); // Spanish names (if available)
     Holidays::for('et', locale: 'am')->get(); // Amharic names (new in 2.1.0)
     

5. Carbon Dependencies:

   • The package uses CarbonImmutable. Ensure your project is compatible:

     composer require nesbot/carbon
     

Debugging Tips

1. Validate Country Codes:

   if (!Holidays::has('xx')) {
       throw new \InvalidArgumentException("Unsupported country: xx");
   }
   

2. Inspect Holiday Data:

   dd(Holidays::for('et', year: 2024, locale: 'am')->get()->first()->toArray());
   

3. Check for Regional Overrides:

   use Spatie\Holidays\Countries\Ethiopia;
   dd(Ethiopia::regions()); // [] (Ethiopia has no regional holidays)
   

Extension Points

1. Custom Holiday Logic: Extend the Country class for unsupported countries:

   class MyCountry extends \Spatie\Holidays\Countries\