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.

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

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