Make Ast serializable

With a serializable Ast, it is possible to cache the Ast. This will save
some parser time (reading attributes and classes with reflection).

Author: jerowork

docs/getting_started.md

@@ -32,6 +32,8 @@ $container = new YourPsr11Container();
 // 1. Create an AST based on your classes
 $ast = ParserFactory::create()->parse(__DIR__ . '/Path/To/GraphQL');
 
+// with $ast->toArray(), the AST is cacheable (see Cache section)
+
 // 2. Create the schema configuration
 $schema = SchemaBuilderFactory::create($container)->build($ast);
 
@@ -97,3 +99,28 @@ final readonly class GraphQLServerController
     }
 }
 ```
+
+## Caching
+To save parsing time (involving reflection of all classes and attributes),
+the AST is serializable. This makes the AST cacheable.
+
+```php
+use GraphQL\Server\StandardServer;
+use GraphQL\Server\ServerConfig;
+use Jerowork\GraphqlAttributeSchema\Parser\ParserFactory;
+use Jerowork\GraphqlAttributeSchema\SchemaBuilderFactory;
+
+// 1. Create an AST based on your classes
+$ast = ParserFactory::create()->parse(__DIR__ . '/Path/To/GraphQL');
+
+// Add to cache
+$someCache->set('graphql-attribute-schema.ast', json_encode($ast->toArray(), JSON_THROW_ON_ERROR));
+
+// ...
+
+// Get from cache
+$ast = Ast::fromArray(json_decode($someCache->get('graphql-attribute-schema.ast'), true, flags: JSON_THROW_ON_ERROR));
+
+// 2. Create the schema configuration
+$schema = SchemaBuilderFactory::create($container)->build($ast);
+```

docs/todo.md

@@ -4,8 +4,8 @@ This library is still work in progress, and misses some valuable features:
 - ~~Introduction of `#[Deprecated]` attribute~~
 - ~~Overwrite type via attributes~~
 - ~~Allow simple lists (array type)~~
+- ~~Make AST serializable (cacheable)~~
 - Connection, edge, nodes (see https://relay.dev/graphql/connections.htm)
-- Make AST serializable (cacheable)
 - Handle `DateTime` and `DateTimeImmutable`
 - GraphQL interfaces, inheritance
 - Inject autowiring services

src/Parser/Ast.php

@@ -4,9 +4,18 @@
 
 namespace Jerowork\GraphqlAttributeSchema\Parser;
 
+use Jerowork\GraphqlAttributeSchema\Parser\Node\ArraySerializable;
 use Jerowork\GraphqlAttributeSchema\Parser\Node\Node;
 
-final readonly class Ast
+/**
+ * @implements ArraySerializable<array{
+ *     nodes: list<array{
+ *          node: class-string,
+ *          payload: array<string, mixed>
+ *     }>
+ * }>
+ */
+final readonly class Ast implements ArraySerializable
 {
     /**
      * @var list<Node>
@@ -42,4 +51,32 @@ public function getNodeByClassName(string $className): ?Node
 
         return null;
     }
+
+    public function toArray(): array
+    {
+        $nodes = [];
+        foreach ($this->nodes as $node) {
+            $nodes[] = [
+                'node' => $node::class,
+                'payload' => $node->toArray(),
+            ];
+        }
+
+        return [
+            'nodes' => $nodes,
+        ];
+    }
+
+    public static function fromArray(array $payload): Ast
+    {
+        $nodes = [];
+        foreach ($payload['nodes'] as $nodePayload) {
+            /** @var Node $nodeClassName */
+            $nodeClassName = $nodePayload['node'];
+            $nodes[] = $nodeClassName::fromArray($nodePayload['payload']);
+        }
+
+        /** @var list<Node> $nodes */
+        return new self(...$nodes);
+    }
 }

src/Parser/Node/ArraySerializable.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Jerowork\GraphqlAttributeSchema\Parser\Node;
+
+/**
+ * @template T of array
+ */
+interface ArraySerializable
+{
+    /**
+     * @return T
+     */
+    public function toArray(): array;
+
+    /**
+     * @param T $payload
+     */
+    public static function fromArray(array $payload): self; // @phpstan-ignore-line
+}

src/Parser/Node/Child/ArgNode.php

@@ -4,14 +4,47 @@
 
 namespace Jerowork\GraphqlAttributeSchema\Parser\Node\Child;
 
+use Jerowork\GraphqlAttributeSchema\Parser\Node\ArraySerializable;
 use Jerowork\GraphqlAttributeSchema\Parser\Node\Type;
 
-final readonly class ArgNode
+/**
+ * @phpstan-import-type TypePayload from Type
+ *
+ * @phpstan-type ArgNodePayload array{
+ *     type: TypePayload,
+ *     name: string,
+ *     description: null|string,
+ *     propertyName: string
+ * }
+ *
+ * @implements ArraySerializable<ArgNodePayload>
+ */
+final readonly class ArgNode implements ArraySerializable
 {
     public function __construct(
         public Type $type,
         public string $name,
         public ?string $description,
         public string $propertyName,
     ) {}
+
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type->toArray(),
+            'name' => $this->name,
+            'description' => $this->description,
+            'propertyName' => $this->propertyName,
+        ];
+    }
+
+    public static function fromArray(array $payload): ArgNode
+    {
+        return new self(
+            Type::fromArray($payload['type']),
+            $payload['name'],
+            $payload['description'],
+            $payload['propertyName'],
+        );
+    }
 }

src/Parser/Node/Child/FieldNode.php

@@ -4,9 +4,27 @@
 
 namespace Jerowork\GraphqlAttributeSchema\Parser\Node\Child;
 
