diff --git a/README.md b/README.md index 3feef7f..11ece86 100644 --- a/README.md +++ b/README.md @@ -116,27 +116,30 @@ provide guarantees whether or not the item has been removed from cache. #### getMultiple() -The `getMultiple(iterable $keys, mixed $default = null): PromiseInterface` method can be used to +The `getMultiple(string[] $keys, mixed $default = null): PromiseInterface` method can be used to retrieve multiple cache items by their unique keys. -This method will resolve with the list of cached value on success or with the -given `$default` value when no item can be found or when an error occurs. +This method will resolve with an array of cached values on success or with the +given `$default` value when an item can not be found or when an error occurs. Similarly, an expired cache item (once the time-to-live is expired) is considered a cache miss. ```php -$cache - ->getMultiple(array('foo', 'bar')) - ->then('var_dump'); +$cache->getMultiple(array('name', 'age'))->then(function (array $values) { + $name = $values['name'] ?? 'User'; + $age = $values['age'] ?? 'n/a'; + + echo $name . ' is ' . $age . PHP_EOL; +}); ``` -This example fetches the list of value for `foo` and `bar` keys and passes it to the -`var_dump` function. You can use any of the composition provided by -[promises](https://github.com/reactphp/promise). +This example fetches the cache items for the `name` and `age` keys and +prints some example output. You can use any of the composition provided +by [promises](https://github.com/reactphp/promise). #### setMultiple() -The `setMultiple(iterable $values, ?float $ttl = null): PromiseInterface` method can be used to +The `setMultiple(array $values, ?float $ttl = null): PromiseInterface` method can be used to persist a set of key => value pairs in the cache, with an optional TTL. This method will resolve with `true` on success or `false` when an error @@ -158,7 +161,7 @@ and the key `bar` to `2`. If some of the keys already exist, they are overridden #### deleteMultiple() -The `setMultiple(iterable $keys): PromiseInterface` method can be used to +The `setMultiple(string[] $keys): PromiseInterface` method can be used to delete multiple cache items in a single operation. This method will resolve with `true` on success or `false` when an error diff --git a/src/ArrayCache.php b/src/ArrayCache.php index e3c14e5..81f25ef 100644 --- a/src/ArrayCache.php +++ b/src/ArrayCache.php @@ -115,7 +115,7 @@ public function delete($key) return Promise\resolve(true); } - public function getMultiple($keys, $default = null) + public function getMultiple(array $keys, $default = null) { $values = array(); @@ -126,7 +126,7 @@ public function getMultiple($keys, $default = null) return Promise\all($values); } - public function setMultiple($values, $ttl = null) + public function setMultiple(array $values, $ttl = null) { foreach ($values as $key => $value) { $this->set($key, $value, $ttl); @@ -135,7 +135,7 @@ public function setMultiple($values, $ttl = null) return Promise\resolve(true); } - public function deleteMultiple($keys) + public function deleteMultiple(array $keys) { foreach ($keys as $key) { unset($this->data[$key], $this->expires[$key]); diff --git a/src/CacheInterface.php b/src/CacheInterface.php index 76c3a6c..424149c 100644 --- a/src/CacheInterface.php +++ b/src/CacheInterface.php @@ -92,26 +92,29 @@ public function delete($key); /** * Retrieves multiple cache items by their unique keys. * - * This method will resolve with the list of cached value on success or with the - * given `$default` value when no item can be found or when an error occurs. + * This method will resolve with an array of cached values on success or with the + * given `$default` value when an item can not be found or when an error occurs. * Similarly, an expired cache item (once the time-to-live is expired) is * considered a cache miss. * * ```php - * $cache - * ->getMultiple(array('foo', 'bar')) - * ->then('var_dump'); + * $cache->getMultiple(array('name', 'age'))->then(function (array $values) { + * $name = $values['name'] ?? 'User'; + * $age = $values['age'] ?? 'n/a'; + * + * echo $name . ' is ' . $age . PHP_EOL; + * }); * ``` * - * This example fetches the list of value for `foo` and `bar` keys and passes it to the - * `var_dump` function. You can use any of the composition provided by - * [promises](https://github.com/reactphp/promise). + * This example fetches the cache items for the `name` and `age` keys and + * prints some example output. You can use any of the composition provided + * by [promises](https://github.com/reactphp/promise). * - * @param iterable $keys A list of keys that can obtained in a single operation. - * @param mixed $default Default value to return for keys that do not exist. - * @return PromiseInterface + * @param string[] $keys A list of keys that can obtained in a single operation. + * @param mixed $default Default value to return for keys that do not exist. + * @return PromiseInterface Returns a promise which resolves to an `array` of cached values */ - public function getMultiple($keys, $default = null); + public function getMultiple(array $keys, $default = null); /** * Persists a set of key => value pairs in the cache, with an optional TTL. @@ -133,24 +136,24 @@ public function getMultiple($keys, $default = null); * This example eventually sets the list of values - the key `foo` to 1 value * and the key `bar` to 2. If some of the keys already exist, they are overridden. * - * @param iterable $values A list of key => value pairs for a multiple-set operation. - * @param ?float $ttl Optional. The TTL value of this item. - * @return bool PromiseInterface Returns a promise which resolves to `true` on success or `false` on error + * @param array $values A list of key => value pairs for a multiple-set operation. + * @param ?float $ttl Optional. The TTL value of this item. + * @return PromiseInterface Returns a promise which resolves to `true` on success or `false` on error */ - public function setMultiple($values, $ttl = null); + public function setMultiple(array $values, $ttl = null); /** * Deletes multiple cache items in a single operation. * - * @param iterable $keys A list of string-based keys to be deleted. - * @return bool PromiseInterface Returns a promise which resolves to `true` on success or `false` on error + * @param string[] $keys A list of string-based keys to be deleted. + * @return PromiseInterface Returns a promise which resolves to `true` on success or `false` on error */ - public function deleteMultiple($keys); + public function deleteMultiple(array $keys); /** * Wipes clean the entire cache. * - * @return bool PromiseInterface Returns a promise which resolves to `true` on success or `false` on error + * @return PromiseInterface Returns a promise which resolves to `true` on success or `false` on error */ public function clear(); @@ -177,7 +180,7 @@ public function clear(); * another script can remove it making the state of your app out of date. * * @param string $key The cache item key. - * @return PromiseInterface Returns a promise which resolves to `true` on success or `false` on error + * @return PromiseInterface Returns a promise which resolves to `true` on success or `false` on error */ public function has($key); }