Skip to content

Commit 53b8dbb

Browse files
EriBlooEriBloo
committed
update readme
1 parent 1832a92 commit 53b8dbb

File tree

1 file changed

+261
-30
lines changed

1 file changed

+261
-30
lines changed

‎README.md

+261-30
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,80 @@
11
# Strongly typed cache objects
22

3-
[![Latest Version on Packagist](https://img.shields.io/packagist/v/19932449-eribloo/laravel-cache-objects.svg?style=flat-square)](https://packagist.org/packages/19932449-eribloo/laravel-cache-objects)
4-
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/19932449-eribloo/laravel-cache-objects/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/19932449-eribloo/laravel-cache-objects/actions?query=workflow%3Arun-tests+branch%3Amain)
5-
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/19932449-eribloo/laravel-cache-objects/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/19932449-eribloo/laravel-cache-objects/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
6-
[![Total Downloads](https://img.shields.io/packagist/dt/19932449-eribloo/laravel-cache-objects.svg?style=flat-square)](https://packagist.org/packages/19932449-eribloo/laravel-cache-objects)
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/eribloo/laravel-cache-objects.svg?style=flat-square)](https://packagist.org/packages/eribloo/laravel-cache-objects)
4+
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/eribloo/laravel-cache-objects/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/eribloo/laravel-cache-objects/actions?query=workflow%3Arun-tests+branch%3Amain)
5+
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/eribloo/laravel-cache-objects/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/eribloo/laravel-cache-objects/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
6+
[![Total Downloads](https://img.shields.io/packagist/dt/eribloo/laravel-cache-objects.svg?style=flat-square)](https://packagist.org/packages/eribloo/laravel-cache-objects)
77

8-
This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
8+
Introducing Laravel package that simplifies cache management by allowing you to encapsulate all details in one place. Improve your application cache maintanance with less raw strings and static typing.
99

10-
## Support us
10+
```php
11+
/**
12+
* @implements CacheObject<CarbonInterface>
13+
*
14+
* @method static self make(User $user)
15+
*/
16+
final readonly class SomeUserCache implements CacheObject
17+
{
18+
/** @use CacheObjectActions<CarbonInterface> */
19+
use CacheObjectActions;
20+
21+
public function __construct(
22+
public User $user,
23+
) {}
24+
25+
public function key(): StringKey
26+
{
27+
$id = $this->user->getKey();
28+
29+
return new StringKey("some-cache:$id");
30+
}
31+
32+
public function ttl(): CarbonInterval
33+
{
34+
return CarbonInterval::minutes(15));
35+
}
1136

12-
[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/laravel-cache-objects.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/laravel-cache-objects)
37+
/**
38+
* @return SerializeTransformer<CarbonInterface>
39+
*/
40+
public function transformer(): SerializeTransformer
41+
{
42+
return new SerializeTransformer();
43+
}
44+
}
45+
```
1346

14-
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
47+
## Table of contents
1548

16-
We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
49+
- [Installation](#installation)
50+
- [Usage](#usage)
51+
- [Creating](#creating)
52+
- [CacheObject](#cacheobject)
53+
- [CacheKey](#cachekey)
54+
- [StringKey](#stringkey)
55+
- [HashedKey](#hashedkey)
56+
- [Time-to-live](#time-to-live)
57+
- [CacheValueTransformer](#cachevaluetransformer)
58+
- [JsonTransformer](#jsontransformer)
59+
- [SerializeTransformer](#serializetransformer)
60+
- [EncryptedTransformer](#encryptedtransformer)
61+
- [GuardTransformer](#guardtransformer)
62+
- [Traits](#traits)
63+
- [CacheObjectActions](#cacheobjectactions)
64+
- [CacheObjectDriver](#cacheobjectdriver)
65+
- [CacheDriver](#cachedriver)
66+
- [Events](#events)
67+
- [CacheObjectStored](#cacheobjectstored)
68+
- [CacheObjectRetrieved](#cacheobjectretrieved)
69+
- [CacheObjectMissed](#cacheobjectmissed)
70+
- [CacheObjectDeleted](#cacheobjectdeleted)
71+
- [Extending](#extending)
72+
- [PHPStan](#phpstan)
73+
- [Testing](#testing)
74+
- [Changelog](#changelog)
75+
- [Contributing](#contributing)
76+
- [Credits](#credits)
77+
- [Licence](#license)
1778

1879
## Installation
1980

@@ -23,39 +84,213 @@ You can install the package via composer:
2384
composer require eribloo/laravel-cache-objects
2485
```
2586

26-
You can publish and run the migrations with:
87+
## Usage
88+
89+
### Creating
90+
91+
You can create basic Cache Object by running Artisan Command:
2792

2893
```bash
29-
php artisan vendor:publish --tag="laravel-cache-objects-migrations"
30-
php artisan migrate
94+
php artisan make:cache-object SomeCacheObject
3195
```
3296

33-
You can publish the config file with:
97+
this will create class implementing `EriBloo\CacheObjects\Contracts\CacheObject` in `app\Cache` directory with some defaults for you to configure.
3498

35-
```bash
36-
php artisan vendor:publish --tag="laravel-cache-objects-config"
99+
### CacheObject
100+
101+
`EriBloo\CacheObjects\Contracts\CacheObject` interface requires you to implement 3 methods:
102+
103+
```php
104+
public function key(): EriBloo\CacheObjects\Contracts\CacheKey;
105+
public function ttl(): Carbon\CarbonInterval;
106+
public function transformer(): EriBloo\CacheObjects\Contracts\CacheValueTransformer;
37107
```
38108

39-
This is the contents of the published config file:
109+
### CacheKey
110+
111+
CacheKey interface is a wrapper for Stringable interface responsible for preparing key for storage. Currently 2 options exist.
112+
113+
##### StringKey
114+
115+
Basic key that accepts string.
40116

41117
```php
42-
return [
43-
];
118+
public function key(): EriBloo\CacheObjects\ValueObjects\Keys\StringKey
119+
{
120+
return new StringKey(key: 'some-cache');
121+
}
44122
```
45123

46-
Optionally, you can publish the views using
124+
##### HashedKey
47125

48-
```bash
49-
php artisan vendor:publish --tag="laravel-cache-objects-views"
126+
Decorator for other keys that returns hashes key before storage. Accepts optional algorithm in constructor (`sha256` by default).
127+
128+
```php
129+
public function key(): EriBloo\CacheObjects\ValueObjects\Keys\HashedKey
130+
{
131+
return new HashedKey(
132+
key: new StringKey('some-cache'),
133+
algo: 'md5',
134+
);
135+
}
50136
```
51137

52-
## Usage
138+
### Time-to-live
139+
140+
Defined with `Carbon\CarbonInterval`. Values that resolve to 0 or less seconds are considered to be stored forever.
141+
142+
### CacheValueTransformer
143+
144+
Transformers are classes responsible for modifying values before storage and after retrieval.
145+
146+
##### JsonTransformer
147+
148+
Uses `json_encode` on save and `json_decode` on load. Accepts optional flags and depth in constructor.
149+
150+
```php
151+
public function transformer(): EriBloo\CacheObjects\ValueObjects\Values\JsonTransformer
152+
{
153+
return new JsonTransformer(
154+
loadFlags: JSON_INVALID_UTF8_SUBSTITUTE,
155+
saveFlags: JSON_UNESCAPED_UNICODE,
156+
depth: 256,
157+
);
158+
}
159+
```
160+
161+
##### SerializeTransformer
162+
163+
Transformer that uses PHP `serialize` on save and `unserialize` on load. Accepts optional `class-string[]|bool` in constructor to specify classes allowed for deserialization.
164+
165+
```php
166+
public function transformer(): EriBloo\CacheObjects\ValueObjects\Values\SerializeTransformer
167+
{
168+
return new SerializeTransformer(allowedClasses: [SomeClass::class]);
169+
}
170+
```
171+
172+
##### EncryptedTransformer
173+
174+
Decorator for other transformer that uses `Crypt::encryptString` on save and `Crypt::decryptString` on load.
175+
176+
```php
177+
public function transformer(): EriBloo\CacheObjects\ValueObjects\Values\EncryptedTransformer
178+
{
179+
return new EncryptedTransformer(
180+
transformer: new SerializeTransformer,
181+
);
182+
}
183+
```
184+
185+
##### GuardTransformer
186+
187+
Proxy for other transformer that doesn't modify values, but instead validates them before storage or after retrieval. This class accepts up to 2 closures that should throw an Exception when provided value is invalid.
188+
189+
```php
190+
public function transformer(): EriBloo\CacheObjects\ValueObjects\Values\GuardTransformer
191+
{
192+
return new GuardTransformer(
193+
transformer: new EncryptedTransformer(new SerializeTransformer),
194+
onSaveGuard: function (CarbonInterface $value) {
195+
if ($value->isPast()) {
196+
throw new UnexpectedValueException;
197+
}
198+
},
199+
onLoadGuard: null,
200+
);
201+
}
202+
```
203+
204+
### Traits
205+
206+
##### CacheObjectActions
207+
208+
Optional (but helpful) trait that adds usage methods:
209+
210+
```php
211+
public static function make(): static; // easier creation
212+
public function store(mixed $value): string; // put into storage, returns key stored in cache
213+
public function retrieve(): mixed; // get from storage
214+
public function delete(): bool; // remove from storage
215+
protected function resolveDriver(): CacheObjectDriver; // resolves to default driver from Service Provider, more below
216+
```
217+
218+
### CacheObjectDriver
219+
220+
This interface defines methods used for interacting with storage. Currently 1 class exists.
221+
222+
##### CacheDriver
223+
224+
This class is a default driver that accepts an instance of `Illuminate\Contracts\Cache\Store`. Binding defined in Service Provider resolves this to your default cache storage.
225+
226+
### Events
227+
228+
Default driver dispatches events:
229+
230+
##### CacheObjectStored
231+
232+
When object is put in storage.
53233

54234
```php
55-
$cacheObjects = new EriBloo\CacheObjects();
56-
echo $cacheObjects->echoPhrase('Hello, EriBloo!');
235+
final class CacheObjectStored
236+
{
237+
public function __construct(
238+
public CacheObject $cacheObject,
239+
public mixed $originalValue,
240+
public string $transformedValue,
241+
) {}
242+
}
57243
```
58244

245+
##### CacheObjectRetrieved
246+
247+
When object is retrieved from storage.
248+
249+
```php
250+
final class CacheObjectRetrieved
251+
{
252+
public function __construct(
253+
public CacheObject $cacheObject,
254+
public string $originalValue,
255+
public mixed $transformedValue,
256+
) {}
257+
}
258+
```
259+
260+
##### CacheObjectMissed
261+
262+
When cache object retrieval misses.
263+
264+
```php
265+
final class CacheObjectMissed
266+
{
267+
public function __construct(
268+
public CacheObject $cacheObject,
269+
) {}
270+
}
271+
```
272+
273+
##### CacheObjectDeleted
274+
275+
When cache object is removed from storage.
276+
277+
```php
278+
final class CacheObjectDeleted
279+
{
280+
public function __construct(
281+
public CacheObject $cacheObject,
282+
) {}
283+
}
284+
```
285+
286+
## Extending
287+
288+
I created this package with ease of configuration in mind so you can easly create `CacheKey`, `CacheValueTransformer` or `CacheObjectDriver` that will suit your needs. Additionally if you have any ideas of classes that could be incorporated into main package feel free to open an Issue or Pull Request.
289+
290+
## PHPStan
291+
292+
While I omited most of static typing in examples above for clarity, this package is developed with level 8 of PHPStan and parts of code that are working with `mixed` values (transformers, cache object interface and cache object action) are built with generics.
293+
59294
## Testing
60295

61296
```bash
@@ -68,15 +303,11 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
68303

69304
## Contributing
70305

71-
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
72-
73-
## Security Vulnerabilities
74-
75-
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
306+
All contributions are welcome.
76307

77308
## Credits
78309

79-
- [EriBloo](https://github.com/19932449+EriBloo)
310+
- [EriBloo](https://github.com/eribloo)
80311
- [All Contributors](../../contributors)
81312

82313
## License

0 commit comments

Comments
 (0)