documentation

Author: shmax

src/Validator/ValidationCache.php

@@ -3,23 +3,38 @@
 namespace GraphQL\Validator;
 
 use GraphQL\Language\AST\DocumentNode;
+use GraphQL\Tests\PsrValidationCacheAdapter;
 use GraphQL\Type\Schema;
 
 /**
- * Implement this interface and pass an instance to GraphQL::executeQuery to cache validation of ASTs.
- * The details of how to compute any keys (or whether to validate at all) are left up to you.
+ * 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 and schema combinations.
+ * You are responsible for defining how cache keys are computed, and when validation should be skipped.
+ *
+ * @see PsrValidationCacheAdapter for a toy implementation.
  */
 interface ValidationCache
 {
     /**
-     * Return true if the given schema + AST pair has previously been validated successfully.
-     * Only successful validations are cached.
-     * A return value of false means the pair is either unknown or has not been validated yet.
+     * Determine whether the given schema + AST pair 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.
+     *
+     * Note: This allows for optimizations in systems where validation may not be necessary on every request —
+     * for example, when using persisted queries that are known to be valid ahead of time. In such cases, you
+     * can implement this method to always return true.
+     *
+     * @return bool True if validation for the given schema + AST is already known to be valid; false otherwise.
      */
     public function isValidated(Schema $schema, DocumentNode $ast): bool;
 
     /**
-     * Cache validation status for this schema/query.
+     * Mark the given schema + AST pair 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): void;
 }

tests/PsrValidationCacheAdapter.php

@@ -59,7 +59,11 @@ public function markValidated(Schema $schema, DocumentNode $ast): void
      */
     private function buildKey(Schema $schema, DocumentNode $ast): string
     {
-        // NOTE: You can override this strategy if you want to make schema fingerprinting cheaper
+        /**
+         * NOTE: This default strategy generates a cache key by hashing the printed schema and AST.
+         * You'll likely want to replace this with a more stable or efficient method for fingerprinting
+         * the schema -- for example, a build-time hash, schema version number, or an environment-based identifier.
+         */
         $schemaHash = md5(SchemaPrinter::doPrint($schema));
         $astHash = md5($ast->__toString());