perf: fix needless sorting on every holiday insert

Sorting after each insertion results in O(n² log n) complexity when
adding n holidays. For a provider with 20 holidays, this means
sorting 20 times instead of once. Using deferred sorting avoids this
issue which could result in 10-20x faster initialization for
providers with many holidays.

Signed-off-by: Sacha Telgenhof <me@sachatelgenhof.com>

Author: stelgenhof

src/Yasumi/Provider/AbstractProvider.php

@@ -86,6 +86,11 @@ abstract class AbstractProvider implements \Countable, ProviderInterface, \Itera
      */
     private array $holidays = [];
 
+    /**
+     * flag to track if holidays need to be sorted
+     */
+    private bool $needSorting = false;
+
     /**
      * Creates a new holiday provider (i.e. country/state).
      *
@@ -114,7 +119,7 @@ public function addHoliday(Holiday $holiday): void
         }
 
         $this->holidays[$holiday->getKey()] = $holiday;
-        uasort($this->holidays, static fn (\DateTimeInterface $dateA, \DateTimeInterface $dateB): int => self::compareDates($dateA, $dateB));
+        $this->needSorting = true;
     }
 
     public function removeHoliday(string $key): void
@@ -182,6 +187,8 @@ public function count(): int
 
     public function getHolidays(): array
     {
+        $this->ensureSorted();
+
         return $this->holidays;
     }
 
@@ -228,7 +235,9 @@ public function between(
 
     public function getIterator(): \ArrayIterator
     {
-        return new \ArrayIterator($this->getHolidays());
+        $this->ensureSorted();
+
+        return new \ArrayIterator($this->holidays);
     }
 
     public function on(\DateTimeInterface $date): OnFilter
@@ -238,6 +247,8 @@ public function on(\DateTimeInterface $date): OnFilter
 
     public function getHolidayDates(): array
     {
+        $this->ensureSorted();
+
         return array_map(static fn ($holiday): string => (string) $holiday, $this->holidays);
     }
 
@@ -264,6 +275,18 @@ protected function isHolidayNameNotEmpty(string $key): bool
     private function clearHolidays(): void
     {
         $this->holidays = [];
+        $this->needSorting = false;
+    }
+
+    /**
+     * Ensures holidays are sorted chronologically if needed.
+     */
+    private function ensureSorted(): void
+    {
+        if ($this->needSorting) {
+            uasort($this->holidays, static fn (\DateTimeInterface $dateA, \DateTimeInterface $dateB): int => self::compareDates($dateA, $dateB));
+            $this->needSorting = false;
+        }
     }
 
     /**