Cache result of validation

composer.json

@@ -28,9 +28,11 @@
     "phpstan/phpstan-strict-rules": "2.0.4",
     "phpunit/phpunit": "^9.5 || ^10.5.21 || ^11",
     "psr/http-message": "^1 || ^2",
+    "psr/simple-cache": "^1.0",
     "react/http": "^1.6",
     "react/promise": "^2.0 || ^3.0",
     "rector/rector": "^2.0",
+    "symfony/cache": "^5.4",
     "symfony/polyfill-php81": "^1.23",
     "symfony/var-exporter": "^5 || ^6 || ^7",
     "thecodingmachine/safe": "^1.3 || ^2 || ^3"

docs/class-reference.md

@@ -70,7 +70,8 @@ static function executeQuery(
     ?array $variableValues = null,
     ?string $operationName = null,
     ?callable $fieldResolver = null,
-    ?array $validationRules = null
+    ?array $validationRules = null,
+    ?GraphQL\Validator\ValidationCache $cache = null
 ): GraphQL\Executor\ExecutionResult
 ```
 
@@ -98,7 +99,8 @@ static function promiseToExecute(
     ?array $variableValues = null,
     ?string $operationName = null,
     ?callable $fieldResolver = null,
-    ?array $validationRules = null
+    ?array $validationRules = null,
+    ?GraphQL\Validator\ValidationCache $cache = null
 ): GraphQL\Executor\Promise\Promise
 ```
 
@@ -1811,7 +1813,8 @@ static function validate(
     GraphQL\Type\Schema $schema,
     GraphQL\Language\AST\DocumentNode $ast,
     ?array $rules = null,
-    ?GraphQL\Utils\TypeInfo $typeInfo = null
+    ?GraphQL\Utils\TypeInfo $typeInfo = null,
+    ?GraphQL\Validator\ValidationCache $cache = null
 ): array
 ```
 

docs/executing-queries.md

@@ -210,3 +210,101 @@ $server = new StandardServer([
     'validationRules' => $myValidationRules
 ]);
 ```
+
+## Validation Caching
+
+Validation is a required step in GraphQL execution, but it can become a performance bottleneck when the same queries are
+run repeatedly — especially in production environments where queries are often static or pre-generated (e.g., persisted
+queries or queries emitted by client libraries).
+
+To optimize for this, `graphql-php` supports pluggable validation caching. By implementing the `GraphQL\Validator\ValidationCache` interface and passing it to
+`GraphQL::executeQuery()`, you can skip validation for queries that are already known to be valid.
+
+```php
+use GraphQL\Validator\ValidationCache;
+use GraphQL\GraphQL;
+use GraphQL\Tests\PsrValidationCacheAdapter;
+
+$validationCache = new PsrValidationCacheAdapter();
+
+$result = GraphQL::executeQuery(
+    $schema,
+    $queryString,
+    $rootValue,
+    $context,
+    $variableValues,
+    $operationName,
+    $fieldResolver,
+    $validationRules,
+    $validationCache
+);
+```
+
+### Key Generation Tips
+
+You are responsible for generating your own cache keys in a way that uniquely identifies the schema, the query, and
+(optionally) any custom validation rules. Here are some tips:
+
+- Hash your schema once at build time and store the result in an environment variable or constant.
+- Avoid using serialize() on schema objects — closures and internal references may cause errors.
+- If using custom validation rules, be sure to account for them in your key (e.g., by serializing or listing their class names).
+- Consider including the graphql-php version number to account for internal rule changes across versions.
+
+### Sample Implementation
+
+```php
+use GraphQL\Validator\ValidationCache;
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Type\Schema;
+use GraphQL\Utils\SchemaPrinter;
+use Psr\SimpleCache\CacheInterface;
+use Composer\InstalledVersions;
+
+/**
+ * Reference implementation of ValidationCache using PSR-16 cache.
+ *
+ * @see GraphQl\Tests\PsrValidationCacheAdapter
+ */
+class PsrValidationCacheAdapter implements ValidationCache
+{
+    private CacheInterface $cache;
+
+    private int $ttlSeconds;
+
+    public function __construct(
+        CacheInterface $cache,
+        int $ttlSeconds = 300
+    ) {
+        $this->cache = $cache;
+        $this->ttlSeconds = $ttlSeconds;
+    }
+
+    public function isValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): bool
+    {
+        $key = $this->buildKey($schema, $ast);
+        return $this->cache->has($key);
+    }
+
+    public function markValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): void
+    {
+        $key = $this->buildKey($schema, $ast);
+        $this->cache->set($key, true, $this->ttlSeconds);
+    }
+
+    private function buildKey(Schema $schema, DocumentNode $ast, ?array $rules = null): string
+    {
+        // Use a stable hash for schema. In production, prefer a build-time constant:
+        // $schemaHash = $_ENV['SCHEMA_VERSION'] ?? 'v1';
+        $schemaHash = md5(SchemaPrinter::doPrint($schema));
+
+        // Serialize AST and rules — both are predictable and safe in this context
+        $astHash = md5(serialize($ast));
+        $rulesHash = md5(serialize($rules));
+
+        // Include graphql-php version to account for internal changes
+        $libraryVersion = \Composer\InstalledVersions::getVersion('webonyx/graphql-php') ?: 'unknown';
+
+        return "graphql_validation_{$libraryVersion}_{$schemaHash}_{$astHash}_{$rulesHash}";
+    }
+}
+```

