Added queryResultCache

Author: TomHAnderson

docs/driver.rst

@@ -25,6 +25,7 @@ Creating a Driver with all config options
       'limit' => 500,
       'sortFields' => true,
       'useHydratorCache' => true,
+      'useQueryResultCache' => true,
       'excludeFilters' => [Filters::LIKE],
   ]);
 
@@ -125,6 +126,27 @@ the duration of the request thereby saving possible multiple extracts for
 the same entity.  Default is ``false``
 
 
+useQueryResultCache
+-------------------
+
+When set to true query results will be cached for
+the duration of the request thereby preventing duplicate database queries
+with identical SQL and parameters. This is particularly useful for:
+
+- Circular references in the graph
+- Queries accessing the same entity multiple times
+- Duplicate association queries
+
+The cache is request-scoped and automatically cleared after each request.
+Performance benefits are most noticeable with complex, nested GraphQL queries
+that may execute the same database query multiple times.
+
+Default is ``false``
+
+**Note**: This caches the query results, not the hydrated entities.
+For entity caching, see ``useHydratorCache``.
+
+
 Functions
 =========
 

docs/technical/config-reference.rst

@@ -18,6 +18,7 @@ Class Overview
         public function getGroup(): string;
         public function getGroupSuffix(): ?string;
         public function getUseHydratorCache(): bool;
+        public function getUseQueryResultCache(): bool;
         public function getLimit(): int;
         public function getGlobalEnable(): bool;
         public function getIgnoreFields(): array;
@@ -51,6 +52,7 @@ Available Options
         'group' => 'default',            // string
         'groupSuffix' => null,           // string|null
         'useHydratorCache' => false,     // bool
+        'useQueryResultCache' => false,  // bool
         'limit' => 1000,                 // int
         'globalEnable' => false,         // bool
         'ignoreFields' => [],            // string[]
@@ -222,6 +224,74 @@ extracted once per request, and subsequent accesses return cached data.
 
 Cache is request-scoped only. Cleared after each GraphQL query execution.
 
+useQueryResultCache
+-------------------
+
+**Type**: ``bool``
+
+**Default**: ``false``
+
+**Description**:
+
+Enables request-scoped caching of database query results. When enabled, identical
+SQL queries with the same parameters are executed only once per request, with
+subsequent executions returning cached results.
+
+**Use Cases**:
+
+- Complex nested queries that may execute the same query multiple times
+- Circular references in the GraphQL query
+- Queries accessing the same associations repeatedly
+- Performance optimization for duplicate data access patterns
+
+**How It Works**:
+
+The cache generates a signature from the SQL query string and parameters. When a
+query is executed, the cache is checked first. If found, cached results are returned
+without database access.
+
+**Performance Impact**:
+
+.. code-block:: graphql
+
+    # Without cache: artist performances queried twice
+    {
+        artist1: artist(id: 1) {
+            performances { edges { node { venue } } }
+        }
+        artist2: artist(id: 1) {  # Same artist
+            performances { edges { node { venue } } }  # Duplicate query
+        }
+    }
+
+    # With cache: second performances query uses cached results
+    new Config(['useQueryResultCache' => true]);
+
+**Cache Statistics**:
+
+.. code-block:: php
+
+    use ApiSkeletons\Doctrine\ORM\GraphQL\Cache\QueryResultCache;
+
+    $cache = $driver->get(QueryResultCache::class);
+    $stats = $cache->getStats();
+
+    echo "Cache size: " . $stats['size'] . "\n";
+    echo "Cache hits: " . $stats['hits'] . "\n";
+    echo "Cache misses: " . $stats['misses'] . "\n";
+    echo "Hit rate: " . ($stats['hitRate'] * 100) . "%\n";
+
+**Scope**:
+
+Cache is request-scoped only. Automatically cleared after each request.
+
+**Difference from useHydratorCache**:
+
+- ``useQueryResultCache``: Caches database query results (SQL level)
+- ``useHydratorCache``: Caches entity extraction results (hydration level)
+
+Both can be enabled simultaneously for maximum caching.
+
 limit
 -----
 
@@ -696,6 +766,7 @@ Production Configuration
         'groupSuffix' => '',
         'sortFields' => true,
         'useHydratorCache' => true,
+        'useQueryResultCache' => true,
         'excludeFilters' => [
             Filters::CONTAINS,  // Expensive on large datasets
         ],
@@ -787,7 +858,7 @@ Best Practices
 4. **Use Groups for Multiple APIs**: Separate public/admin/internal APIs with different groups
 5. **Clean Type Names**: Use ``entityPrefix`` and ``groupSuffix`` for readable type names
 6. **Exclude Sensitive Fields**: Always use ``ignoreFields`` with ``globalEnable``
-7. **Profile Before Caching**: Only enable ``useHydratorCache`` if profiling shows benefit
+7. **Profile Before Caching**: Only enable ``useHydratorCache`` and ``useQueryResultCache`` if profiling shows benefit
 8. **Document Custom Configs**: Comment why you're using non-default values
 
 Common Pitfalls
@@ -796,6 +867,6 @@ Common Pitfalls
 1. **globalEnable in Production**: Security risk - always use explicit attributes
 2. **Same groupSuffix for Different Groups**: Causes type name collisions
 3. **Too High Limits**: Can cause memory exhaustion and slow queries
