From 7edbfb11eab192b164ec530d60ab09e7dd118f1d Mon Sep 17 00:00:00 2001
From: Paul Klimov <klimov.paul@gmail.com>
Date: Wed, 9 Aug 2023 17:58:27 +0300
Subject: [PATCH] add docs

---
 README.md             | 68 +++++++++++++++++++++++++++++++++++++++++++
 src/CacheItemPool.php |  6 ++--
 2 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 63dbc51..d697ddb 100644
--- a/README.md
+++ b/README.md
@@ -194,3 +194,71 @@ function getCachedValue()
 
 ### Using cache tags <span id="using-cache-tags"></span>
 
+This extension allows setup of tags per each particular cache items via `\yii1tech\psr\cache\CacheItemContract::tag()` method.
+
+**Heads up!** This package does not directly implement cache tags feature - it does rely on wrapped Yii cache component to support it instead.
+All tags associated with the cache items are passed as 5th argument to `\ICache::set()` method assuming its particular implementation will
+handle them. Thus cache item tags saving will **silently fail** in related cache component does not provide support for it.
+
+You may use [yii1tech/tagged-cache](https://github.com/yii1tech/tagged-cache) extension to get a tag aware cache Yii component.
+
+Application configuration example:
+
+```php
+<?php
+
+return [
+    'components' => [
+        'cache' => [
+            'class' => \yii1tech\cache\tagged\MemCache::class, // use tag aware cache component
+            'servers' => [
+                // ...
+            ],
+        ],
+        \Psr\Cache\CacheItemPoolInterface::class => [
+            'class' => \yii1tech\psr\cache\CacheItemPool::class,
+            'cache' => 'cache',
+        ],
+        // ...
+    ],
+    // ...
+];
+```
+
+Tag specification example:
+
+```php
+<?php
+
+use yii1tech\psr\cache\CacheItemContract;
+use yii1tech\psr\cache\CacheItemPoolContract;
+
+function getCachedValue()
+{
+    /** @var CacheItemPoolContract $pool */
+    $pool = Yii::app()->getComponent(CacheItemPoolContract::class);
+    
+    return $pool->get('example-cache-id', function (CacheItemContract $item) {
+        $item->expiresAfter(DateInterval::createFromDateString('1 hour'));
+        $item->tag(['database', 'example']); // specify the list of tags for the item
+        
+        $value = Yii::app()->db->createCommand('SELECT ...')->query(); // some heave SQL query.
+        
+        return $value;
+    });
+}
+```
+
+In order to clear items associated with particular tag use `\yii1tech\psr\cache\CacheItemPoolContract::invalidateTags()`.
+For example:
+
+```php
+<?php
+
+use yii1tech\psr\cache\CacheItemPoolContract;
+
+/** @var CacheItemPoolInterface $pool */
+$pool = Yii::app()->getComponent(CacheItemPoolInterface::class);
+
+$pool->invalidateTags(['database']); // clear only items tagged as "database"
+```
diff --git a/src/CacheItemPool.php b/src/CacheItemPool.php
index 5f5675a..ffbf2cd 100644
--- a/src/CacheItemPool.php
+++ b/src/CacheItemPool.php
@@ -30,9 +30,9 @@
  * ];
  * ```
  *
- * > Note: for the cache item tags feature this class rely on wrapped Yii cache component, saving item tags
- *   will silently fail if such support is not provided. You'll need to install and use "yii1tech/tagged-cache"
- *   extension in order to make tags feature function.
+ * > Note: his package does not directly implement cache tags feature - it does rely on wrapped Yii cache component to support it instead.
+ *   All tags associated with the cache items are passed as 5th argument to {@see \ICache::set()} method assuming its particular implementation will
+ *   handle them. Thus cache item tags saving will **silently fail** in related cache component does not provide support for it.
  *
  * @see https://github.com/yii1tech/tagged-cache
  * @see \yii1tech\psr\cache\CacheItem