Merge pull request #1048 from sparklink-pro/enum_php

PHP 8.1 Enum support

Author: Vincz

.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
             symfony-version: '5.4.*'
             dependencies: 'lowest'
             remove-dependencies: '--dev symfony/validator doctrine/orm doctrine/annotations'
-          - php-version: '8.0'
+          - php-version: '8.1'
             symfony-version: '5.4.*'
             dependencies: 'lowest'
             coverage: "pcov"
@@ -86,7 +86,7 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           tools: flex
-          php-version: "8.0"
+          php-version: "8.1"
 
       - name: "Install dependencies"
         uses: ramsey/composer-install@v2
@@ -101,7 +101,6 @@ jobs:
       fail-fast: false
       matrix:
         php-version:
-          - '8.0'
           - '8.1'
     steps:
       - name: "Checkout"

docs/definitions/type-system/enum.md

@@ -57,3 +57,57 @@ class Episode
     public $value;
 }
 ```
+
+## Working with native PHP 8.1 enums
+
+Given a PHP enum as follow:
+
+```php
+namespace App;
+
+enum Color 
+{
+    case RED;
+    case GREEN;
+    case BLUE;
+}
+```
+
+You can declare it with annotations or attributes as follow:
+
+```php
+#[GQL\Enum]
+enum Color 
+{
+    #[GQL\Description("The color red")]
+    case RED;
+    case GREEN;
+    case BLUE;
+}
+```
+
+or with YAML:
+
+```yaml
+Color:
+    type: enum
+    config:
+        enumClass: App\Color
+```
+
+The possible values will be automatically extracted from the enum but if you need to add description and/or deprecated, you can proceed this way
+
+```yaml
+Color:
+    type: enum
+    config:
+        enumClass: App\Color
+        values:
+            GREEN:
+                description: "The color green"
+```
+When using PHP enum, the serialization will extract the `name` of the enum case, and the deserialization will return the enum case by its `name`.  
+Even if the used enum is a Backed enum, the serialization and deserialization will always use the `name` and not the value.  
+
+
+

src/Config/EnumTypeDefinition.php

@@ -21,6 +21,16 @@ public function getDefinition(): ArrayNodeDefinition
         $node
             ->children()
                 ->append($this->nameSection())
+                ->scalarNode('enumClass')
+                    ->validate()
+                        ->ifTrue(fn () => PHP_VERSION_ID < 80100)
+                        ->thenInvalid('The enumClass option requires PHP 8.1 or higher.')
+                    ->end()
+                    ->validate()
+                        ->ifTrue(fn ($v) => !class_exists($v))
+                        ->thenInvalid('The specified enum Class "%s" does not exist.')
+                    ->end()
+                ->end()
                 ->arrayNode('values')
                     ->useAttributeAsKey('name')
                     ->beforeNormalization()
@@ -49,8 +59,6 @@ public function getDefinition(): ArrayNodeDefinition
                             ->append($this->deprecationReasonSection())
                         ->end()
                     ->end()
-                    ->isRequired()
-                    ->requiresAtLeastOneElement()
                 ->end()
                 ->append($this->descriptionSection())
             ->end();

src/Config/Parser/MetadataParser/MetadataParser.php

@@ -42,6 +42,8 @@
 use function substr;
 use function trim;
 
+use const PHP_VERSION_ID;
+
 abstract class MetadataParser implements PreParserInterface
 {
     public const ANNOTATION_NAMESPACE = 'Overblog\GraphQLBundle\Annotation\\';
@@ -434,15 +436,15 @@ private static function enumMetadataToGQLConfiguration(ReflectionClass $reflecti
     {
         $metadatas = static::getMetadatas($reflectionClass);
         $enumValues = self::getMetadataMatching($metadatas, Metadata\EnumValue::class);
-
+        $isPhpEnum = PHP_VERSION_ID >= 80100 && $reflectionClass->isEnum();
         $values = [];
 
         foreach ($reflectionClass->getConstants() as $name => $value) {
             $reflectionConstant = new ReflectionClassConstant($reflectionClass->getName(), $name);
             $valueConfig = self::getDescriptionConfiguration(static::getMetadatas($reflectionConstant), true);
 
             $enumValueAnnotation = current(array_filter($enumValues, fn ($enumValueAnnotation) => $enumValueAnnotation->name === $name));
-            $valueConfig['value'] = $value;
+            $valueConfig['value'] = $isPhpEnum ? $value->name : $value;
 
             if (false !== $enumValueAnnotation) {
                 if (isset($enumValueAnnotation->description)) {
@@ -459,6 +461,9 @@ private static function enumMetadataToGQLConfiguration(ReflectionClass $reflecti
 
         $enumConfiguration = ['values' => $values];
         $enumConfiguration = self::getDescriptionConfiguration(static::getMetadatas($reflectionClass)) + $enumConfiguration;
+        if ($isPhpEnum) {
+            $enumConfiguration['enumClass'] = $reflectionClass->getName();
+        }
 
         return ['type' => 'enum', 'config' => $enumConfiguration];
     }

src/Definition/Type/PhpEnumType.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Overblog\GraphQLBundle\Definition\Type;
+
+use Exception;
+use GraphQL\Error\Error;
+use GraphQL\Error\SerializationError;
+use GraphQL\Language\AST\EnumTypeDefinitionNode;
+use GraphQL\Language\AST\EnumTypeExtensionNode;
+use GraphQL\Language\AST\EnumValueNode;
+use GraphQL\Language\AST\Node;
+use GraphQL\Type\Definition\EnumType;
+use GraphQL\Utils\Utils;
+use ReflectionEnum;
+use UnitEnum;
+
+/**
+ * @phpstan-import-type EnumValues from EnumType
+ *
+ * @phpstan-type PhpEnumTypeConfig array{
+ *   name?: string|null,
+ *   description?: string|null,
+ *   enumClass?: class-string<\UnitEnum>|null,
+ *   values?: EnumValues|callable(): EnumValues,
+ *   astNode?: EnumTypeDefinitionNode|null,
+ *   extensionASTNodes?: array<int, EnumTypeExtensionNode>|null
+ * }
+ */
+class PhpEnumType extends EnumType
+{
+    /** @var class-string<UnitEnum>|null */
+    protected ?string $enumClass = null;
+
+    /**
+     * @phpstan-param PhpEnumTypeConfig $config
+     */
+    public function __construct(array $config)
+    {
+        if (isset($config['enumClass'])) {
+            $this->enumClass = $config['enumClass'];
+            if (!enum_exists($this->enumClass)) {
+                throw new Error(sprintf('Enum class "%s" does not exist.', $this->enumClass));
+            }
+            unset($config['enumClass']);
+        }
+
+        if (!isset($config['values'])) {
+            $config['values'] = [];
+        }
+
+        parent::__construct($config);
+        if ($this->enumClass) {
+            $configValues = $this->config['values'] ?? [];
+            if (is_callable($configValues)) {
+                $configValues = $configValues();
+            }
+            $reflection = new ReflectionEnum($this->enumClass);
+
+            $enumDefinitions = [];
+            foreach ($reflection->getCases() as $case) {
+                $enumDefinitions[$case->getName()] = ['value' => $case->getName()];
+            }
+
+            foreach ($configValues as $name => $config) {
+                if (!isset($enumDefinitions[$name])) {
+                    throw new Error("Enum value {$name} is not defined in {$this->enumClass}");
+                }
+                $enumDefinitions[$name]['description'] = $config['description'] ?? null;
+                $enumDefinitions[$name]['deprecationReason'] = $config['deprecationReason'] ?? null;
+            }
+
+            $this->config['values'] = $enumDefinitions;
+        }
+    }
+
+    public function parseValue($value): mixed
+    {
+        if ($this->enumClass) {
+            try {
+                return (new ReflectionEnum($this->enumClass))->getCase($value)->getValue();
+            } catch (Exception $e) {
+                throw new Error("Cannot represent enum of class {$this->enumClass} from value {$value}: ".$e->getMessage());
+            }
+        }
+
+        return parent::parseValue($value);
+    }
+
+    public function parseLiteral(Node $valueNode, ?array $variables = null): mixed
+    {
+        if ($this->enumClass) {
+            if (!$valueNode instanceof EnumValueNode) {
+                throw new Error("Cannot represent enum of class {$this->enumClass} from node: {$valueNode->__toString()} is not an enum value");
+            }
+            try {
+                return (new ReflectionEnum($this->enumClass))->getCase($valueNode->value)->getValue();
+            } catch (Exception $e) {
+                throw new Error("Cannot represent enum of class {$this->enumClass} from literal {$valueNode->value}: ".$e->getMessage());
+            }
+        }
+
+        return parent::parseLiteral($valueNode, $variables);
+    }
+
+    public function serialize($value): mixed
+    {
+        if ($this->enumClass) {
+            if (!$value instanceof $this->enumClass) {
+                $valueStr = Utils::printSafe($value);
+                throw new SerializationError("Cannot serialize value {$valueStr} as it must be an instance of enum {$this->enumClass}.");
+            }
+
+            return $value->name;
+        }
+
+        return parent::serialize($value);
+    }
+}

src/Generator/TypeBuilder.php

@@ -6,7 +6,6 @@
 
 use GraphQL\Language\AST\NodeKind;
 use GraphQL\Language\Parser;
-use GraphQL\Type\Definition\EnumType;
 use GraphQL\Type\Definition\InputObjectType;
 use GraphQL\Type\Definition\InterfaceType;
 use GraphQL\Type\Definition\ObjectType;
@@ -27,6 +26,7 @@
 use Overblog\GraphQLBundle\Definition\Resolver\AliasedInterface;
 use Overblog\GraphQLBundle\Definition\Type\CustomScalarType;
 use Overblog\GraphQLBundle\Definition\Type\GeneratedTypeInterface;
+use Overblog\GraphQLBundle\Definition\Type\PhpEnumType;
 use Overblog\GraphQLBundle\Error\ResolveErrors;
 use Overblog\GraphQLBundle\ExpressionLanguage\ExpressionLanguage as EL;
 use Overblog\GraphQLBundle\Generator\Converter\ExpressionConverter;
@@ -70,7 +70,7 @@ final class TypeBuilder
         'input-object' => InputObjectType::class,
         'interface' => InterfaceType::class,
         'union' => UnionType::class,
-        'enum' => EnumType::class,
+        'enum' => PhpEnumType::class,
         'custom-scalar' => CustomScalarType::class,
     ];
 
@@ -342,6 +342,9 @@ private function buildConfig(array $config): Collection
         if (isset($c->values)) {
             $configLoader->addItem('values', Collection::assoc($c->values));
         }
+        if (isset($c->enumClass)) {
+            $configLoader->addItem('enumClass', $c->enumClass);
+        }
 
         // only by custom-scalar types
         if ('custom-scalar' === $this->type) {

src/Transformer/ArgumentsTransformer.php

@@ -10,6 +10,7 @@
 use GraphQL\Type\Definition\NonNull;
 use GraphQL\Type\Definition\ResolveInfo;
 use GraphQL\Type\Definition\Type;
+use Overblog\GraphQLBundle\Definition\Type\PhpEnumType;
 use Overblog\GraphQLBundle\Error\InvalidArgumentError;
 use Overblog\GraphQLBundle\Error\InvalidArgumentsError;
 use Symfony\Component\PropertyAccess\PropertyAccess;
@@ -80,6 +81,10 @@ private function populateObject(Type $type, $data, bool $multiple, ResolveInfo $
         }
 
         if ($type instanceof EnumType) {
+            /** Enum based on PHP Enum are already processed by PhpEnumType */
+            if (isset($type->config['enumClass'])) { /** @phpstan-ignore-line */
+                return $data;
+            }
             $instance = $this->getTypeClassInstance($type->name);
             if ($instance) {
                 $this->accessor->setValue($instance, 'value', $data);

tests/Config/Parser/MetadataParserTest.php

@@ -7,6 +7,7 @@
 use Doctrine\Common\Annotations\Reader;
 use Doctrine\ORM\Mapping\Column;
 use Exception;
+use Overblog\GraphQLBundle\Tests\Config\Parser\fixtures\annotations\Enum\Color;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
 use SplFileInfo;
@@ -62,6 +63,9 @@ public function setUp(): void
                     if (!self::isDoctrineOrmInstalled() && 'Lightsaber.php' === $file->getFileName()) {
                         continue 2;
                     }
+                    if (PHP_VERSION_ID < 80100 && 'Color.php' === $file->getFileName()) {
+                        continue 2;
+                    }
                 }
 
                 $files[] = $file->getPathname();
@@ -249,6 +253,18 @@ public function testEnum(): void
                 'TWILEK' => ['value' => '4'],
             ],
         ]);
+
+        if (PHP_VERSION_ID >= 80100) {
+            $this->expect('Color', 'enum', [
+                'enumClass' => Color::class,
+                'values' => [
+                    'RED' => ['value' => 'RED', 'description' => 'The color red'],
+                    'GREEN' => ['value' => 'GREEN'],
+                    'BLUE' => ['value' => 'BLUE'],
+                    'YELLOW' => ['value' => 'YELLOW'],
+                ],
+            ]);
+        }
     }
 
     public function testUnion(): void

tests/Config/Parser/fixtures/annotations/Enum/Color.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Overblog\GraphQLBundle\Tests\Config\Parser\fixtures\annotations\Enum;
+
+use Overblog\GraphQLBundle\Annotation as GQL;
+
+/**
+ * @GQL\Enum
+ * @GQL\EnumValue(name="RED", description="The color red")
+ */
+#[GQL\Enum]
+enum Color
+{
+    #[GQL\Description('The color red')]
+    case RED;
+
+    case GREEN;
+
+    case BLUE;
+
+    case YELLOW;
+}