Native enum support (#409)

* Implement native enum type + mapper

* Ignore test output in directory 'build/'

* Run tests on PHP 8.1

* Test native enum support if available
- PHP >= 8.1
- interface_exists(UnitEnum)

* Disable static code analysis on 8.1-specific code files

* [wip] Use default Type annotation for enums instead of EnumType

* Added symfony/var-dumper so we can actually debug

* Excluded a bad rule for 8.1 code style

* CS fixes

* Additional comments

* Ignore Enum type mapping outside root

* Define UnitEnum namespace

* Moved logic into more optimal location

* Removed unused use statement

* Support v5 of var-dumper for < PHP8

* Remove root namespace for `UnitEnum` interface check

* Ignore PHPStan check for isEnum

* Added root namespce back for UnitEnum

* Deprecated EnumType annotation and updated docs

* CS fixes

* Fixed failing test

* Fixed bug causing useEnumValues to not never be assigned

* Improved documentation around the class attribute for @type

Co-authored-by: Jacob Thomason <jacob@thomason.xxx>

Author: dsavina

.github/workflows/continuous_integration.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         install-args: ['', '--prefer-lowest']
-        php-version: ['7.4', '8.0']
+        php-version: ['7.4', '8.0', '8.1']
       fail-fast: false
 
     steps:

.gitignore

@@ -1,3 +1,4 @@
+/build/
 /vendor/
 /composer.lock
 /src/Tests/

composer.json

@@ -40,7 +40,8 @@
         "phpstan/extension-installer": "^1.1",
         "phpstan/phpstan": "^1.0",
         "phpstan/phpstan-webmozart-assert": "^1.0",
-        "phpunit/phpunit": "^8.5.19||^9.5.8",
+        "phpunit/phpunit": "^8.5.19 || ^9.5.8",
+        "symfony/var-dumper": "^5.4 || ^6.0",
         "thecodingmachine/phpstan-strict-rules": "^1.0"
     },
     "suggest": {

phpcs.xml.dist

@@ -28,6 +28,7 @@
         <exclude name="SlevomatCodingStandard.ControlStructures.RequireNullCoalesceEqualOperator"/>
         <exclude name="Squiz.Commenting.FunctionComment.InvalidNoReturn" />
         <exclude name="Generic.Formatting.MultipleStatementAlignment" />
+        <exclude name="Squiz.Functions.MultiLineFunctionDeclaration.NewlineBeforeOpenBrace" />
     </rule>
 
     <!-- Do not align assignments -->

phpstan.neon

@@ -4,6 +4,10 @@ parameters:
     tmpDir: .phpstan-cache
     paths:
         - src
+    excludePaths:
+         # TODO: exlude only for PHP < 8.1
+        - src/Mappers/Root/EnumTypeMapper.php
+        - src/Types/EnumType.php
     level: 8
     checkGenericClassInNonGenericObjectType: false
     reportUnmatchedIgnoredErrors: false

src/AnnotationReader.php

@@ -7,7 +7,6 @@
 use Doctrine\Common\Annotations\AnnotationException;
 use Doctrine\Common\Annotations\Reader;
 use InvalidArgumentException;
-use MyCLabs\Enum\Enum;
 use ReflectionClass;
 use ReflectionMethod;
 use ReflectionParameter;
@@ -568,9 +567,6 @@ static function ($attribute) {
         return $toAddAnnotations;
     }
 
-    /**
-     * @param ReflectionClass<Enum> $refClass
-     */
     public function getEnumTypeAnnotation(ReflectionClass $refClass): ?EnumType
     {
         return $this->getClassAnnotation($refClass, EnumType::class);

src/Annotations/EnumType.php

@@ -9,6 +9,8 @@
 /**
  * The EnumType annotation is useful to change the name of the generated "enum" type.
  *
+ * @deprecated Use @Type on a native PHP 8.1 Enum instead. Support will be removed in future release.
+ *
  * @Annotation
  * @Target({"CLASS"})
  * @Attributes({
@@ -21,12 +23,16 @@ class EnumType
     /** @var string|null */
     private $name;
 
+    /** @var bool */
+    private $useValues;
+
     /**
      * @param mixed[] $attributes
      */
-    public function __construct(array $attributes = [], ?string $name = null)
+    public function __construct(array $attributes = [], ?string $name = null, ?bool $useValues = null)
     {
         $this->name = $name ?? $attributes['name'] ?? null;
+        $this->useValues = $useValues ?? $attributes['useValues'] ?? false;
     }
 
     /**
@@ -36,4 +42,12 @@ public function getName(): ?string
     {
         return $this->name;
     }
+
+    /**
+     * Returns true if the enum type should expose backed values instead of case names.
+     */
+    public function useValues(): bool
+    {
+        return $this->useValues;
+    }
 }

src/Annotations/Type.php

@@ -45,12 +45,21 @@ class Type
      */
     private $selfType = false;
 
+    /** @var bool */
+    private $useEnumValues = false;
+
     /**
      * @param mixed[] $attributes
      * @param class-string<object>|null $class
      */
-    public function __construct(array $attributes = [], ?string $class = null, ?string $name = null, ?bool $default = null, ?bool $external = null)
-    {
+    public function __construct(
+        array $attributes = [],
+        ?string $class = null,
+        ?string $name = null,
+        ?bool $default = null,
+        ?bool $external = null,
+        ?bool $useEnumValues = null
+    ) {
         $external = $external ?? $attributes['external'] ?? null;
         $class = $class ?? $attributes['class'] ?? null;
         if ($class !== null) {
@@ -63,6 +72,7 @@ public function __construct(array $attributes = [], ?string $class = null, ?stri
 
         // If no value is passed for default, "default" = true
         $this->default = $default ?? $attributes['default'] ?? true;
+        $this->useEnumValues = $useEnumValues ?? $attributes['useEnumValues'] ?? false;
 
         if ($external === null) {
             return;
@@ -123,4 +133,12 @@ public function isDefault(): bool
     {
         return $this->default;
     }
+
+    /**
+     * Returns true if this enum type
+     */
+    public function useEnumValues(): bool
+    {
+        return $this->useEnumValues;
+    }
 }

src/Mappers/CompositeTypeMapper.php

@@ -65,6 +65,7 @@ public function mapClassToType(string $className, ?OutputType $subType): Mutable
                 return $typeMapper->mapClassToType($className, $subType);
             }
         }
+
         throw CannotMapTypeException::createForType($className);
     }
 

src/Mappers/RecursiveTypeMapper.php

@@ -114,6 +114,7 @@ public function mapClassToType(string $className, ?OutputType $subType): Mutable
         if ($closestClassName === null) {
             throw CannotMapTypeException::createForType($className);
         }
+
         $type = $this->typeMapper->mapClassToType($closestClassName, $subType);
 
         // In the event this type was already part of cache, let's not extend it.
@@ -452,8 +453,10 @@ public function getOutputTypes(): array
         $types     = [];
         $typeNames = [];
         foreach ($this->typeMapper->getSupportedClasses() as $supportedClass) {
-            $type                   = $this->mapClassToType($supportedClass, null);
+            $type = $this->mapClassToType($supportedClass, null);
+
             $types[$supportedClass] = $type;
+
             if (isset($typeNames[$type->name])) {
                 throw DuplicateMappingException::createForTypeName($type->name, $typeNames[$type->name], $supportedClass);
             }