diff --git a/README.md b/README.md index 8321745..264c48d 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,59 @@ Assuming you have setup Composer's autoloader, FluentCache can be found in the ` ## Usage +The principal type that FluentCache provides is `CacheBuilder`. `CacheBuilder` is an immutable object that takes references to a cache and anonymous functions to generate a cache key, build cacheable objects, validate results, and hook an event dispatcher. + +`CacheBuilder` handles the responsibility for, and obfuscates, the steps required to orchestrate the most common scenario for handling cached data: + +* Check the cache for an object + * If miss, build an object, set it in the cache, and return the object + * If hit, return the object + +Managing these steps, choosing what to profile, when to validate, or other cache-specific decision making isn't the responsibility of the calling code: the caller just wants to _get_ an object, it shouldn't care if it comes from a cache, if the data is stale, or the object is built for the first time. `CacheBuilder` separates this concern and encapsulates it, exposing custom logic hooks for reasonable flexibility. + ```php +class Memcache implements \Psr\SimpleCache\CacheInterface {} + +class Dispatcher implements \Psr\EventDispatcher\EventDispatcherInterface {} + +$result = (new CacheBuilder()) + ->withCache(new Memcache(), function() : ?string { + + // generate a cache key - if null is returned, then the cache will be ignored + return 'foo'; + }) + ->withCacheLifespanBuilder(function($result) : int { + + // what is the ttl for objects set in the cache? + return 1500; + }) + ->withCacheValidator(function($result) : bool { + + // assert that cached object is valid when fetched + if(!($result instanceof Bar)) { + return false; + } + return $result->someProperty = 'some value'; + }); + ->withBuilder(function() : object { + + // build a cacheable object if cache miss + return new Bar(); + }) + ->withBuildValidator(function($result) : object { + + // assert that post-cache miss built object is valid + return $result instanceof Bar; + }) + + // send cache and build stage events to trigger downstream actions such as profiling + ->withEventDispatcher(new Dispatcher()) + + // ...or set a lazy dispatcher to initialize when we attempt to fetch an object + ->withLazyEventDispatcher(function(CacheBuilder $this) : EventDispatcherInterface { + return new Dispatcher(); + }) + // fetch object from cache or build it and set it in the cache - the caller doesn't care! + ->get(); ```