From 364f7edd2dacb3a4a5ff1e763b91ec0a47e9eccd Mon Sep 17 00:00:00 2001
From: Paul Klimov <klimov.paul@gmail.com>
Date: Fri, 4 Aug 2023 14:04:28 +0300
Subject: [PATCH] add docs

---
 README.md             | 94 ++++++++++++++++++++++++++++++++++++++++++-
 src/CacheItemPool.php | 23 +++++++++++
 2 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 136ec05..c016951 100644
--- a/README.md
+++ b/README.md
@@ -38,4 +38,96 @@ to the "require" section of your composer.json.
 Usage
 -----
 
-This extension allows integration with PSR-6 compatible cache for Yii1.
+This extension allows integration with [PSR-6](https://www.php-fig.org/psr/psr-6/) compatible cache for Yii1.
+It provides several instruments for that. Please choose the one suitable for your particular needs.
+
+
+### Wrap PSR cache pool into Yii cache <span id="wrap-psr-cache-pool-into-yii-cache"></span>
+
+The most common use case for PSR caceh involvement into Yii application is usage of 3rd party cache library.
+This can be achieved using `\yii1tech\psr\cache\Cache` as Yii cache component.
+
+Application configuration example:
+
+```php
+<?php
+
+return [
+    'components' => [
+        'cache' => [
+            'class' => \yii1tech\psr\cache\Cache::class,
+            'psrCachePool' => function () {
+                // ...
+                return new ExamplePsrCachePool(); // instantiate 3rd party cache library
+            },
+        ],
+        // ...
+    ],
+    // ...
+];
+```
+
+
+### Wrap Yii cache into PSR cache pool <span id="wrap-yii-cache-into-psr-cache-pool"></span>
+
+There is another use case related to PSR cache besides bootstrapping eternal cache storage.
+Sometimes 3rd party libraries may require PSR cache pool instance to be passed to them in order to function.
+`\Psr\Cache\CacheItemPoolInterface` allows wrapping standard Yii cache component into a PSR compatible cache pool.
+
+Application configuration example:
+
+```php
+<?php
+
+return [
+    'components' => [
+        'cache' => [
+            'class' => \CMemCache::class,
+            'servers' => [
+                // ...
+            ],
+        ],
+        \Psr\Cache\CacheItemPoolInterface::class => [
+            'class' => \yii1tech\psr\cache\CacheItemPool::class,
+            'cache' => 'cache',
+        ],
+        // ...
+    ],
+    // ...
+];
+```
+
+Usage example:
+
+```php
+<?php
+
+use Psr\Cache\CacheItemPoolInterface;
+
+function getCategoriesCount()
+{
+    /** @var CacheItemPoolInterface $pool */
+    $pool = Yii::app()->getComponent(CacheItemPoolInterface::class);
+    
+    $item = $pool->getItem('categories-count');
+    if ($item->isHit()) {
+        return $item->get();
+    }
+    
+    $value = Category::model()->count();
+    
+    $item->set($value)
+        ->expiresAfter(DateInterval::createFromDateString('1 hour'));
+    
+    $pool->save($item);
+    
+    return $value;
+}
+```
+
+
+### Simplified interface <span id="simplified-interface"></span>
+
+
+### Using cache tags <span id="using-cache-tags"></span>
+
diff --git a/src/CacheItemPool.php b/src/CacheItemPool.php
index d98e72d..9c62a74 100644
--- a/src/CacheItemPool.php
+++ b/src/CacheItemPool.php
@@ -8,6 +8,29 @@
 use Yii;
 
 /**
+ * CacheItemPool allows wrapping standard Yii cache component into a PSR compatible cache pool.
+ *
+ * Application configuration example:
+ *
+ * ```php
+ * return [
+ *     'components' => [
+ *         'cache' => [
+ *             'class' => \CMemCache::class,
+ *             'servers' => [
+ *                 // ...
+ *             ],
+ *         ],
+ *         \Psr\Cache\CacheItemPoolInterface::class => [
+ *             'class' => \yii1tech\psr\cache\CacheItemPool::class,
+ *             'cache' => 'cache',
+ *         ],
+ *         // ...
+ *     ],
+ *     // ...
+ * ];
+ * ```
+ *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 1.0
  */