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,
+        };
+    }
+}

tests/PHPStan/InvokableCasesTest.php

@@ -0,0 +1,99 @@
+<?php
+
+use ArchTech\Enums\Tests\PHPStan\InvokableCases\InvokableCasesTestCase;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\StringType;
+
+uses(InvokableCasesTestCase::class);
+
+it('correctly identifies allowable static method calls for invokable pure enum', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Role::class;
+
+    // Base enum
+    $this->assertStaticallyCallable($class, 'cases');
+    $this->assertStaticallyCallable($class, 'from', false);
+    $this->assertStaticallyCallable($class, 'tryFrom', false);
+
+    // Defined methods
+    $this->assertStaticallyCallable($class, 'administrator');
+    $this->assertStaticallyCallable($class, 'isManager', true, false);
+
+    // Cases
+    $this->assertStaticallyCallable($class, 'admin');
+    $this->assertStaticallyCallable($class, 'manager');
+    $this->assertStaticallyCallable($class, 'staff');
+
+    // Missing Case
+    $this->assertStaticallyCallable($class, 'customer', false);
+});
+
+it('correctly identifies allowable static method calls for invokable int backed enum', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Status::class;
+
+    // Base enum
+    $this->assertStaticallyCallable($class, 'cases');
+    $this->assertStaticallyCallable($class, 'from');
+    $this->assertStaticallyCallable($class, 'tryFrom');
+
+    // Defined methods
+    $this->assertStaticallyCallable($class, 'initial');
+    $this->assertStaticallyCallable($class, 'isStarted', true, false);
+
+    // Cases
+    $this->assertStaticallyCallable($class, 'created');
+    $this->assertStaticallyCallable($class, 'running');
+    $this->assertStaticallyCallable($class, 'done');
+
+    // Missing Case
+    $this->assertStaticallyCallable($class, 'failed', false);
+});
+
+it('correctly identifies allowable static method calls for invokable string backed enum', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Suits::class;
+
+    // Base enum
+    $this->assertStaticallyCallable($class, 'cases');
+    $this->assertStaticallyCallable($class, 'from');
+    $this->assertStaticallyCallable($class, 'tryFrom');
+
+    // Defined methods
+    $this->assertStaticallyCallable($class, 'valuable');
+    $this->assertStaticallyCallable($class, 'isRed', true, false);
+
+    // Cases
+    $this->assertStaticallyCallable($class, 'clubs');
+    $this->assertStaticallyCallable($class, 'diamonds');
+    $this->assertStaticallyCallable($class, 'hearts');
+    $this->assertStaticallyCallable($class, 'spades');
+
+    // Missing Case
+    $this->assertStaticallyCallable($class, 'joker', false);
+});
+
+it('correctly identifies types for invoked pure enum cases', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Role::class;
+
+    // Cases
+    $this->assertStaticallyCallableType($class, 'admin', StringType::class);
+    $this->assertStaticallyCallableType($class, 'manager', StringType::class);
+    $this->assertStaticallyCallableType($class, 'staff', StringType::class);
+});
+
+it('correctly identifies types for invoked int backed enum cases', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Status::class;
+
+    // Cases
+    $this->assertStaticallyCallableType($class, 'created', IntegerType::class);
+    $this->assertStaticallyCallableType($class, 'running', IntegerType::class);
+    $this->assertStaticallyCallableType($class, 'done', IntegerType::class);
+});
+
+it('correctly identifies types for invoked string backed enum cases', function () {
+    $class = \ArchTech\Enums\Tests\PHPStan\InvokableCases\Suits::class;
+
+    // Cases
+    $this->assertStaticallyCallableType($class, 'clubs', StringType::class);
+    $this->assertStaticallyCallableType($class, 'diamonds', StringType::class);
+    $this->assertStaticallyCallableType($class, 'hearts', StringType::class);
+    $this->assertStaticallyCallableType($class, 'spades', StringType::class);
+});