Allow lazy root types (query, mutation, subscription)

CHANGELOG.md

@@ -9,6 +9,10 @@ You can find and compare releases at the [GitHub release page](https://github.co
 
 ## Unreleased
 
+### Added
+
+- Allow lazy root types `query`, `mutation`, `subscription` https://github.com/webonyx/graphql-php/pull/1418
+
 ## v15.5.3
 
 ### Fixed

docs/class-reference.md

@@ -535,12 +535,13 @@ Usage example:
 
 @see Type, NamedType
 
+@phpstan-type MaybeLazyObjectType ObjectType|(callable(): ObjectType)|null
 @phpstan-type TypeLoader callable(string $typeName): ((Type&NamedType)|null)
 @phpstan-type Types iterable<Type&NamedType>|(callable(): iterable<Type&NamedType>)
 @phpstan-type SchemaConfigOptions array{
-query?: ObjectType|null,
-mutation?: ObjectType|null,
-subscription?: ObjectType|null,
+query?: MaybeLazyObjectType,
+mutation?: MaybeLazyObjectType,
+subscription?: MaybeLazyObjectType,
 types?: Types|null,
 directives?: array<Directive>|null,
 typeLoader?: TypeLoader|null,
@@ -563,6 +564,66 @@ extensionASTNodes?: array<SchemaExtensionNode>|null,
 static function create(array $options = []): self
 ```
 
+```php
+/**
+ * @return MaybeLazyObjectType
+ *
+ * @api
+ */
+function getQuery()
+```
+
+```php
+/**
+ * @param MaybeLazyObjectType $query
+ *
+ * @throws InvariantViolation
+ *
+ * @api
+ */
+function setQuery($query): self
+```
+
+```php
+/**
+ * @return MaybeLazyObjectType
+ *
+ * @api
+ */
+function getMutation()
+```
+
+```php
+/**
+ * @param MaybeLazyObjectType $mutation
+ *
+ * @throws InvariantViolation
+ *
+ * @api
+ */
+function setMutation($mutation): self
+```
+
+```php
+/**
+ * @return MaybeLazyObjectType
+ *
+ * @api
+ */
+function getSubscription()
+```
+
+```php
+/**
+ * @param MaybeLazyObjectType $subscription
+ *
+ * @throws InvariantViolation
+ *
+ * @api
+ */
+function setSubscription($subscription): self
+```
+
 ```php
 /**
  * @return array|callable

src/Type/Schema.php

@@ -147,7 +147,7 @@ public function getTypeMap(): array
                 TypeInfo::extractTypes($type, $allReferencedTypes);
             }
 
-            foreach ([$this->config->query, $this->config->mutation, $this->config->subscription] as $rootType) {
+            foreach ([$this->getQueryType(), $this->getMutationType(), $this->getSubscriptionType()] as $rootType) {
                 if ($rootType instanceof ObjectType) {
                     TypeInfo::extractTypes($rootType, $allReferencedTypes);
                 }
@@ -214,7 +214,17 @@ public function getOperationType(string $operation): ?ObjectType
      */
     public function getQueryType(): ?ObjectType
     {
-        return $this->config->query;
+        $query = $this->config->query;
+
+        if ($query === null) {
+            return null;
+        }
+
+        if (is_callable($query)) {
+            return $this->config->query = ($query)();
+        }
+
+        return $query;
     }
 
     /**
@@ -224,7 +234,17 @@ public function getQueryType(): ?ObjectType
      */
     public function getMutationType(): ?ObjectType
     {
-        return $this->config->mutation;
+        $mutation = $this->config->mutation;
+
+        if ($mutation === null) {
+            return null;
+        }
+
+        if (is_callable($mutation)) {
+            return $this->config->mutation = ($mutation)();
+        }
+
+        return $mutation;
     }
 
     /**
@@ -234,7 +254,17 @@ public function getMutationType(): ?ObjectType
      */
     public function getSubscriptionType(): ?ObjectType
     {
-        return $this->config->subscription;
+        $subscription = $this->config->subscription;
+
+        if ($subscription === null) {
+            return null;
+        }
+
+        if (is_callable($subscription)) {
+            return $this->config->subscription = ($subscription)();
+        }
+
+        return $subscription;
     }
 
     /** @api */

src/Type/SchemaConfig.php

@@ -2,6 +2,7 @@
 
 namespace GraphQL\Type;
 
+use GraphQL\Error\InvariantViolation;
 use GraphQL\Language\AST\SchemaDefinitionNode;
 use GraphQL\Language\AST\SchemaExtensionNode;
 use GraphQL\Type\Definition\Directive;
@@ -25,12 +26,13 @@
  *
  * @see Type, NamedType
  *
+ * @phpstan-type MaybeLazyObjectType ObjectType|(callable(): ObjectType)|null
  * @phpstan-type TypeLoader callable(string $typeName): ((Type&NamedType)|null)
  * @phpstan-type Types iterable<Type&NamedType>|(callable(): iterable<Type&NamedType>)
  * @phpstan-type SchemaConfigOptions array{
- *   query?: ObjectType|null,
- *   mutation?: ObjectType|null,
- *   subscription?: ObjectType|null,
+ *   query?: MaybeLazyObjectType,
+ *   mutation?: MaybeLazyObjectType,
+ *   subscription?: MaybeLazyObjectType,
  *   types?: Types|null,
  *   directives?: array<Directive>|null,
  *   typeLoader?: TypeLoader|null,
@@ -41,11 +43,14 @@
  */
 class SchemaConfig
 {
-    public ?ObjectType $query = null;
+    /** @var MaybeLazyObjectType */
+    public $query;
 
-    public ?ObjectType $mutation = null;
+    /** @var MaybeLazyObjectType */
+    public $mutation;
 
-    public ?ObjectType $subscription = null;
+    /** @var MaybeLazyObjectType */
+    public $subscription;
 
     /**
      * @var iterable|callable
@@ -124,43 +129,76 @@ public static function create(array $options = []): self
         return $config;
     }
 
-    /** @api */
-    public function getQuery(): ?ObjectType
+    /**
+     * @return MaybeLazyObjectType
+     *
+     * @api
+     */
+    public function getQuery()
     {
         return $this->query;
     }
 
-    /** @api */
-    public function setQuery(?ObjectType $query): self
+    /**
+     * @param MaybeLazyObjectType $query
+     *
+     * @throws InvariantViolation
+     *
+     * @api
+     */
+    public function setQuery($query): self
     {
+        $this->assertMaybeLazyObjectType($query);
         $this->query = $query;
 
         return $this;
     }
 
-    /** @api */
-    public function getMutation(): ?ObjectType
+    /**
+     * @return MaybeLazyObjectType
+     *
+     * @api
+     */
+    public function getMutation()
     {
         return $this->mutation;
     }
 
-    /** @api */
-    public function setMutation(?ObjectType $mutation): self
+    /**
+     * @param MaybeLazyObjectType $mutation
+     *
+     * @throws InvariantViolation
+     *
+     * @api
+     */
+    public function setMutation($mutation): self
     {
+        $this->assertMaybeLazyObjectType($mutation);
         $this->mutation = $mutation;
 
         return $this;
     }
 
-    /** @api */
-    public function getSubscription(): ?ObjectType
+    /**
+     * @return MaybeLazyObjectType
+     *
+     * @api
+     */
+    public function getSubscription()
     {
         return $this->subscription;
     }
 
-    /** @api */
-    public function setSubscription(?ObjectType $subscription): self
+    /**
+     * @param MaybeLazyObjectType $subscription
+     *
+     * @throws InvariantViolation
+     *
+     * @api
+     */
+    public function setSubscription($subscription): self
     {
+        $this->assertMaybeLazyObjectType($subscription);
         $this->subscription = $subscription;
 
         return $this;
@@ -275,4 +313,22 @@ public function setExtensionASTNodes(array $extensionASTNodes): self
 
         return $this;
     }
+
+    /**
+     * @param mixed $maybeLazyObjectType Should be MaybeLazyObjectType
+     *
+     * @throws InvariantViolation
+     */
+    protected function assertMaybeLazyObjectType($maybeLazyObjectType): void
+    {
+        if ($maybeLazyObjectType instanceof ObjectType || is_callable($maybeLazyObjectType) || is_null($maybeLazyObjectType)) {
+            return;
+        }
+
+        $notMaybeLazyObjectType = is_object($maybeLazyObjectType)
+            ? get_class($maybeLazyObjectType)
+            : gettype($maybeLazyObjectType);
+        $objectTypeClass = ObjectType::class;
+        throw new InvariantViolation("Expected instanceof {$objectTypeClass}, a callable that returns such an instance, or null, got: {$notMaybeLazyObjectType}.");
+    }
 }

src/Utils/BuildClientSchema.php

@@ -83,9 +83,9 @@ public function __construct(array $introspectionQuery, array $options = [])
      * the "errors" field of a server response before calling this function.
      *
      * @param array<string, mixed> $introspectionQuery
-     * @param array<string, bool>  $options
+     * @param array<string, bool> $options
      *
-     * @phpstan-param Options    $options
+     * @phpstan-param Options $options
      *
      * @api
      *

tests/Type/LazyDefinitionTest.php

@@ -182,4 +182,30 @@ public function testReturningFieldsUsingYield(): void
         self::assertSame($field->name, 'width');
         self::assertInstanceOf(IntType::class, $field->getType());
     }
+
+    public function testLazyRootTypes(): void
+    {
+        $query = new ObjectType([
+            'name' => 'Query',
+            'fields' => [],
+        ]);
+        $mutation = new ObjectType([
+            'name' => 'Mutation',
+            'fields' => [],
+        ]);
+        $subscription = new ObjectType([
+            'name' => 'Subscription',
+            'fields' => [],
+        ]);
+
+        $schema = new Schema([
+            'query' => fn () => $query,
+            'mutation' => fn () => $mutation,
+            'subscription' => fn () => $subscription,
+        ]);
+
+        self::assertSame($schema->getQueryType(), $query);
+        self::assertSame($schema->getMutationType(), $mutation);
+        self::assertSame($schema->getSubscriptionType(), $subscription);
+    }
 }