Refactor color loading and type annotations in color classes

composer.json

@@ -21,8 +21,8 @@
         "php": ">=8.3"
     },
     "require-dev": {
-        "phpunit/phpunit": "^11.0",
-        "symfony/var-dumper": "^7.0"
+        "phpunit/phpunit": "^12.5",
+        "symfony/var-dumper": "^7.0 || ^8.0"
     },
     "replace": {
         "phpcolor/apple-colors": "self.version",

src/Apple/AppleColors.php

@@ -19,7 +19,7 @@
 final class AppleColors extends \stdClass implements \IteratorAggregate, \Countable
 {
     /**
-     * @var array<string, array<string, string>>
+     * @var array<string, mixed>
      */
     private static array $files = [];
 
@@ -63,13 +63,31 @@ private static function create(string $file, ?string $theme = null): self
             throw new \InvalidArgumentException(sprintf('The theme "%s" does not exist.', $theme));
         }
 
-        $file = self::$files[$file] ??= require __DIR__.'/Resources/colors/'.$file.'.php';
+        if (!isset(self::$files[$file])) {
+            self::$files[$file] = require __DIR__.'/Resources/colors/'.$file.'.php';
+        }
+
+        $fileData = self::$files[$file];
+
+        if ($theme) {
+            if (!is_array($fileData) || !isset($fileData[$theme])) {
+                throw new \RuntimeException(sprintf('Theme "%s" not found in file "%s".', $theme, $file));
+            }
+            /** @var array<string, array{string, int[]}> */
+            $colors = $fileData[$theme];
+        } else {
+            if (!is_array($fileData)) {
+                throw new \RuntimeException(sprintf('Invalid data structure in file "%s".', $file));
+            }
+            /** @var array<string, array{string, int[]}> */
+            $colors = $fileData;
+        }
 
-        return new self($theme ? $file[$theme] : $file);
+        return new self($colors);
     }
 
     /**
-     * @param array<string, array{string, string[]}> $colors
+     * @param array<string, array{string, int[]}> $colors
      */
     private function __construct(private readonly array $colors)
     {

src/Bootstrap/BootstrapColors.php

@@ -32,7 +32,10 @@ final class BootstrapColors extends \stdClass implements \IteratorAggregate, \Co
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array<int, string>> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**
@@ -77,9 +80,15 @@ public function has(string $name): bool
         return \in_array($name, $this->getNames(), true);
     }
 
+    /**
+     * @return int<0, max>
+     */
     public function count(): int
     {
-        return count($this->colors, COUNT_RECURSIVE) - count($this->colors);
+        $total = count($this->colors, COUNT_RECURSIVE) - count($this->colors);
+        assert($total >= 0);
+
+        return $total;
     }
 
     /**
@@ -103,7 +112,13 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = 500;
+        if (isset($arguments[0])) {
+            assert(\is_int($arguments[0]));
+            $shade = $arguments[0];
+        }
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string

src/Dracula/DraculaColors.php

@@ -20,7 +20,10 @@ final class DraculaColors extends \stdClass implements \IteratorAggregate, \Coun
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array{string, int[]}> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**

src/Material/MaterialColors.php

@@ -40,7 +40,10 @@ final class MaterialColors extends \stdClass implements \IteratorAggregate, \Cou
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array<int|string, string>> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**
@@ -111,7 +114,9 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer or string, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = isset($arguments[0]) ? (\is_int($arguments[0]) || \is_string($arguments[0]) ? $arguments[0] : 500) : 500;
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string

src/Nord/NordColors.php

@@ -20,7 +20,10 @@ final class NordColors extends \stdClass implements \IteratorAggregate, \Countab
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array{string, int[]}> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**

src/OpenColor/OpenColorColors.php

@@ -34,7 +34,10 @@ final class OpenColorColors extends \stdClass implements \IteratorAggregate, \Co
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array<int, string>|string> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**
@@ -114,7 +117,13 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = 5;
+        if (isset($arguments[0])) {
+            assert(\is_int($arguments[0]));
+            $shade = $arguments[0];
+        }
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string

src/Pico/PicoColors.php

@@ -41,7 +41,10 @@ final class PicoColors extends \stdClass implements \IteratorAggregate, \Countab
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array<int, string>> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**
@@ -86,9 +89,15 @@ public function has(string $name): bool
         return \in_array($name, $this->getNames(), true);
     }
 
+    /**
+     * @return int<0, max>
+     */
     public function count(): int
     {
-        return count($this->colors, COUNT_RECURSIVE) - count($this->colors);
+        $total = count($this->colors, COUNT_RECURSIVE) - count($this->colors);
+        assert($total >= 0);
+
+        return $total;
     }
 
     /**
@@ -112,7 +121,13 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = 500;
+        if (isset($arguments[0])) {
+            assert(\is_int($arguments[0]));
+            $shade = $arguments[0];
+        }
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string

src/Primer/PrimerColors.php

@@ -41,7 +41,10 @@ public static function colors(string $theme = 'light'): self
             throw new \InvalidArgumentException(sprintf('The theme "%s" does not exist.', $theme));
         }
 
-        return new self(require __DIR__.'/Resources/'.$theme.'.php');
+        /** @var array<string, array<int, string>> $colors */
+        $colors = require __DIR__.'/Resources/'.$theme.'.php';
+
+        return new self($colors);
     }
 
     /**
@@ -112,7 +115,13 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = 5;
+        if (isset($arguments[0])) {
+            assert(\is_int($arguments[0]));
+            $shade = $arguments[0];
+        }
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string

src/Tailwind/TailwindColors.php

@@ -32,7 +32,10 @@ final class TailwindColors extends \stdClass implements \IteratorAggregate, \Cou
 {
     public static function colors(): self
     {
-        return new self(require __DIR__.'/Resources/colors.php');
+        /** @var array<string, array<int, string>> $colors */
+        $colors = require __DIR__.'/Resources/colors.php';
+
+        return new self($colors);
     }
 
     /**
@@ -103,7 +106,13 @@ public function __call(string $name, array $arguments): mixed
             throw new \InvalidArgumentException(sprintf('The first argument of "%s" must be an integer, "%s" given.', $name, get_debug_type($arguments[0])));
         }
 
-        return $this->get($name, ...$arguments);
+        $shade = 500;
+        if (isset($arguments[0])) {
+            assert(\is_int($arguments[0]));
+            $shade = $arguments[0];
+        }
+
+        return $this->get($name, $shade);
     }
 
     public function __get(string $name): string