+use Jerowork\GraphqlAttributeSchema\Parser\Node\ArraySerializable;
 use Jerowork\GraphqlAttributeSchema\Parser\Node\Type;
 
-final readonly class FieldNode
+/**
+ * @phpstan-import-type ArgNodePayload from ArgNode
+ * @phpstan-import-type TypePayload from Type
+ *
+ * @phpstan-type FieldNodePayload array{
+ *     type: TypePayload,
+ *     name: string,
+ *     description: null|string,
+ *     argNodes: list<ArgNodePayload>,
+ *     fieldType: string,
+ *     methodName: null|string,
+ *     propertyName: null|string,
+ *     deprecationReason: null|string
+ * }
+ *
+ * @implements ArraySerializable<FieldNodePayload>
+ */
+final readonly class FieldNode implements ArraySerializable
 {
     /**
      * @param list<ArgNode> $argNodes
@@ -21,4 +39,32 @@ public function __construct(
         public ?string $propertyName,
         public ?string $deprecationReason,
     ) {}
+
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type->toArray(),
+            'name' => $this->name,
+            'description' => $this->description,
+            'argNodes' => array_map(fn($argNode) => $argNode->toArray(), $this->argNodes),
+            'fieldType' => $this->fieldType->value,
+            'methodName' => $this->methodName,
+            'propertyName' => $this->propertyName,
+            'deprecationReason' => $this->deprecationReason,
+        ];
+    }
+
+    public static function fromArray(array $payload): FieldNode
+    {
+        return new self(
+            Type::fromArray($payload['type']),
+            $payload['name'],
+            $payload['description'],
+            array_map(fn($argNodePayload) => ArgNode::fromArray($argNodePayload), $payload['argNodes']),
+            FieldNodeType::from($payload['fieldType']),
+            $payload['methodName'],
+            $payload['propertyName'],
+            $payload['deprecationReason'],
+        );
+    }
 }

src/Parser/Node/EnumNode.php

@@ -4,6 +4,16 @@
 
 namespace Jerowork\GraphqlAttributeSchema\Parser\Node;
 
+/**
+ * @phpstan-import-type EnumValueNodePayload from EnumValueNode
+ *
+ * @phpstan-type EnumNodePayload array{
+ *     className: class-string,
+ *     name: string,
+ *     description: null|string,
+ *     cases: list<EnumValueNodePayload>
+ * }
+ */
 final readonly class EnumNode implements Node
 {
     /**
@@ -21,4 +31,30 @@ public function getClassName(): string
     {
         return $this->className;
     }
+
+    /**
+     * @return EnumNodePayload
+     */
+    public function toArray(): array
+    {
+        return [
+            'className' => $this->className,
+            'name' => $this->name,
+            'description' => $this->description,
+            'cases' => array_map(fn($case) => $case->toArray(), $this->cases),
+        ];
+    }
+
+    /**
+     * @param EnumNodePayload $payload
+     */
+    public static function fromArray(array $payload): EnumNode
+    {
+        return new self(
+            $payload['className'],
+            $payload['name'],
+            $payload['description'],
+            array_map(fn($casePayload) => EnumValueNode::fromArray($casePayload), $payload['cases']),
+        );
+    }
 }

src/Parser/Node/EnumValueNode.php

@@ -4,11 +4,38 @@
 
 namespace Jerowork\GraphqlAttributeSchema\Parser\Node;
 
-final readonly class EnumValueNode
+/**
+ * @phpstan-type EnumValueNodePayload array{
+ *     value: string,
+ *     description: null|string,
+ *     deprecationReason: null|string
+ * }
+ *
+ * @implements ArraySerializable<EnumValueNodePayload>
+ */
+final readonly class EnumValueNode implements ArraySerializable
 {
     public function __construct(
         public string $value,
         public ?string $description,
         public ?string $deprecationReason,
     ) {}
+
+    public function toArray(): array
+    {
+        return [
+            'value' => $this->value,
+            'description' => $this->description,
+            'deprecationReason' => $this->deprecationReason,
+        ];
+    }
+
+    public static function fromArray(array $payload): EnumValueNode
+    {
+        return new self(
+            $payload['value'],
+            $payload['description'],
+            $payload['deprecationReason'],
+        );
+    }
 }

src/Parser/Node/InputTypeNode.php

@@ -6,6 +6,16 @@
 
 use Jerowork\GraphqlAttributeSchema\Parser\Node\Child\FieldNode;
 
+/**
+ * @phpstan-import-type FieldNodePayload from FieldNode
+ *
+ * @phpstan-type InputTypeNodePayload array{
+ *     className: class-string,
+ *     name: string,
+ *     description: null|string,
+ *     fieldNodes: list<FieldNodePayload>
+ * }
+ */
 final readonly class InputTypeNode implements Node
 {
     /**
@@ -23,4 +33,30 @@ public function getClassName(): string
     {
         return $this->className;
     }
+
+    /**
+     * @return InputTypeNodePayload
+     */
+    public function toArray(): array
+    {
+        return [
+            'className' => $this->className,
+            'name' => $this->name,
+            'description' => $this->description,
+            'fieldNodes' => array_map(fn($fieldNode) => $fieldNode->toArray(), $this->fieldNodes),
+        ];
+    }
+
+    /**
+     * @param InputTypeNodePayload $payload
+     */
+    public static function fromArray(array $payload): InputTypeNode
+    {
+        return new self(
+            $payload['className'],
+            $payload['name'],
+            $payload['description'],
+            array_map(fn($fieldNodePayload) => FieldNode::fromArray($fieldNodePayload), $payload['fieldNodes']),
+        );
+    }
 }