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

README.md

@@ -366,6 +366,15 @@ enum TaskStatus: int
 
 And if you're using the same meta property in multiple enums, you can create a dedicated trait that includes this `@method` annotation.
 
+## PHPStan
+
+To assist PHPStan when using invokable cases, you can include the PHPStan extensions into your own `phpstan.neon` file:
+
+```yaml
+includes:
+  - ./vendor/archtechx/enums/extension.neon
+```
+
 ## Development
 
 Run all checks locally:

extension.neon

@@ -0,0 +1,2 @@
+includes:
+  - ./src/PHPStan/InvokableCases/extension.neon

phpstan.neon

@@ -1,5 +1,6 @@
 includes:
     - ./vendor/nunomaduro/larastan/extension.neon
+    - ./extension.neon
 
 parameters:
     paths:

src/PHPStan/InvokableCases/ReflectionExtension.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\PHPStan\InvokableCases;
+
+use ArchTech\Enums\InvokableCases;
+use PHPStan\BetterReflection\Reflection\Adapter\ReflectionEnum;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\MethodsClassReflectionExtension;
+
+class ReflectionExtension implements MethodsClassReflectionExtension
+{
+    public function hasMethod(ClassReflection $classReflection, string $methodName): bool
+    {
+        if (
+            $classReflection->getNativeReflection() instanceof ReflectionEnum
+            && $classReflection->hasTraitUse(InvokableCases::class)
+        ) {
+            return $classReflection->getNativeReflection()->hasCase($methodName);
+        }
+
+        return false;
+    }
+
+    public function getMethod(ClassReflection $classReflection, string $methodName): MethodReflection
+    {
+        return new StaticInvokableCaseMethodReflection($classReflection, $methodName);
+    }
+}

src/PHPStan/InvokableCases/StaticInvokableCaseMethodReflection.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArchTech\Enums\PHPStan\InvokableCases;
+
+use PHPStan\Analyser\OutOfClassScope;
+use PHPStan\Reflection\ClassMemberReflection;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\FunctionVariant;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParametersAcceptor;
+use PHPStan\TrinaryLogic;
+use PHPStan\Type\Generic\TemplateTypeMap;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+
+class StaticInvokableCaseMethodReflection implements MethodReflection
+{
+    private readonly MethodReflection $callStaticMethod;
+
+    public function __construct(
+        private readonly ClassReflection $classReflection,
+        private readonly string $name,
+    ) {
+        $this->callStaticMethod = $this->classReflection->getMethod('__callStatic', new OutOfClassScope());
+    }
+
+    public function getDeclaringClass(): ClassReflection
+    {
+        return $this->classReflection;
+    }
+
+    public function isStatic(): bool
+    {
+        return true;
+    }
+
+    public function isPrivate(): bool
+    {
+        return false;
+    }
+
+    public function isPublic(): bool
+    {
+        return true;
+    }
+
+    public function getDocComment(): ?string
+    {
+        return $this->callStaticMethod->getDocComment();
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getPrototype(): ClassMemberReflection
+    {
+        return $this;
+    }
+
+    /**
+     * @return ParametersAcceptor[]
+     */
+    public function getVariants(): array
+    {
+        return [
+            new FunctionVariant(
+                TemplateTypeMap::createEmpty(),
+                TemplateTypeMap::createEmpty(),
+                [],
+                false,
+                $this->classReflection->getBackedEnumType() ?? new StringType()
+            ),
+        ];
+    }
+
+    public function isDeprecated(): TrinaryLogic
+    {
+        return $this->callStaticMethod->isDeprecated();
+    }
+
+    public function getDeprecatedDescription(): ?string
+    {
+        return $this->callStaticMethod->getDeprecatedDescription();
+    }
+
+    public function isFinal(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+
+    public function isInternal(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+
+    public function getThrowType(): ?Type
+    {
+        return $this->callStaticMethod->getThrowType();
+    }
+
+    public function hasSideEffects(): TrinaryLogic
+    {
+        return TrinaryLogic::createNo();
+    }
+}

src/PHPStan/InvokableCases/extension.neon

@@ -0,0 +1,5 @@
+services:
+  -
+    class: ArchTech\Enums\PHPStan\InvokableCases\ReflectionExtension
+    tags:
+      - phpstan.broker.methodsClassReflectionExtension

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