src/GraphQL.php

@@ -19,6 +19,7 @@
 use GraphQL\Validator\DocumentValidator;
 use GraphQL\Validator\Rules\QueryComplexity;
 use GraphQL\Validator\Rules\ValidationRule;
+use GraphQL\Validator\ValidationCache;
 
 /**
  * This is the primary facade for fulfilling GraphQL operations.
@@ -90,7 +91,8 @@ public static function executeQuery(
         ?array $variableValues = null,
         ?string $operationName = null,
         ?callable $fieldResolver = null,
-        ?array $validationRules = null
+        ?array $validationRules = null,
+        ?ValidationCache $cache = null
     ): ExecutionResult {
         $promiseAdapter = new SyncPromiseAdapter();
 
@@ -103,7 +105,8 @@ public static function executeQuery(
             $variableValues,
             $operationName,
             $fieldResolver,
-            $validationRules
+            $validationRules,
+            $cache
         );
 
         return $promiseAdapter->wait($promise);
@@ -132,7 +135,8 @@ public static function promiseToExecute(
         ?array $variableValues = null,
         ?string $operationName = null,
         ?callable $fieldResolver = null,
-        ?array $validationRules = null
+        ?array $validationRules = null,
+        ?ValidationCache $cache = null
     ): Promise {
         try {
             $documentNode = $source instanceof DocumentNode
@@ -152,7 +156,7 @@ public static function promiseToExecute(
                 }
             }
 
-            $validationErrors = DocumentValidator::validate($schema, $documentNode, $validationRules);
+            $validationErrors = DocumentValidator::validate($schema, $documentNode, $validationRules, null, $cache);
 
             if ($validationErrors !== []) {
                 return $promiseAdapter->createFulfilled(

src/Server/ServerConfig.php

@@ -124,7 +124,7 @@ public static function create(array $config = []): self
     private bool $queryBatching = false;
 
     /**
-     * @var array<ValidationRule>|callable|null
+     * @var array|callable|null
      *
      * @phpstan-var ValidationRulesOption
      */
@@ -315,7 +315,7 @@ public function getPromiseAdapter(): ?PromiseAdapter
     }
 
     /**
-     * @return array<ValidationRule>|callable|null
+     * @return array|callable|null
      *
      * @phpstan-return ValidationRulesOption
      */

src/Validator/DocumentValidator.php

