V2: Improve Islamic calendar contracts

UPGRADING.md

@@ -101,3 +101,4 @@ These are internal changes that don't require any action on your part.
 - **`HasRegions` interface** standardizes how countries declare and validate regional holiday support.
 - **`Holiday` value object and `HolidayType` enum** provide structured, JSON-serializable return data instead of plain arrays.
 - **`region` parameter on `Holidays::for()`** allows passing a region code directly without constructing a country instance.
+- **Islamic calendar methods are stricter** — `arafat()`, `islamicNewYear()`, and `prophetMuhammadBirthday()` now throw `InvalidYear` instead of returning `null` when a year is not found in the lookup table.

phpstan.neon.dist

@@ -1,8 +1,5 @@
-includes:
-    - phpstan-baseline.neon
-
 parameters:
-	level: 8
+	level: max
 	paths:
 		- src
 	ignoreErrors:

src/Calendars/IslamicCalendar.php

@@ -17,37 +17,67 @@ trait IslamicCalendar
 
     protected string $islamicCalendarTimezone = 'UTC';
 
+    /** @return array<int, string|array<string>> */
+    abstract protected function eidAlFitrDates(): array;
+
+    /** @return array<int, string|array<string>> */
+    abstract protected function eidAlAdhaDates(): array;
+
+    /** @return array<int, string> */
+    protected function ashuraDates(): array
+    {
+        return [];
+    }
+
+    /** @return array<int, string> */
+    protected function arafatDates(): array
+    {
+        return [];
+    }
+
+    /** @return array<int, string> */
+    protected function islamicNewYearDates(): array
+    {
+        return [];
+    }
+
+    /** @return array<int, string> */
+    protected function prophetMuhammadBirthdayDates(): array
+    {
+        return [];
+    }
+
     /** @return array<CarbonPeriod> */
     public function eidAlFitr(int $year, int $totalDays = 3): array
     {
-        return $this->getMultiDayHoliday(self::eidAlFitr, $year, $totalDays);
+        return $this->getMultiDayHoliday($this->eidAlFitrDates(), $year, $totalDays);
     }
 
     /** @return array<CarbonPeriod> */
     public function eidAlAdha(int $year, int $totalDays = 4): array
     {
-        return $this->getMultiDayHoliday(self::eidAlAdha, $year, $totalDays);
+        return $this->getMultiDayHoliday($this->eidAlAdhaDates(), $year, $totalDays);
     }
 
     /** @return array<CarbonPeriod> */
     protected function ashura(int $year, int $totalDays = 2): array
     {
-        return $this->getMultiDayHoliday(self::ashura, $year, $totalDays);
+        return $this->getMultiDayHoliday($this->ashuraDates(), $year, $totalDays);
     }
 
     protected function arafat(int $year): CarbonImmutable
     {
-        return $this->getSingleDayHoliday(self::arafat, $year);
+        return $this->getSingleDayHoliday($this->arafatDates(), $year);
     }
 
     protected function islamicNewYear(int $year): CarbonImmutable
     {
-        return $this->getSingleDayHoliday(self::islamicNewYear, $year);
+        return $this->getSingleDayHoliday($this->islamicNewYearDates(), $year);
     }
 
     protected function prophetMuhammadBirthday(int $year): CarbonImmutable
     {
-        return $this->getSingleDayHoliday(self::prophetMuhammadBirthday, $year);
+        return $this->getSingleDayHoliday($this->prophetMuhammadBirthdayDates(), $year);
     }
 
     public function setIslamicCalendarTimezone(string $islamicCalendarTimezone): static

src/Calendars/ResolvesCalendarDates.php

@@ -38,7 +38,7 @@ protected function getMultiDayHoliday(array $collection, int $year, int $totalDa
         $date = $collection[$year] ?? null;
 
         if ($date === null) {
-            $this->throwUnsupportedYear($collection);
+            return [];
         }
 
         $overlap = $this->getOverlapping($collection, $year, $totalDays);
@@ -109,11 +109,13 @@ protected function getOverlapping(array $collection, int $year, int $totalDays):
         return ($end?->year !== $year) ? (string) $date : null;
     }
 
-    /** @param non-empty-array<int, mixed> $collection */
+    /** @param array<int, mixed> $collection */
     private function throwUnsupportedYear(array $collection): never
     {
         $keys = array_keys($collection);
+        $min = $keys ? min($keys) : 0;
+        $max = $keys ? max($keys) : 0;
 
-        throw InvalidYear::range($this->countryCode(), min($keys), max($keys));
+        throw InvalidYear::range($this->countryCode(), $min, $max);
     }
 }