Add NativeEnumTypeConfig to generate native PHP enums

.github/settings.yml

@@ -8,21 +8,6 @@ branches:
         dismiss_stale_reviews: true
         require_code_owner_reviews: true
         required_approving_review_count: 1
-      required_status_checks:
-        contexts:
-          -  "Coding Standards"
-          -  "Static Code Analysis"
-          -  "Tests (php7.3, lowest)"
-          -  "Tests (php7.3, locked)"
-          -  "Tests (php7.3, highest)"
-          -  "Tests (php7.3, lowest)"
-          -  "Tests (php7.3, locked)"
-          -  "Tests (php7.3, highest)"
-          -  "Code Coverage"
-          -  "Mutation Tests"
-          -  "codecov/patch"
-          -  "codecov/project"
-        strict: false
       restrictions: null
 
 labels:

.github/workflows/validate.yml

@@ -24,6 +24,26 @@ jobs:
   static-code-analysis:
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version:
+          - 7.4
+          - 8.0
+          - 8.1
+          - 8.2
+          - 8.3
+          - 8.4
+        dependencies:
+          - lowest
+          - highest
+        exclude:
+          # Problematic because those PHP versions allow nette/php-generator 3 which can not generate native enums
+          - php-version: 8.1
+            dependencies: lowest
+          - php-version: 8.2
+            dependencies: lowest
+
     steps:
       - uses: actions/checkout@v4
 
@@ -34,6 +54,14 @@ jobs:
           php-version: 8.3
 
       - uses: ramsey/composer-install@v3
+        with:
+          dependency-versions: "${{ matrix.dependencies }}"
+
+      # We require PHP 8.1 to generate native enums.
+      # Thus, the generated output differs in other versions, so we regenerate the code there.
+      # This is not ideal as it makes CodegenTest less useful, but allows us to move forward with native enums.
+      - if: ${{ matrix.php-version <= '8.1' }}
+        run: make approve
 
       - run: vendor/bin/phpstan analyse --configuration=phpstan.neon
 
@@ -52,8 +80,13 @@ jobs:
           - 8.4
         dependencies:
           - lowest
-          - locked
           - highest
+        exclude:
+          # Problematic because those PHP versions allow nette/php-generator 3 which can not generate native enums
+          - php-version: 8.1
+            dependencies: lowest
+          - php-version: 8.2
+            dependencies: lowest
 
     steps:
       - uses: actions/checkout@v4
@@ -68,6 +101,12 @@ jobs:
         with:
           dependency-versions: "${{ matrix.dependencies }}"
 
+      # We require PHP 8.1 to generate native enums.
+      # Thus, the generated output differs in other versions, so we regenerate the code there.
+      # This is not ideal as it makes CodegenTest less useful, but allows us to move forward with native enums.
+      - if: ${{ matrix.php-version <= '8.1' }}
+        run: make approve
+
       - run: vendor/bin/phpunit
 
   examples:

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `NativeEnumTypeConfig` to generate native PHP enums https://github.com/spawnia/sailor/pull/92
 - Allow `thecodingmachine/safe` v3 as dependency
 - Add `CarbonTypeConfig`
 

Makefile

@@ -3,7 +3,7 @@ it: fix stan approve test test-examples ## Run the commonly used targets
 
 .PHONY: help
 help: ## Displays this list of targets with descriptions
-	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
+	@grep --extended-regexp '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
 
 .PHONY: fix
 fix: vendor

README.md

@@ -111,10 +111,10 @@ HelloSailor::setClient(null);
 Custom scalars are commonly serialized as strings, but may also use other representations.
 Without knowing about the contents of the type, Sailor can not do any conversions or provide more accurate type hints, so it uses `mixed`.
 
-Enums are only supported from PHP 8.1. Many projects simply used scalar values or an implementation
-that approximates enums through some kind of value class. Sailor is not opinionated and generates
-enums as a class with string constants and does no conversion - useful but not perfect.
-For an improved experience, it is recommended to customize the enum generation/conversion.
+Since enums are only supported from PHP 8.1 and this library still supports PHP 7.4,
+it generates enums as a class with string constants and handles values as `string`.
+You may leverage native PHP enums by overriding `EndpointConfig::enumTypeConfig()`
+and return an instance of `Spawnia\Sailor\Type\NativeEnumTypeConfig`.
 
 Overwrite `EndpointConfig::configureTypes()` to specialize how Sailor deals with the types within your schema.
 See [examples/custom-types](examples/custom-types).

composer.json