@@ -99,20 +99,25 @@ public static function validate(
         Schema $schema,
         DocumentNode $ast,
         ?array $rules = null,
-        ?TypeInfo $typeInfo = null
+        ?TypeInfo $typeInfo = null,
+        ?ValidationCache $cache = null
     ): array {
-        $rules ??= static::allRules();
+        if (isset($cache)) {
+            if ($cache->isValidated($schema, $ast, $rules)) {
+                return [];
+            }
+        }
 
-        if ($rules === []) {
+        $finalRules = $rules ?? static::allRules();
+        if ($finalRules === []) {
             return [];
         }
 
         $typeInfo ??= new TypeInfo($schema);
-
         $context = new QueryValidationContext($schema, $ast, $typeInfo);
 
         $visitors = [];
-        foreach ($rules as $rule) {
+        foreach ($finalRules as $rule) {
             $visitors[] = $rule->getVisitor($context);
         }
 
@@ -124,7 +129,13 @@ public static function validate(
             )
         );
 
-        return $context->getErrors();
+        $errors = $context->getErrors();
+
+        if (isset($cache) && $errors === []) {
+            $cache->markValidated($schema, $ast, $rules);
+        }
+
+        return $errors;
     }
 
     /**
@@ -273,7 +284,6 @@ public static function validateSDL(
         ?array $rules = null
     ): array {
         $rules ??= self::sdlRules();
-
         if ($rules === []) {
             return [];
         }

src/Validator/ValidationCache.php

@@ -0,0 +1,49 @@
+<?php declare(strict_types=1);
+
+namespace GraphQL\Validator;
+
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Tests\PsrValidationCacheAdapter;
+use GraphQL\Type\Schema;
+use GraphQL\Validator\Rules\ValidationRule;
+
+/**
+ * Implement this interface and pass an instance to GraphQL::executeQuery to enable caching of successful query validations.
+ *
+ * This can improve performance by skipping validation for known-good combinations of query, schema, and rules.
+ * You are responsible for defining how cache keys are computed.
+ *
+ * Some things to keep in mind when generating keys:
+ * - PHP's `serialize` method is fast, but can't handle certain structures such as closures.
+ * - If your `schema` includes closures or is too large or complex to serialize,
+ *   consider using a build-time version number or environment-based fingerprint instead.
+ * - Keep in mind that there are internal `rules` that are applied in addition to any you pass in,
+ *   and it's possible these may shift or expand as the library evolves, so it might make sense
+ *   to include the library version number in your keys.
+ *
+ * @see PsrValidationCacheAdapter for a simple reference implementation.
+ */
+interface ValidationCache
+{
+    /**
+     * Determine whether the given schema/AST/rules set has already been successfully validated.
+     *
+     * This method should return true if the query has previously passed validation for the provided schema.
+     * Only successful validations should be considered "cached" — failed validations are not cached.
+     *
+     * @param array<ValidationRule>|null $rules
+     *
+     * @return bool true if validation for the given schema + AST + rules is already known to be valid; false otherwise
+     */
+    public function isValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): bool;
+
+    /**
+     * @param array<ValidationRule>|null $rules
+     *
+     * Mark the given schema/AST/rules set as successfully validated.
+     *
+     * This is typically called after a query passes validation.
+     * You should store enough information to recognize this combination on future requests.
+     */
+    public function markValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): void;
+}

tests/Executor/TestClasses/SpyValidationCacheAdapter.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types=1);
+
+namespace GraphQL\Tests\Executor\TestClasses;
+
+use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Tests\PsrValidationCacheAdapter;
+use GraphQL\Type\Schema;
+
+final class SpyValidationCacheAdapter extends PsrValidationCacheAdapter
+{
+    public int $isValidatedCalls = 0;
+
+    public int $markValidatedCalls = 0;
+
+    public function isValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): bool
+    {
+        ++$this->isValidatedCalls;
+
+        return parent::isValidated($schema, $ast);
+    }
+
+    public function markValidated(Schema $schema, DocumentNode $ast, ?array $rules = null): void
+    {
+        ++$this->markValidatedCalls;
+
+        parent::markValidated($schema, $ast);
+    }
+}