Added "Invokable Cases" PHPStan extension (#13)

* Added "Invokable Cases" PHPStan extension

This includes a PHPStan extension to add support for `InvokableCases`
so that static analysis tools can understand the callable methods and
their return types.

The extension has been added in a way that will allow multiple extensions
in the future if required, with a single include file that will import
all extensions, or the option to include only specific extensions.

* Added "Invokable Cases" PHPStan extension testing

tests/PHPStan/InvokableCases/InvokableCasesTestCase.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace ArchTech\Enums\Tests\PHPStan\InvokableCases;
+
+use PHPStan\Analyser\OutOfClassScope;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Testing\PHPStanTestCase;
+
+class InvokableCasesTestCase extends PHPStanTestCase
+{
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [__DIR__ . '/../../../src/PHPStan/InvokableCases/extension.neon'];
+    }
+
+    public function assertStaticallyCallable(string $enum, string $case, $exists = true, $static = true): void
+    {
+        $reflectionProvider = $this->createReflectionProvider();
+        $class = $reflectionProvider->getClass($enum);
+
+        if ($exists) {
+            $this->assertTrue($class->hasMethod($case), sprintf('%s on class %s does not exist', $case, $enum));
+            $method = $class->getMethod($case, new OutOfClassScope());
+            if ($static) {
+                $this->assertTrue($method->isStatic(), sprintf('%s on class %s is not static', $case, $enum));
+            } else {
+                $this->assertFalse($method->isStatic(), sprintf('%s on class %s is static', $case, $enum));
+            }
+        } else {
+            $this->assertFalse($class->hasMethod($case), sprintf('%s on class %s exists', $case, $enum));
+        }
+    }
+
+    public function assertStaticallyCallableType(string $enum, string $case, string $type): void
+    {
+        $reflectionProvider = $this->createReflectionProvider();
+        $class = $reflectionProvider->getClass($enum);
+
+        $method = $class->getMethod($case, new OutOfClassScope());
+        $methodVariant = ParametersAcceptorSelector::selectSingle($method->getVariants());
+        $methodReturnType = $methodVariant->getReturnType();
+        $this->assertInstanceOf($type, $methodReturnType);
+    }
+}

tests/PHPStan/InvokableCases/Role.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Tests\PHPStan\InvokableCases;
+
+use ArchTech\Enums\InvokableCases;
+
+enum Role
+{
+    use InvokableCases;
+
+    case admin;
+    case manager;
+    case staff;
+
+    public static function administrator(): self
+    {
+        return self::admin;
+    }
+
+    public function isManager(): bool
+    {
+        return $this === self::manager;
+    }
+}

tests/PHPStan/InvokableCases/Status.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Tests\PHPStan\InvokableCases;
+
+use ArchTech\Enums\InvokableCases;
+
+enum Status: int
+{
+    use InvokableCases;
+
+    case created = 0;
+    case running = 1;
+    case done = 2;
+
+    public static function initial(): self
+    {
+        return self::created;
+    }
+
+    public function isStarted(): bool
+    {
+        return $this->value > self::created->value;
+    }
+}

tests/PHPStan/InvokableCases/Suits.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\Tests\PHPStan\InvokableCases;
+
+use ArchTech\Enums\InvokableCases;
+
+enum Suits: string
+{
+    use InvokableCases;
+
+    case clubs = 'C';
+    case diamonds = 'D';
+    case hearts = 'H';
+    case spades = 'S';
+
+    public static function valuable(): self
+    {
+        return self::diamonds;
+    }
+
+    public function isRed(): bool
+    {
+        return match ($this) {
+            self::diamonds, self::hearts => true,
+            default => false,
+        };
+    }
+}