@@ -17,7 +17,7 @@
   "require": {
     "php": "^7.4 || ^8",
     "ext-json": "*",
-    "nette/php-generator": "^3.6.7 || ^4",
+    "nette/php-generator": "^3.6.9 || ^4.1.7",
     "psr/http-client": "^1",
     "symfony/console": "^5 || ^6 || ^7",
     "symfony/var-exporter": "^5.3 || ^6 || ^7",
@@ -35,15 +35,17 @@
     "mockery/mockery": "^1.4",
     "nesbot/carbon": "^2.73 || ^3",
     "nyholm/psr7": "^1.4",
+    "ocramius/package-versions": "^1 || ^2",
     "php-http/httplug": "^2",
     "php-http/mock-client": "^1.4",
     "phpstan/extension-installer": "^1",
-    "phpstan/phpstan": "^1 || ^2",
+    "phpstan/phpstan": "^1.12.19 || ^2",
+    "phpstan/phpstan-deprecation-rules": "^1 || ^2",
     "phpstan/phpstan-mockery": "^1 || ^2",
     "phpstan/phpstan-phpunit": "^1 || ^2",
     "phpstan/phpstan-strict-rules": "^1 || ^2",
-    "phpunit/phpunit": "^9.5.2 || ^10 || ^11 || ^12",
-    "spawnia/phpunit-assert-directory": "^2",
+    "phpunit/phpunit": "^9.6.22 || ^10.5.45 || ^11.5.10 || ^12.0.5",
+    "spawnia/phpunit-assert-directory": "^2.1",
     "symfony/var-dumper": "^5.2.3 || ^6 || ^7",
     "thecodingmachine/phpstan-safe-rule": "^1.1"
   },
@@ -80,9 +82,6 @@
       "php-http/discovery": false,
       "phpstan/extension-installer": true
     },
-    "platform": {
-      "php": "7.4.15"
-    },
     "preferred-install": "dist",
     "sort-packages": true
   }

examples/custom-types/expected/Operations/MyBenSampoEnumQuery.php

@@ -10,8 +10,9 @@ class MyBenSampoEnumQuery extends \Spawnia\Sailor\Operation
     /**
      * @param \Spawnia\Sailor\CustomTypes\Types\BenSampoEnum|null $value
      */