-4. **useHydratorCache Always On**: Wastes memory for simple queries
+4. **Cache Always On**: ``useHydratorCache`` and ``useQueryResultCache`` waste memory for simple queries
 5. **Empty entityPrefix**: Results in ugly type names like ``App_Entity_Artist_default``
 6. **Forgetting ignoreFields**: Exposes sensitive data with ``globalEnable``

docs/technical/performance.rst

@@ -154,6 +154,64 @@ Enable only when profiling shows repeated entity extraction:
 - Memory-constrained environments
 - Single-access patterns
 
+useQueryResultCache
+-------------------
+
+Enable to cache identical database queries within a single request:
+
+.. code-block:: php
+
+    new Config(['useQueryResultCache' => true]);
+
+**When to Enable**:
+
+- Complex GraphQL queries that may execute the same query multiple times
+- Queries with circular references or repeated associations
+- Deep nested queries accessing the same data paths
+- When profiling shows duplicate SQL queries
+
+**When to Disable**:
+
+- Simple queries without duplication
+- Memory-constrained environments
+- When query patterns show no duplication
+
+**How It Works**:
+
+The cache uses a signature based on SQL + parameters to identify identical queries.
+When a query is executed, the cache is checked first. If found, the cached results
+are returned without hitting the database. The cache is request-scoped and
+automatically cleared after the request completes.
+
+**Performance Impact**:
+
+.. code-block:: php
+
+    // Without cache: executes same query twice
+    query {
+        artist1: artist(id: 1) {
+            performances { edges { node { venue } } }
+        }
+        artist2: artist(id: 1) {  # Same artist
+            performances { edges { node { venue } } }  # Duplicate query
+        }
+    }
+
+    // With cache: second query uses cached results
+    // Queries reduced from 4 to 3 (artist query + performances query cached)
+
+**Cache Statistics**:
+
+.. code-block:: php
+
+    $cache = $driver->get(QueryResultCache::class);
+    $stats = $cache->getStats();
+
+    echo "Cache size: " . $stats['size'] . "\n";
+    echo "Hits: " . $stats['hits'] . "\n";
+    echo "Misses: " . $stats['misses'] . "\n";
+    echo "Hit rate: " . ($stats['hitRate'] * 100) . "%\n";
+
 **Profiling Example**:
 
 .. code-block:: php

src/Cache/QueryResultCache.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ApiSkeletons\Doctrine\ORM\GraphQL\Cache;
+
+use Doctrine\ORM\Query;
+
+use function count;
+use function md5;
+use function serialize;
+
+/**
+ * Request-scoped cache for query results.
+ *
+ * Caches query results based on SQL + parameters signature to prevent
+ * duplicate database queries within a single GraphQL request. This is
+ * particularly useful for:
+ * - Circular references in the graph
+ * - Queries accessing the same entity multiple times
+ * - Duplicate association queries
+ *
+ * The cache is stored in memory and is automatically cleared after
+ * the request completes.
+ */
+class QueryResultCache
+{
+    /** @var array<string, mixed[]> */
+    private array $cache = [];
+
+    /** @var array<string, int> */
+    private array $hits = [];
+
+    /** @var array<string, int> */
+    private array $misses = [];
+
+    /**
+     * Get cached results for a query if available
+     *
+     * @return mixed[]|null Returns cached results or null if not cached
+     */
+    public function get(Query $query): array|null
+    {
+        $cacheKey = $this->getCacheKey($query);
+
+        if (isset($this->cache[$cacheKey])) {
+            $this->hits[$cacheKey] = ($this->hits[$cacheKey] ?? 0) + 1;
+
+            return $this->cache[$cacheKey];
+        }
+
+        $this->misses[$cacheKey] = ($this->misses[$cacheKey] ?? 0) + 1;
+
+        return null;
+    }
+
+    /**
+     * Store query results in cache
+     *
+     * @param mixed[] $results
+     */
+    public function set(Query $query, array $results): void
+    {
+        $cacheKey               = $this->getCacheKey($query);
+        $this->cache[$cacheKey] = $results;
+    }
+
+    /**
+     * Check if query results are cached
+     */
+    public function has(Query $query): bool
+    {
+        return isset($this->cache[$this->getCacheKey($query)]);
+    }
+
+    /**
+     * Clear all cached results
+     */
+    public function clear(): void
+    {
+        $this->cache  = [];
+        $this->hits   = [];
+        $this->misses = [];
+    }
+
+    /**
+     * Get cache statistics
+     *
+     * @return array{size: int, hits: int, misses: int, hitRate: float}
+     */
+    public function getStats(): array
+    {
+        $totalHits   = 0;
+        $totalMisses = 0;
+
+        foreach ($this->hits as $hits) {
+            $totalHits += $hits;
+        }
+
+        foreach ($this->misses as $misses) {
+            $totalMisses += $misses;
+        }
+
+        $totalRequests = $totalHits + $totalMisses;
+        $hitRate       = $totalRequests > 0 ? $totalHits / $totalRequests : 0.0;
+
+        return [
+            'size' => count($this->cache),
+            'hits' => $totalHits,
+            'misses' => $totalMisses,
+            'hitRate' => $hitRate,
+        ];
+    }
+
+    /**
+     * Generate cache key from query SQL and parameters
+     */
+    private function getCacheKey(Query $query): string
+    {
+        $sql        = $query->getSQL();
+        $parameters = $query->getParameters()->toArray();
+
+        // Normalize parameters for consistent cache keys
+        $normalizedParams = [];
+        foreach ($parameters as $param) {
+            $normalizedParams[$param->getName()] = $param->getValue();
+        }
+
+        return md5($sql . serialize($normalizedParams));
+    }
+}