From 89beaf783992b1ce64aec0eeaefc4b863a7d28cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 25 Feb 2016 19:39:48 +0100 Subject: [PATCH 1/5] Consistent formatting for examples --- README.md | 58 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b582385..4b1ee3f 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,11 @@ against the interface and third parties to provide alternate implementations. ## Basic usage ### get + ```php - $cache - ->get('foo') - ->then('var_dump'); +$cache + ->get('foo') + ->then('var_dump'); ``` This example fetches the value of the key `foo` and passes it to the @@ -24,8 +25,9 @@ This example fetches the value of the key `foo` and passes it to the If the key `foo` does not exist, the promise will be rejected. ### set + ```php - $cache->set('foo', 'bar'); +$cache->set('foo', 'bar'); ``` This example eventually sets the value of the key `foo` to `bar`. If it @@ -34,8 +36,9 @@ value is set. If the cache implementation has to go over the network to store it, it may take a while. ### remove + ```php - $cache->remove('foo'); +$cache->remove('foo'); ``` This example eventually removes the key `foo` from the cache. As with `set`, @@ -48,11 +51,12 @@ this may not happen instantly. A common use case of caches is to attempt fetching a cached value and as a fallback retrieve it from the original data source if not found. Here is an example of that: + ```php - $cache - ->get('foo') - ->then(null, 'getFooFromDb') - ->then('var_dump'); +$cache + ->get('foo') + ->then(null, 'getFooFromDb') + ->then('var_dump'); ``` First an attempt is made to retrieve the value of `foo`. A promise rejection @@ -68,25 +72,27 @@ chain will correctly fall back, and provide the value in both cases. To expand on the fallback get example, often you want to set the value on the cache after fetching it from the data source. + ```php - $cache +$cache + ->get('foo') + ->then(null, array($this, 'getAndCacheFooFromDb')) + ->then('var_dump'); + +public function getAndCacheFooFromDb() +{ + return $this->db ->get('foo') - ->then(null, array($this, 'getAndCacheFooFromDb')) - ->then('var_dump'); - - public function getAndCacheFooFromDb() - { - return $this->db - ->get('foo') - ->then(array($this, 'cacheFooFromDb')); - } - - public function cacheFooFromDb($foo) - { - $this->cache->set('foo', $foo); - - return $foo; - } + ->then(array($this, 'cacheFooFromDb')); +} + +public function cacheFooFromDb($foo) +{ + $this->cache->set('foo', $foo); + + return $foo; +} ``` + By using chaining you can easily conditionally cache the value if it is fetched from the database. From 40013c9a0104769049b2e3f6f8b8fd7ff7ff75e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 25 Feb 2016 19:41:42 +0100 Subject: [PATCH 2/5] Add TOC --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 4b1ee3f..2167115 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,16 @@ The cache component provides a promise-based cache interface and an in-memory `ArrayCache` implementation of that. This allows consumers to type hint against the interface and third parties to provide alternate implementations. +**Table of Contents** + +* [Basic usage](#basic-usage) + * [get](#get) + * [set](#set) + * [remove](#remove) +* [Common usage](#common-usage) + * [Fallback get](#fallback-get) + * [Fallback-get-and-set](#fallback-get-and-set) + ## Basic usage ### get From 9e288c67a6c56451ad6b2acd0f19565250a8fdcd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 25 Feb 2016 19:49:17 +0100 Subject: [PATCH 3/5] Documentation for CacheInterface and ArrayCache --- README.md | 42 +++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 2167115..65cf6a1 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,32 @@ Promised cache interface. -The cache component provides a promise-based cache interface and an in-memory -`ArrayCache` implementation of that. This allows consumers to type hint -against the interface and third parties to provide alternate implementations. +The cache component provides a promise-based [`CacheInterface`](#cacheinterface) +and an in-memory [`ArrayCache`](#arraycache) implementation of that. +This allows consumers to type hint against the interface and third parties to +provide alternate implementations. **Table of Contents** -* [Basic usage](#basic-usage) - * [get](#get) - * [set](#set) - * [remove](#remove) +* [Usage](#usage) + * [CacheInterface](#cacheinterface) + * [get()](#get) + * [set()](#set) + * [remove()](#remove) + * [ArrayCache](#arraycache) * [Common usage](#common-usage) * [Fallback get](#fallback-get) * [Fallback-get-and-set](#fallback-get-and-set) -## Basic usage +## Usage -### get +### CacheInterface + +The `CacheInterface` describes the main interface of this component. +This allows consumers to type hint against the interface and third parties to +provide alternate implementations. + +#### get() ```php $cache @@ -34,7 +43,7 @@ This example fetches the value of the key `foo` and passes it to the If the key `foo` does not exist, the promise will be rejected. -### set +#### set() ```php $cache->set('foo', 'bar'); @@ -45,7 +54,7 @@ already exists, it is overridden. No guarantees are made as to when the cache value is set. If the cache implementation has to go over the network to store it, it may take a while. -### remove +#### remove() ```php $cache->remove('foo'); @@ -54,6 +63,17 @@ $cache->remove('foo'); This example eventually removes the key `foo` from the cache. As with `set`, this may not happen instantly. +### ArrayCache + +The `ArrayCache` provides an in-memory implementation of the +[`CacheInterface`](#cacheinterface). + +```php +$cache = new ArrayCache(); + +$cache->set('foo', 'bar'); +``` + ## Common usage ### Fallback get From 4ec4671c91a726a297947e5f59e9e5c55aa64342 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 25 Feb 2016 19:51:30 +0100 Subject: [PATCH 4/5] Add installation and license instructions --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 65cf6a1..eeb08df 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ provide alternate implementations. * [Common usage](#common-usage) * [Fallback get](#fallback-get) * [Fallback-get-and-set](#fallback-get-and-set) +* [Install](#install) +* [License](#license) ## Usage @@ -126,3 +128,26 @@ public function cacheFooFromDb($foo) By using chaining you can easily conditionally cache the value if it is fetched from the database. + +## Install + +The recommended way to install this library is [through Composer](http://getcomposer.org). +[New to Composer?](http://getcomposer.org/doc/00-intro.md) + +This will install the latest supported version: + +```bash +$ composer require react/cache:~0.4.0 +``` + +If you care a lot about BC, you may also want to look into supporting legacy versions: + +```bash +$ composer require "react/cache:~0.4.0|~0.3.0" +``` + +More details and upgrade guides can be found in the [CHANGELOG](CHANGELOG.md). + +## License + +MIT, see [LICENSE file](LICENSE). From a79879b36cbf5f3d88714dac78105c4757a76093 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 25 Feb 2016 19:59:08 +0100 Subject: [PATCH 5/5] Add links to promise lib --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index eeb08df..c426e21 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,12 @@ [![Build Status](https://secure.travis-ci.org/reactphp/cache.png?branch=master)](http://travis-ci.org/reactphp/cache) [![Code Climate](https://codeclimate.com/github/reactphp/cache/badges/gpa.svg)](https://codeclimate.com/github/reactphp/cache) -Promised cache interface. +Async, [Promise](https://github.com/reactphp/promise)-based cache interface. -The cache component provides a promise-based [`CacheInterface`](#cacheinterface) -and an in-memory [`ArrayCache`](#arraycache) implementation of that. +The cache component provides a +[Promise](https://github.com/reactphp/promise)-based +[`CacheInterface`](#cacheinterface) and an in-memory [`ArrayCache`](#arraycache) +implementation of that. This allows consumers to type hint against the interface and third parties to provide alternate implementations.