From a3a808a8153761eb42fda3f9f629ad1e7e51338e Mon Sep 17 00:00:00 2001
From: kiro-agent <kiro-agent@users.noreply.github.com>
Date: Thu, 4 Jun 2026 21:02:05 +0000
Subject: [PATCH] docs: add PHP examples to client-side caching guide

---
 .../client-features/client-side-caching.mdx   | 73 +++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/src/content/docs/concepts/client-features/client-side-caching.mdx b/src/content/docs/concepts/client-features/client-side-caching.mdx
index 1b49a76c..7aeaa86c 100644
--- a/src/content/docs/concepts/client-features/client-side-caching.mdx
+++ b/src/content/docs/concepts/client-features/client-side-caching.mdx
@@ -169,6 +169,36 @@ To enable client-side caching, pass a `ClientSideCache` configuration when creat
     clusterClient, err := glide.NewGlideClusterClient(clusterConfig)
     ```
   </TabItem>
+
+  <TabItem label="PHP">
+    ```php
+    use ValkeyGlide\Cache\ClientSideCache;
+    use ValkeyGlide\ValkeyGlide;
+    use ValkeyGlide\ValkeyGlideCluster;
+
+    // Create a cache configuration
+    $cache = ClientSideCache::builder()
+        ->maxCacheKb(1024)                              // 1 MB maximum cache size
+        ->entryTtlMs(60000)                             // 60 second TTL per entry (0 = no expiration)
+        ->evictionPolicy(ClientSideCache::EVICTION_LRU) // LRU or LFU
+        ->enableMetrics(true)                           // Enable hit/miss tracking
+        ->build();
+
+    // Standalone client
+    $client = ValkeyGlide::connect(
+        host: 'localhost',
+        port: 6379,
+        client_side_cache: $cache->toArray(),
+    );
+
+    // Cluster client
+    $clusterClient = new ValkeyGlideCluster(
+        host: 'localhost',
+        port: 6379,
+        client_side_cache: $cache->toArray(),
+    );
+    ```
+  </TabItem>
 </Tabs>
 
 ### Configuration Options
@@ -253,6 +283,21 @@ When `enableMetrics` is set to `true`, you can query cache performance statistic
         entryCount, evictions, expirations)
     ```
   </TabItem>
+
+  <TabItem label="PHP">
+    ```php
+    // Get metrics
+    $hitRate = $client->getCacheHitRate();         // float 0.0–1.0
+    $missRate = $client->getCacheMissRate();       // float 0.0–1.0
+    $entryCount = $client->getCacheEntryCount();   // int
+    $evictions = $client->getCacheEvictions();     // int
+    $expirations = $client->getCacheExpirations(); // int
+
+    printf("Hit rate: %.2f%%\n", $hitRate * 100);
+    printf("Entries: %d, Evictions: %d, Expirations: %d\n",
+        $entryCount, $evictions, $expirations);
+    ```
+  </TabItem>
 </Tabs>
 
 <Aside type="note">
@@ -368,6 +413,34 @@ Multiple clients can share the same cache instance by passing the same `ClientSi
     result, _ := client2.Get("key")  // Cache hit
     ```
   </TabItem>
+
+  <TabItem label="PHP">
+    ```php
+    // Both clients share the same cache
+    $cache = ClientSideCache::builder()
+        ->maxCacheKb(1024)
+        ->entryTtlMs(60000)
+        ->build();
+
+    $client1 = ValkeyGlide::connect(
+        host: 'localhost',
+        port: 6379,
+        client_side_cache: $cache->toArray(),
+    );
+    $client2 = ValkeyGlide::connect(
+        host: 'localhost',
+        port: 6379,
+        client_side_cache: $cache->toArray(),
+    );
+
+    // client1 populates the cache
+    $client1->set('key', 'value');
+    $client1->get('key');  // Cache miss — fetches from server
+
+    // client2 gets a cache hit without contacting the server
+    $result = $client2->get('key');  // Cache hit
+    ```
+  </TabItem>
 </Tabs>
 
 <Aside type="caution">