add docs

Author: shmax

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 already known to be valid:
+
+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/Validator/ValidationCache.php

@@ -10,18 +10,18 @@
 /**
  * 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 query, schema, and rules combinations.
+ * 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` does include closures or is quite large and complex, consider
- *   using some kind of build-time version number or other environment variable.
+ * - 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 toy implementation.
+ * @see PsrValidationCacheAdapter for a simple reference implementation.
  */
 interface ValidationCache
 {