You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Cache manager using Doctrine Cache with easy-to-use PSR-16 API for quick caching
1
+
# Cache manager using Doctrine Cache, offers a very intuitive PSR-16 and PSR-6 API for cache manipulation.
2
2
3
-
Cache accelerates your application by storing data - once hardly retrieved - for future use. The caching manager focuses on [Doctrine Cache](https://github.com/doctrine/cache) for caching. [Cache](https://github.com/cache/cache) will be supported in the future.
4
-
5
-
Cache manager utilizes PSR-16 protocols to allow your application to communicate with cache engines. For now let's work with [Doctrine Cache](https://github.com/doctrine/cache).
3
+
The Cache manager is a [Doctrine Cache](https://github.com/doctrine/cache) based system, providing features covering simple to advanced caching needs. Natively implements PSR-6 and PSR-16 for greatest interoperability. It is designed for performance and resiliency. It enables concurrent caching, cache stampede protection via locking early expiration and more advanced caching stragegies.
6
4
7
5
**`Please note that this documentation is currently work-in-progress. Feel free to contribute.`**
8
6
@@ -14,84 +12,242 @@ The recommended way to install Cache Manager is via Composer:
14
12
composer require biurad/biurad-caching
15
13
```
16
14
17
-
It requires PHP version 7.0 and supports PHP up to 7.4. The dev-master version requires PHP 7.1.
15
+
It requires PHP version 7.1 and supports PHP up to 7.4. The dev-master version requires PHP 7.1.
18
16
19
17
## How To Use
20
18
21
19
Cache manager offers a very intuitive API for cache manipulation. Before we show you the first example, we need to think about place where
22
20
to store data physically. We can use a database, Memcached server, or the most available storage - hard drive. So we thought of using [Doctrine Cache](https://github.com/doctrine/cache) implementation:
23
21
24
22
```php
25
-
// the `temp` directory will be the storage
23
+
// you can use any of doctrine cache adapter
26
24
$storage = new Doctrine\Common\Cache\ArrayCache();
27
25
```
28
26
29
-
The `Doctrine\Common\Cache\Cache` storage is very well optimized for performance and in the first place,
30
-
it provides full atomicity of operations.
27
+
The `Doctrine\Common\Cache\Cache` storage is very well optimized for performance and in the first place, it provides full atomicity of operations.
28
+
29
+
What does that mean? When we use cache we can be sure we are not reading a file that is not fully written yet (by another thread) or that the file gets deleted "under our hands". Using the cache is therefore completely safe.
30
+
31
+
The package has 5 important strategies for caching, thus:
32
+
33
+
Strategy | Description
34
+
--- | ---
35
+
BiuradPHP\Cache\SimpleCache | For PSR-16 caching abilities using doctrine cache adapter
36
+
BiuradPHP\Cache\CacheItemPool | For PSR-6 caching abilities
37
+
BiuradPHP\Cache\FastCache | For advance and optimized PSR-16/PSR-6 caching strategy
38
+
BiuradPHP\Cache\MemoryCache | For caching using `var_export`
39
+
BiuradPHP\Cache\Preloader | For php7.4 opache.preload abilities
40
+
41
+
Now you can create, retrieve, update and delete items using the above caching classes except `Preloader` class:
42
+
43
+
> For manipulation with cache using psr-16, we use the `BiuradPHP\Cache\SimpleCache`:
44
+
---
45
+
46
+
```php
47
+
use BiuradPHP\Cache\SimpleCache;
48
+
49
+
$cache = new SimpleCache($storage); // psr-16 caching
If you want a bit advanced caching stratagy above PSR-16, PSR-6 is what you need, has a cool way of invalidating a missed cache.
104
+
105
+
> For manipulation with cache using `var_export`, we use the `BiuradPHP\Cache\MemoryCache`:
106
+
---
107
+
108
+
```php
109
+
use BiuradPHP\Cache\MemoryCache;
110
+
111
+
$cache = new MemoryCache(getcwd() . '/memory_cache');
112
+
```
113
+
114
+
```php
115
+
// assign a value to the item and save it
116
+
$products = [...]; // An array of products
117
+
$cache->saveData('stats.products', $products);
31
118
32
-
What does that mean? When we use cache we can be sure we are not reading a file that is not fully
33
-
written yet (by another thread) or that the file gets deleted "under our hands". Using the cache is therefore completely safe.
119
+
if (null === $productsCount) {
120
+
// ... item does not exist in the cache
121
+
}
34
122
35
-
For manipulation with cache, we use the `BiuradPHP\Cache\SimpleCache`:
123
+
// retrieve the value stored by the item
124
+
$total = $cache->loadData('stats.products');
125
+
126
+
// Remove cache item, by deleting the cache file.
127
+
```
128
+
129
+
> For manipulation with cache using advanced PSR-6, we use the `BiuradPHP\Cache\FastCache`:
130
+
---
131
+
132
+
For each method in `BiuradPHP\Cache\FastCache` class that has a second parameter `callable`, which is called when there is no such item in the cache. This callback receives 2 arguments at the end by reference. The `Psr\Cache\CacheItemInterface` and a boolean, which you can use for setting expiration rules and saving data into cache.
36
133
37
134
```php
135
+
use BiuradPHP\Cache\CacheItemPool;
38
136
use BiuradPHP\Cache\SimpleCache;
39
-
use BiuradPHP\Cache\FastCache as Caching;
137
+
use BiuradPHP\Cache\FastCache;
138
+
139
+
// you can use any of doctrine cache adapter
140
+
$storage = new Doctrine\Common\Cache\ArrayCache();
141
+
142
+
$psr6 = new CacheItemPool($psr16 = new SimpleCache($storage)); // psr-16 cache in psr-6 cache.
143
+
144
+
$cache = new FastCache($psr16);
40
145
41
-
$psr = new SimpleCache($storage); // $storage from the previous example
42
-
$cache = new Caching($psr);
146
+
//or
147
+
$cache = new FastCache($psr6);
43
148
```
44
149
45
-
Let's save the contents of the '`$data`' variable under the '`$key`' key:
150
+
The first argument of the load() method is a key, an arbitrary string that you associate to the cached value so you can retrieve it later. The second argument is a PHP callable which is executed when the key is not found in the cache to generate and return the value:
46
151
47
152
```php
48
-
$cache->save($key, $data);
153
+
use Psr\Cache\CacheItemIterface;
154
+
155
+
// The callable will only be executed on a cache miss.
156
+
$value = $cache->load('my_cache_key', function (CacheItemInterface $item) {
157
+
$item->expiresAfter(3600);
158
+
159
+
// ... do some HTTP request or heavy computations
160
+
$computedValue = 'foobar';
161
+
162
+
return $computedValue;
163
+
});
164
+
165
+
echo $value; // 'foobar'
166
+
167
+
// ... and to remove the cache key
168
+
$cache->delete('my_cache_key');
49
169
```
50
170
51
-
This way, we can read from the cache: (if there is no such item in the cache, the `null` value is returned)
171
+
The callable caching feature. Caching the result of a function or method call can be achieved using the `call()` method:
52
172
53
173
```php
54
-
$value = $cache->load($key);
55
-
if ($value === null) ...
174
+
$name = $cache->call('gethostbyaddr', $ip);
56
175
```
57
176
58
-
Method `get()` has second parameter `callable``$fallback`, which is called when there is no such item in the cache. This callback receives the array *$dependencies* by reference, which you can use for setting expiration rules.
177
+
The `gethostbyaddr($ip)` will, therefore, be called only once and next time, only the value from cache will be returned. Of course, for different `$ip`, different results are cached. But if you want to set expiry time on call, add `Psr\Cache\CacheItemInterface` argument at the end and set the expiration time.
178
+
179
+
Similarly, it is possible to wrap a function with cache and call it later.
59
180
60
181
```php
61
-
$cache->save($key, function(& $dependencies) {
62
-
// some calculation
63
-
64
-
return 15;
65
-
}));
182
+
function calculate($number)
183
+
{
184
+
return 'number is ' . $number;
185
+
}
186
+
187
+
$wrapper = $cache->wrap('calculate');
66
188
67
-
$value = $cache->load($key);
189
+
$result = $wrapper(1); // number is 1
190
+
$result = $wrapper(2); // number is 2
68
191
```
69
192
70
-
We could delete the item from the cache either by saving null or by calling `delete()` method:
193
+
The template/output caching feature. Caching the result of an output can be cached not only in templates:
71
194
72
195
```php
73
-
$cache->save($key, null);
74
-
// or
75
-
$cache->remove($key);
196
+
if ($block = $cache->start($key)) {
197
+
... printing some data ...
198
+
199
+
$block->end(); // save the output to the cache
200
+
}
76
201
```
77
202
78
-
It's possible to save any structure to the cache, not only strings. The same applies for keys.
203
+
In case that the output is already present in the cache, the `start()` method prints it and returns `null`. Otherwise, it starts to buffer the output and returns the `$block` object using which we finally save the data to the cache.
79
204
80
-
Deleting the cache is a common operation when uploading a new application version to the server. At that moment, however, using [Doctrine Cache](https://github.com/doctrine/cache), the server can handle it's operations.
81
-
because it has to build a complete new cache. Retrieving some data is not difficult, cause [Doctrine Cache](https://github.com/doctrine/cache) create temporary memory data, so you don't run into further errors. If you are experiencing difficulties in caching.
205
+
The expiration and invalidation caching feature.
82
206
83
-
The solution is to modify application behaviour so that data are created only by one thread and others are waiting. To do this, specify the value as a callback
84
-
or use an anonymous function:
207
+
This feature works with only PSR-6 cache, By default the beta is 1.0 and higher values mean earlier recompute. Set it to 0 to disable early recompute and set it to INF to force an immediate recompute:
85
208
86
209
```php
87
-
$result = $cache->save($key, function() {
210
+
use Psr\Cache\CacheItemIterface;
88
211
89
-
return buildData(); // difficult operation
90
-
});
212
+
$beta = 1.0;
213
+
$value = $cache->save('my_cache_key', function (CacheItemInterface $item) {
214
+
$item->expiresAfter(3600);
215
+
216
+
return '...';
217
+
}, $beta);
218
+
```
219
+
220
+
If you want more control over caching any php type except closures, this package is just for you. This package implements [Stampede prevention](https://en.wikipedia.org/wiki/Cache_stampede), concurrent caching and works perfectly with either PSR-6 or PSR-16 cache.
221
+
222
+
> For manipulation of php 7.4 opcache preload feature, we use the `BiuradPHP\Cache\Preloader`:
223
+
---
224
+
225
+
```php
226
+
use BiuradPHP\Cache\Preloader;
227
+
228
+
$preloadClasses = [...]; // A list array of classes to be appended for preloading.
229
+
$preloadFile = getcwd().'/opcache.preload.php'; // The file preloaded classes to fetch from.
230
+
231
+
Preloader::append($preloadFile, $preloadClasses);
232
+
233
+
// to check opcache preload statistics
234
+
var_dump(Preloader::getStatistics());
235
+
```
236
+
237
+
After the `$preloadFile` is written into, set the following configuration in your php.ini file:
238
+
239
+
```ini
240
+
; php.ini
241
+
opcache.preload=/path/to/opcache.preload.php
242
+
243
+
; maximum memory that OPcache can use to store compiled PHP files
244
+
opcache.memory_consumption=256
245
+
246
+
; maximum number of files that can be stored in the cache
247
+
opcache.max_accelerated_files=20000
91
248
```
92
249
93
-
The Cache-manager will ensure that the body of the function will be called only by one thread at once, and other threads will be waiting.
94
-
If the thread fails for some reason, another gets chance.
250
+
Starting from PHP 7.4, OPcache can compile and load classes at start-up and make them available to all requests until the server is restarted, improving performance significantly.
0 commit comments