Skip to content

Commit e6ea301

Browse files
Joel-JamesJoel-James
committed
🚀 First release
1 parent 9f65b57 commit e6ea301

File tree

4 files changed

+708
-0
lines changed

4 files changed

+708
-0
lines changed

‎README.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
<p align="center">
2+
<a href="http://duckdev.com" target="_blank">
3+
<img width="200px" src="https://duckdev.com/wp-content/uploads/2020/12/cropped-duckdev-logo-mid.png">
4+
</a>
5+
</p>
6+
7+
# WP Cache Helper
8+
9+
WP Cache Helper is a simple WordPress library class to introduce convenient new caching functions.
10+
11+
Built to support group cache flush for WordPress' object cache, which is [not supported by core yet](https://core.trac.wordpress.org/ticket/4476).
12+
13+
* Inspired from [WP Cache Remember](https://github.com/stevegrunwell/wp-cache-remember).
14+
15+
This helper can simplify something like this:
16+
17+
```php
18+
function do_something() {
19+
$cache_key = 'some-cache-key';
20+
$cached = wp_cache_get( $cache_key );
21+
22+
// Return the cached value.
23+
if ( $cached ) {
24+
return $cached;
25+
}
26+
27+
// Do all the work to calculate the value.
28+
$value = a_whole_lotta_processing();
29+
30+
// Cache the value.
31+
wp_cache_set( $cache_key, $value );
32+
33+
return $value;
34+
}
35+
```
36+
37+
That pattern works well, but there's a lot of repeated code. This package draws inspiration from [Laravel's `Cache::remember()` method](https://laravel.com/docs/5.6/cache#cache-usage); using `Cache::remember()`, the same code from above becomes:
38+
39+
```php
40+
// Use this as a global variable or something.
41+
$cache = new \DuckDev\Cache\Cache();
42+
43+
function do_something() {
44+
return $cache->remember( 'some-cache-key', function () {
45+
return a_whole_lotta_processing();
46+
} );
47+
}
48+
```
49+
50+
## Installation
51+
52+
The recommended way to install this library in your project is [via Composer](https://getcomposer.org/):
53+
54+
```sh
55+
$ composer require duckdev/wp-cache-helper
56+
```
57+
58+
## Usage
59+
60+
WP Cache Remember provides the following functions for WordPress:
61+
62+
* [`$cache->remember()`](#$cache->remember())
63+
* [`$cache->forget()`](#$cache->forget())
64+
* [`$cache->persist()`](#$cache->persist())
65+
* [`$cache->cease()`](#$cache->cease())
66+
* [`$cache->flush_group()`](#$cache->flush_group())
67+
* [`$cache->flush()`](#$cache->flush())
68+
69+
Each function checks the response of the callback for a `WP_Error` object, ensuring you're not caching temporary errors for long periods of time. PHP Exceptions will also not be cached.
70+
71+
### $cache->remember()
72+
73+
Retrieve a value from the object cache. If it doesn't exist, run the `$callback` to generate and cache the value.
74+
75+
#### Parameters
76+
77+
<dl>
78+
<dt>(string) $key</dt>
79+
<dd>The cache key.</dd>
80+
<dt>(callable) $callback</dt>
81+
<dd>The callback used to generate and cache the value.</dd>
82+
<dt>(string) $group</dt>
83+
<dd>Optional. The cache group. Default is empty.</dd>
84+
<dt>(int) $expire</dt>
85+
<dd>Optional. The number of seconds before the cache entry should expire. Default is 0 (as long as possible).</dd>
86+
</dl>
87+
88+
#### Example
89+
90+
```php
91+
function get_latest_posts() {
92+
return $cache->remember( 'latest_posts', function () {
93+
return new WP_Query( array(
94+
'posts_per_page' => 5,
95+
'orderby' => 'post_date',
96+
'order' => 'desc',
97+
) );
98+
}, 'my-cache-group', HOUR_IN_SECONDS );
99+
}
100+
```
101+
102+
### $cache->forget()
103+
104+
Retrieve and subsequently delete a value from the object cache.
105+
106+
#### Parameters
107+
108+
<dl>
109+
<dt>(string) $key</dt>
110+
<dd>The cache key.</dd>
111+
<dt>(string) $group</dt>
112+
<dd>Optional. The cache group. Default is empty.</dd>
113+
<dt>(mixed) $default</dt>
114+
<dd>Optional. The default value to return if the given key doesn't exist in the object cache. Default is null.</dd>
115+
</dl>
116+
117+
#### Example
118+
119+
```php
120+
function show_error_message() {
121+
$error_message = $cache->forget( 'form_errors', 'my-cache-group', false );
122+
123+
if ( $error_message ) {
124+
echo 'An error occurred: ' . $error_message;
125+
}
126+
}
127+
```
128+
129+
### $cache->persist()
130+
131+
Retrieve a value from transients. If it doesn't exist, run the `$callback` to generate and cache the value.
132+
133+
#### Parameters
134+
135+
<dl>
136+
<dt>(string) $key</dt>
137+
<dd>The cache key.</dd>
138+
<dt>(callable) $callback</dt>
139+
<dd>The callback used to generate and cache the value.</dd>
140+
<dt>(string) $site</dt>
141+
<dd>Should use site transients.</dd>
142+
<dt>(int) $expire</dt>
143+
<dd>Optional. The number of seconds before the cache entry should expire. Default is 0 (as long as possible).</dd>
144+
</dl>
145+
146+
#### Example
147+
148+
```php
149+
function get_tweets() {
150+
$user_id = get_current_user_id();
151+
$key = 'latest_tweets_' . $user_id;
152+
153+
return $cache->persist( $key, function () use ( $user_id ) {
154+
return get_latest_tweets_for_user( $user_id );
155+
}, 15 * MINUTE_IN_SECONDS );
156+
}
157+
```
158+
159+
### $cache->cease()
160+
161+
Retrieve and subsequently delete a value from the transient cache.
162+
163+
#### Parameters
164+
165+
<dl>
166+
<dt>(string) $key</dt>
167+
<dd>The cache key.</dd>
168+
<dt>(string) $site</dt>
169+
<dd>Should use site transients.</dd>
170+
<dt>(mixed) $default</dt>
171+
<dd>Optional. The default value to return if the given key doesn't exist in transients. Default is null.</dd>
172+
</dl>
173+
174+
### $cache->flush_group()
175+
176+
Flush a cache group items. Use this and do not flush entire cache.
177+
178+
#### Parameters
179+
180+
<dl>
181+
<dt>(string) $group</dt>
182+
<dd>The cache group name.</dd>
183+
</dl>
184+
185+
### $cache->flush()
186+
187+
Wrapper for `wp_cache_flush` to check if other method is available for flushing if `wp_cache_flush` is disabled.
188+
189+
### Credits
190+
* Maintained by [Joel James](https://github.com/joel-james/)
191+
192+
### License
193+
194+
[GPLv2+](http://www.gnu.org/licenses/gpl-2.0.html)

‎composer.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "duckdev/wp-cache-helper",
3+
"description": "Helper class for the WordPress object cache and transients with group flush feature.",
4+
"license": "GPL-2.0-or-later",
5+
"type": "library",
6+
"authors": [
7+
{
8+
"name": "Joel James",
9+
"email": "[email protected]",
10+
"homepage": "https://duckdev.com"
11+
}
12+
],
13+
"keywords": [
14+
"wordpress",
15+
"cache",
16+
"object-cache",
17+
"transients"
18+
],
19+
"support": {
20+
"issues": "https://github.com/duckdev/wp-cache-helper/issues/"
21+
},
22+
"require": {
23+
"php": ">=5.6"
24+
},
25+
"autoload": {
26+
"psr-4": {
27+
"DuckDev\\Cache\\": "src"
28+
}
29+
},
30+
"minimum-stability": "dev"
31+
}

‎gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Dependencies
2+
/vendor
3+
4+
# Generated
5+
/tests/.tmp
6+
composer.lock

0 commit comments

Comments
 (0)