-    public static function execute($value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): MyBenSampoEnumQuery\MyBenSampoEnumQueryResult
-    {
+    public static function execute(
+        $value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): MyBenSampoEnumQuery\MyBenSampoEnumQueryResult {
         return self::executeOperation(
             $value,
         );

examples/custom-types/expected/Operations/MyBenSampoEnumQuery/MyBenSampoEnumQuery.php

@@ -11,8 +11,9 @@ class MyBenSampoEnumQuery extends \Spawnia\Sailor\ObjectLike
     /**
      * @param \Spawnia\Sailor\CustomTypes\Types\BenSampoEnum|null $withBenSampoEnum
      */
-    public static function make($withBenSampoEnum = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): self
-    {
+    public static function make(
+        $withBenSampoEnum = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): self {
         $instance = new self;
 
         $instance->__typename = 'Query';

examples/custom-types/expected/Operations/MyCustomEnumQuery.php

@@ -10,8 +10,9 @@ class MyCustomEnumQuery extends \Spawnia\Sailor\Operation
     /**
      * @param \Spawnia\Sailor\CustomTypes\Types\CustomEnum|null $value
      */
-    public static function execute($value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): MyCustomEnumQuery\MyCustomEnumQueryResult
-    {
+    public static function execute(
+        $value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): MyCustomEnumQuery\MyCustomEnumQueryResult {
         return self::executeOperation(
             $value,
         );

examples/custom-types/expected/Operations/MyCustomEnumQuery/MyCustomEnumQuery.php

@@ -11,8 +11,9 @@ class MyCustomEnumQuery extends \Spawnia\Sailor\ObjectLike
     /**
      * @param \Spawnia\Sailor\CustomTypes\Types\CustomEnum|null $withCustomEnum
      */
-    public static function make($withCustomEnum = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): self
-    {
+    public static function make(
+        $withCustomEnum = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): self {
         $instance = new self;
 
         $instance->__typename = 'Query';

examples/custom-types/expected/Operations/MyCustomObjectQuery.php

@@ -10,8 +10,9 @@ class MyCustomObjectQuery extends \Spawnia\Sailor\Operation
     /**
      * @param \Spawnia\Sailor\CustomTypesSrc\CustomObject|null $value
      */
-    public static function execute($value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): MyCustomObjectQuery\MyCustomObjectQueryResult
-    {
+    public static function execute(
+        $value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): MyCustomObjectQuery\MyCustomObjectQueryResult {
         return self::executeOperation(
             $value,
         );

examples/custom-types/expected/Operations/MyCustomObjectQuery/MyCustomObjectQuery.php

@@ -11,8 +11,9 @@ class MyCustomObjectQuery extends \Spawnia\Sailor\ObjectLike
     /**
      * @param \Spawnia\Sailor\CustomTypesSrc\CustomObject|null $withCustomObject
      */
-    public static function make($withCustomObject = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): self
-    {
+    public static function make(
+        $withCustomObject = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): self {
         $instance = new self;
 
         $instance->__typename = 'Query';

examples/custom-types/expected/Operations/MyEnumInputQuery.php

@@ -10,8 +10,9 @@ class MyEnumInputQuery extends \Spawnia\Sailor\Operation
     /**
      * @param \Spawnia\Sailor\CustomTypes\Types\EnumInput|null $input
      */
-    public static function execute($input = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): MyEnumInputQuery\MyEnumInputQueryResult
-    {
+    public static function execute(
+        $input = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): MyEnumInputQuery\MyEnumInputQueryResult {
         return self::executeOperation(
             $input,
         );

examples/custom-types/expected/Operations/MyEnumInputQuery/MyEnumInputQuery.php

@@ -11,8 +11,9 @@ class MyEnumInputQuery extends \Spawnia\Sailor\ObjectLike
     /**
      * @param \Spawnia\Sailor\CustomTypes\Operations\MyEnumInputQuery\WithEnumInput\EnumObject|null $withEnumInput
      */
-    public static function make($withEnumInput = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'): self
-    {
+    public static function make(
+        $withEnumInput = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): self {
         $instance = new self;
 
         $instance->__typename = 'Query';

examples/custom-types/expected/Operations/MyEnumInputQuery/WithEnumInput/EnumObject.php

@@ -15,7 +15,7 @@ class EnumObject extends \Spawnia\Sailor\ObjectLike
      */
     public static function make(
         $custom = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
-        $default = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.'
+        $default = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
     ): self {
         $instance = new self;
 

examples/custom-types/expected/Operations/MyNativeEnumQuery.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types=1);
+
+namespace Spawnia\Sailor\CustomTypes\Operations;
+
+/**
+ * @extends \Spawnia\Sailor\Operation<\Spawnia\Sailor\CustomTypes\Operations\MyNativeEnumQuery\MyNativeEnumQueryResult>
+ */
+class MyNativeEnumQuery extends \Spawnia\Sailor\Operation
+{
+    /**
+     * @param \Spawnia\Sailor\CustomTypes\Types\NativeEnum|null $value
+     */
+    public static function execute(
+        $value = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): MyNativeEnumQuery\MyNativeEnumQueryResult {
+        return self::executeOperation(
+            $value,
+        );
+    }
+
+    protected static function converters(): array
+    {
+        static $converters;
+
+        return $converters ??= [
+            ['value', new \Spawnia\Sailor\Convert\NullConverter(new \Spawnia\Sailor\CustomTypes\TypeConverters\NativeEnumConverter)],
+        ];
+    }
+
+    public static function document(): string
+    {
+        return /* @lang GraphQL */ 'query MyNativeEnumQuery($value: NativeEnum) {
+          __typename
+          withNativeEnum(value: $value)
+        }';
+    }
+
+    public static function endpoint(): string
+    {
+        return 'custom-types';
+    }
+
+    public static function config(): string
+    {
+        return \Safe\realpath(__DIR__ . '/../../sailor.php');
+    }
+}

examples/custom-types/expected/Operations/MyNativeEnumQuery/MyNativeEnumQuery.php

@@ -0,0 +1,46 @@
+<?php declare(strict_types=1);
+
+namespace Spawnia\Sailor\CustomTypes\Operations\MyNativeEnumQuery;
+
+/**
+ * @property string $__typename
+ * @property \Spawnia\Sailor\CustomTypes\Types\NativeEnum|null $withNativeEnum
+ */
+class MyNativeEnumQuery extends \Spawnia\Sailor\ObjectLike
+{
+    /**
+     * @param \Spawnia\Sailor\CustomTypes\Types\NativeEnum|null $withNativeEnum
+     */
+    public static function make(
+        $withNativeEnum = 'Special default value that allows Sailor to differentiate between explicitly passing null and not passing a value at all.',
+    ): self {
+        $instance = new self;
+
+        $instance->__typename = 'Query';
+        if ($withNativeEnum !== self::UNDEFINED) {
+            $instance->withNativeEnum = $withNativeEnum;
+        }
+
+        return $instance;
+    }
+
+    protected function converters(): array
+    {
+        static $converters;
+
+        return $converters ??= [
+            '__typename' => new \Spawnia\Sailor\Convert\NonNullConverter(new \Spawnia\Sailor\Convert\StringConverter),
+            'withNativeEnum' => new \Spawnia\Sailor\Convert\NullConverter(new \Spawnia\Sailor\CustomTypes\TypeConverters\NativeEnumConverter),
+        ];
+    }
+
+    public static function endpoint(): string
+    {
+        return 'custom-types';
+    }
+
+    public static function config(): string
+    {
+        return \Safe\realpath(__DIR__ . '/../../../sailor.php');
+    }
+}

examples/custom-types/expected/Operations/MyNativeEnumQuery/MyNativeEnumQueryErrorFreeResult.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types=1);
+
+namespace Spawnia\Sailor\CustomTypes\Operations\MyNativeEnumQuery;
+
+class MyNativeEnumQueryErrorFreeResult extends \Spawnia\Sailor\ErrorFreeResult
+{
+    public MyNativeEnumQuery $data;
+
+    public static function endpoint(): string
+    {
+        return 'custom-types';
+    }
+
+    public static function config(): string
+    {
+        return \Safe\realpath(__DIR__ . '/../../../sailor.php');
+    }
+}