Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

PSR Cache Proposal #96

Closed
wants to merge 52 commits into from
@dragoonis
Owner

Quick Link: https://github.com/dragoonis/fig-standards/blob/master/proposed/psr-cache.md

note: the examples section in psr-cache.md will not be part of the official proposal, it is just here so that everything is under the one hood and to prove that the interfaces are solid.

@evert evert referenced this pull request
Closed

Proposal for an object cache #11

@bobthecow

This could probably use a rebase?

@staabm staabm commented on the diff
proposed/psr-cache.md
((125 lines not shown))
+namespace Psr\Cache;
+
+use Psr\Cache\CacheItemInterface;
+
+interface CacheInterface
+{
+
+ /**
+ * Here we pass in a cache key to be fetched from the cache.
+ * A CacheItem object will be constructed and returned to us
+ *
+ * @param string $key The unique key of this item in the cache
+ *
+ * @return CacheItemInterface The newly populated CacheItem class representing the stored data in the cache
+ */
+ public function get($key);
@staabm
staabm added a note

What do you think about a lazy method, which takes a $key and a Closure which would be invoked when no cached value is found.
This simplifies client code to something like

$cachedValue = $cache->lazy($key, function() {
  // impl whatever should be done on cache miss
  // the returned value will be set into the CacheItem
});

This also reduces the need for the always repeated cache pattern

$item = $cache->get($key);
If(!$item->isHit()) {
  // do stuff
  $item->set($key, $value);
} else {
  $value = $item->getValue();
}
@staabm
staabm added a note

So the implementation of the lazy method would look more or less like the pattern which is otherwise used all over the applications

@dragoonis Owner

@staab please bring up these discussions on our mailing list. https://groups.google.com/d/msg/php-fig/UkSWS48eEgo/cbchuV0mlEgJ

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@AmyStephen

Thinking that returning a $this for set, remove, getMultiple, removeMultiple, and clear is better than a true or false in that if the method fails, it should throw an exception and, for that reason, there will never be a false.

@ashnazg

That's a really good observation... I'd +1 that suggestion.

@Crell
Collaborator

I think Amy has been reading my blog... ;-)

@AmyStephen

lol, that is true @Crell -- and I am complying, /me goes to check her temperature.

@AmyStephen

(That comment was a reflection of my stubborn nature, nothing else!)

@flyboarder

:+1: for cache psr

@dragoonis
Owner
@AmyStephen

@dragoonis Please read my comment. It's pretty short. ;-) #96 (comment)

@jfsimon jfsimon referenced this pull request in symfony/symfony
Closed

[POC] Cache component #7986

14 of 18 tasks complete
@jfsimon

:+1: for the CacheInterface & CacheItemInterface and :+1: for @AmyStephen's suggestion about exceptions.
What about replacing isHit() by isCached()?

@philsturgeon
@jfsimon

@philsturgeon indeed, isHit() is maybe more understable. Have a good night ;)

@philsturgeon
proposed/psr-cache.md
((178 lines not shown))
+
+ /**
+ * Remove multiple cache items in a single operation
+ *
+ * @param array $keys The array of keys to be removed
+ *
+ * @return array An array of 'key' => result, elements. Each array row has the key being deleted
+ * and the result of that operation. The result will be a boolean of true or false
+ * representing if the cache item was removed or not
+ */
+ public function removeMultiple($keys);
+
+ /**
+ * This will wipe out the entire cache's keys
+ *
+ * @return boolean The result of the clear operation
@staabm
staabm added a note

Should this be more explicit? Somethink like Returns true on success and otherwise false?

@philsturgeon Owner

Agreed.

@staabm
staabm added a note

Same for set, setMultiple, remove

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
proposed/psr-cache.md
((130 lines not shown))
+ *
+ * @param string $key The unique key of this item in the cache
+ *
+ * @return CacheItemInterface The newly populated CacheItem class representing the stored data in the cache
+ */
+ public function get($key);
+
+ /**
+ * Persisting our data in the cache, uniquely referenced by a key with an optional expiration TTL time.
+ *
+ * @param string $key The key of the item to store
+ * @param mixed $value The value of the item to store
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
+ *
+ * @return boolean
@staabm
staabm added a note

Missing desc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@staabm staabm commented on the diff
proposed/psr-cache.md
((148 lines not shown))
+
+ /**
+ * Remove an item from the cache by its unique key
+ *
+ * @param string $key The unique cache key of the item to remove
+ *
+ * @return boolean The result of the delete operation
+ */
+ public function remove($key);
+
+ /**
+ * Obtain multiple CacheItems by their unique keys
+ *
+ * @param array $keys A list of keys that can obtained in a single operation.
+ *
+ * @return array An array of CacheItem classes.
@staabm
staabm added a note

Type should be CacheItemInterface[]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@staabm staabm commented on the diff
proposed/psr-cache.md
((156 lines not shown))
+ public function remove($key);
+
+ /**
+ * Obtain multiple CacheItems by their unique keys
+ *
+ * @param array $keys A list of keys that can obtained in a single operation.
+ *
+ * @return array An array of CacheItem classes.
+ * The resulting array must use the CacheItem's key as the associative key for the array.
+ */
+ public function getMultiple($keys);
+
+ /**
+ * Persisting a set of key => value pairs in the cache, with an optional TTL.
+ *
+ * @param array $items An array of key => value pairs for a multiple-set operation.
@staabm
staabm added a note

Should this also support CacheItemInterface[]?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@staabm staabm commented on the diff
proposed/psr-cache.md
((199 lines not shown))
+```
+
+### 2.3 CacheAwareInterface
+
+``` php
+<?php
+
+namespace Psr\Cache;
+
+interface CacheAwareInterface
+{
+ /**
+ * Sets a cache instance on the object
+ *
+ * @param CacheInterface $cache
+ * @return null
@staabm
staabm added a note

Should this setter support a fluid interface?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@empire

What about adding hasKey (or isKeyCached or isCached) to CacheInterfae for checking existence of key in cache?
How can we check some key in cache or not!? We must first call get and then based on result we can guess the cache exist.

  if ($item = $cache->get('some-key')) {
    $cache->remove('some-key');
  }

OR

  if ($cache->has('some-key')) {
    $cache->remove('some-key');
  }
@empire

removeMultiple can be implemented by remove, so, some implementations need to do it, adding AbstractCache will be useful for implementing some methods like removeMultiple.

@jfsimon jfsimon commented on the diff
proposed/psr-cache.md
((128 lines not shown))
+ * Here we pass in a cache key to be fetched from the cache.
+ * A CacheItem object will be constructed and returned to us
+ *
+ * @param string $key The unique key of this item in the cache
+ *
+ * @return CacheItemInterface The newly populated CacheItem class representing the stored data in the cache
+ */
+ public function get($key);
+
+ /**
+ * Persisting our data in the cache, uniquely referenced by a key with an optional expiration TTL time.
+ *
+ * @param string $key The key of the item to store
+ * @param mixed $value The value of the item to store
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
@jfsimon
jfsimon added a note

Maybe you shoud specify the unit for $ttl here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@AurelC2G AurelC2G commented on the diff
proposed/psr-cache.md
((171 lines not shown))
+ * @param array $items An array of key => value pairs for a multiple-set operation.
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
+ *
+ * @return boolean The result of the multiple-set operation
+ */
+ public function setMultiple($items, $ttl = null);
+
+ /**
+ * Remove multiple cache items in a single operation
+ *
+ * @param array $keys The array of keys to be removed
+ *
+ * @return array An array of 'key' => result, elements. Each array row has the key being deleted
+ * and the result of that operation. The result will be a boolean of true or false
+ * representing if the cache item was removed or not

Not really clear: what would be returned if the key was not in cache? false because it could not be removed? true because after the call to remove(), the key is still not in cache?
Same for remove().

@dragoonis Owner

If you were setting foo, bar, baz. then the result would be something like this

array(
    'foo' => true,
    'bar' => false,
    'baz' => true
);

In this case it is remove, not set. What is returned if you try to remove an item that is not in cache? The spec is not clear about this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@noah-goodrich

One question I have looking at the proposal is why increment() has been omitted when a number of caching engines provide native support for incrementing a value?

If increment() isn't part of the standard, what should be the de facto way of mimicking increment functionality when consuming a library that implements this standard?

@AmyStephen
@bobthecow

What Amy said. And if it turns out that a lot of libraries implement increment() in addition to the PSR Cache interface, then a new Cache PSR can extend the current one by adding increment() (and whatever other commonalities emerge).

@philsturgeon
@noah-goodrich

@AmyStephen and @bobthecow

I maintain a stand-alone Data Mapper that utilizes the increment() functionality in memcache. I'm looking at the standard from the viewpoint of a library that will consume PSR\Cache implementations as drop-in replacements without requiring customization.

This standard doesn't do much good if everyone who uses my Data Mapper library has to customize their chosen Cache library. As such, I wonder what the standard will be for libraries that use a cache library implementing this standard if increment() is a required function?

@AmyStephen
@AmyStephen
@noah-goodrich

@AmyStephen

https://github.com/energylab/gacela/blob/master/library/Gacela/Gacela.php

The important bits are the enableCache(), _cache() and incrementDataCache() methods.

Originally this was all written to just use the Memcache library, but I'm looking at this PSR as a way to allow someone using Gacela as their Data Mapper to drop in any Cache library and just run with it.

Right now if you look at my docs, the requirements for enabling a cache are as follows:

Gacela will use any caching library that supports get(), set(), and increment()

With this PSR as an available standard, my requirement would become any caching library that supports the PSR-Cache standard. Make sense?

As for the keys, the singleton cache instance is used in the DataSource\Adapters to store metadata for the specific data source. Or in the Mapper\Mapper class if caching is enabled for a concrete mapper class. In both cases the keys are basically hashes implemented within the context of the framework and the developer never interacts directly with the cache.

@AmyStephen

@noah-goodrich As an FYI, if you want to look at one, here's my Cache Adapter/Handlers with the draft PSR Interfaces https://github.com/Molajo/cache - you are right, if increment is a critical feature of your application, the PSR would not be enough.

You probably should request the addition in this thread https://groups.google.com/forum/#!topic/php-fig/lANQM7LPX_M - Although I'm not sure if that will help or not, the project is in a weird spot.

If it doesn't get included, you can work with developer(s) providing the library, ask them to add increment, I wouldn't have a problem adding that if it helps. Or you can fork their library, do it yourself and include it. We're going to have to collaborate while these PSR's get rolling.

@jfsimon

I think increment() should be part of the interface too.

If I build a library based on the cache and I use PSR/Cache, I will only rely on the interface for interoperability. If I have to increment/decrement interger value I will have to reimplment these methods with get() + set(). It's a performance issue (2 requests instead of 1). Caching is all about performance.

Of course, interface is the "minimal contract" of the backend which could implement these methods, but if I have to check if backend class supports or not incrementing, the interface does not fulfill its role.

Furthemore, calling increment() with a negative argument looks really weird to me, so I think decrement() should be part of the interface too.

@Crell
Collaborator

Once again, this discussion belongs on the FIG list, not in a GitHub thread where most people won't see it. We're discussing the cache PSR there now anyway, so this is the time to bring it up.

@jfsimon

@Crell sorry.

@empire

@AmyStephen , @jfsimon @noah-goodrich I think we can have some other interfaces for making increment happen, some thing like following

inteface IncrementableItemInteface 
{
    public function increment($value = 1);
}

And then, for some cache engine, we can have CacheItem class that implements IncrementableItemInteface, we can check just by instance-of

   public function workOnSomeItem(CacheItem $cacheItem)
   {
       if ($cacheItem instanceof IncrementableItemInteface) {
             $cacheItem->increment(123);
       }
    }
@jfsimon

@empire you should publish your response on the mailing list: https://groups.google.com/forum/#!topic/php-fig/lANQM7LPX_M ;)

@empire

@jfsimon thanks, I post it.
In hope that will be useful.

@moisadoru moisadoru commented on the diff
proposed/psr-cache.md
((110 lines not shown))
+```
+
+### 2.2 CacheInterface
+
+This is the base interface class that developers should be looking to begin with. It provised provides the most basic functionality imaginable by a cache server which entails basic reading, writing and deleting of cache items.
+It will provide a generic API for library developers to allow applications to communicate to all popular cache backends.
+
+```php
+
+<?php
+
+namespace Psr\Cache;
+
+use Psr\Cache\ItemInterface;
+
+interface CacheInterface

I think a better suited name for this interface would be Psr\Cache\SingleAccessStore (or something similar), to clearly denote the fact that you can only get/set single items.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@moisadoru moisadoru commented on the diff
proposed/psr-cache.md
((155 lines not shown))
+ * @return boolean Returns true on success and otherwise false
+ */
+ public function remove($key);
+
+ /**
+ * This will wipe out the entire cache's keys
+ *
+ * @return boolean Returns true on success and otherwise false
+ */
+ public function clear();
+
+}
+
+```
+
+### 2.3 MultipleInterface

I think a better suited name for this interface would be Psr\Cache\MultipleAccessStore (or something similar), to clearly denote the fact that you can access multiple items in a single call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@moisadoru moisadoru commented on the diff
proposed/psr-cache.md
((187 lines not shown))
+ *
+ * @return array An array of CacheItem classes.
+ * The resulting array must use the CacheItem's key as the associative key for the array.
+ */
+ public function getMultiple($keys);
+
+ /**
+ * Persisting a set of key => value pairs in the cache, with an optional TTL.
+ *
+ * @param array $items An array of key => value pairs for a multiple-set operation.
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
+ *
+ * @return boolean The result of the multiple-set operation
+ */
+ public function setMultiple($items, $ttl = null);

How does one set individual TTLs for $items ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@moisadoru moisadoru commented on the diff
proposed/psr-cache.md
((205 lines not shown))
+ * Remove multiple cache items in a single operation
+ *
+ * @param array $keys The array of keys to be removed
+ *
+ * @return array An array of 'key' => result, elements. Each array row has the key being deleted
+ * and the result of that operation. The result will be a boolean of true or false
+ * representing if the cache item was removed or not
+ */
+ public function removeMultiple($keys);
+
+}
+```
+
+### 2.4 IncrementableInterface
+
+This interface provides the ability to increment and decrement cache entries by their specified value. Some cache backends support this natively so that you don't have to read the item and then increment it and write it back to the cache server, this can be done in a single call to the cache server since it's natively supported by many modern cache servers.

What is the behavior when trying to increment/decrement an entry that is not numeric?
Ex:

$cache->set('foo', 'bar');
// ... later in the code:
$cache->increment('foo', 1);
// or
$cache->decrement('foo', 1);
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@dragoonis
Owner

Closing this PR.

@dragoonis dragoonis closed this
@Alan01252

Just out of curiosity any reason why this was closed? I personally think this would be a useful standard.

@philsturgeon

This specific PR has been closed to make way for #149

@dave1010

This gist looks like APC, not Memcached. Do you have a Memcached version?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Mar 5, 2013
  1. @dragoonis

    Adding Psr\Cache proposal

    dragoonis authored
  2. @dragoonis

    Adding intro

    dragoonis authored
  3. @dragoonis

    Adding intro

    dragoonis authored
  4. @dragoonis

    Adding intro

    dragoonis authored
  5. @dragoonis

    Header size mod

    dragoonis authored
  6. @dragoonis

    Headers changes

    dragoonis authored
  7. @dragoonis

    Adding credits

    dragoonis authored
  8. @dragoonis

    Adding credits

    dragoonis authored
  9. @dragoonis

    Adding credits

    dragoonis authored
  10. @dragoonis

    Removing Cache->setItems()

    dragoonis authored
  11. @dragoonis
  12. @dragoonis
Commits on Mar 7, 2013
  1. @dragoonis

    Update psr-cache.md

    dragoonis authored
  2. @dragoonis

    Update psr-cache.md

    dragoonis authored
  3. @dragoonis

    Update psr-cache.md

    dragoonis authored
  4. @simensen
Commits on Mar 8, 2013
  1. @dragoonis

    Empty() method to clear()

    dragoonis authored
  2. @dragoonis

    Merge pull request #1 from simensen/docblock

    dragoonis authored
    setItems does not accept CacheItem objects.
  3. @dragoonis

    Adding memcached example

    dragoonis authored
  4. @dragoonis

    Adding APC example

    dragoonis authored
  5. @dragoonis

    Update psr-cache.md

    dragoonis authored
  6. @dragoonis

    Updating memcached link

    dragoonis authored
  7. @dragoonis

    Update psr-cache.md

    dragoonis authored
  8. @dragoonis
Commits on Mar 10, 2013
  1. @dragoonis
Commits on Mar 11, 2013
  1. @dragoonis
  2. @dragoonis
Commits on Mar 12, 2013
  1. @ashnazg

    Update psr-cache.md

    ashnazg authored
    Typo-ish edits
  2. @dragoonis

    Merge pull request #2 from ashnazg/patch-1

    dragoonis authored
    Update psr-cache.md
  3. @dragoonis

    Updating docblocks

    dragoonis authored
  4. @dragoonis

    Docblock updates.

    dragoonis authored
Commits on Mar 13, 2013
  1. @dragoonis

    Changing val param to value.

    dragoonis authored
  2. @dragoonis
  3. @dragoonis
  4. @dragoonis
Commits on Mar 14, 2013
  1. @dragoonis

    Textual updates from @Crell

    dragoonis authored
Commits on Mar 26, 2013
  1. @dragoonis

    Adding CacheAwareInterface

    dragoonis authored
Commits on Apr 22, 2013
  1. @dragoonis
  2. @dragoonis

    Updating keys definition

    dragoonis authored
  3. @dragoonis

    Updating definitions list

    dragoonis authored
Commits on May 24, 2013
  1. @dragoonis

    Update psr-cache.md

    dragoonis authored
  2. @dragoonis
  3. @dragoonis

    Cache to CacheInterface

    dragoonis authored
  4. @dragoonis

    PHP Syntax highlighting

    dragoonis authored
  5. @dragoonis

    set() docblock updates

    dragoonis authored
Commits on May 25, 2013
  1. @dragoonis
Commits on May 27, 2013
  1. @dragoonis

    Class name changes.

    dragoonis authored
  2. @dragoonis

    Adding IncrementableCache

    dragoonis authored
  3. @dragoonis
  4. @dragoonis

    CacheInterface texts.

    dragoonis authored
  5. @dragoonis

    CacheAwareInterface Texts

    dragoonis authored
Commits on May 31, 2013
  1. @dragoonis

    Wording updates.

    dragoonis authored
This page is out of date. Refresh to see the latest.
Showing with 288 additions and 0 deletions.
  1. +288 −0 proposed/psr-cache.md
View
288 proposed/psr-cache.md
@@ -0,0 +1,288 @@
+Common Interface for Caching libraries
+================
+
+This document describes a simple yet extensible interface for a cache item and
+a cache driver.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119][].
+
+The final implementations MAY be able to decorate the objects with more
+functionality than the one proposed but they MUST implement the indicated
+interfaces/functionality first.
+
+[RFC 2119]: http://tools.ietf.org/html/rfc2119
+
+1. Specification
+-----------------
+
+## 1.1 Introduction
+
+Caching is a common way to improve the performance of any project, making
+caching libraries one of the most common features of many frameworks and
+libraries. This has led to a situation where many libraries roll their own
+caching libraries, with various levels of functionality. These differences are
+causing developers to have to learn multiple systems which may or may not
+provide the functionality they need. In addition, the developers of caching
+libraries themselves face a choice between only supporting a limited number
+of frameworks or creating a large number of adapter classes.
+
+A common interface for caching systems will solve these problems. Library and
+framework developers can count on the caching systems working the way they're
+expecting, while the developers of caching systems will only have to implement
+a single set of interfaces rather than a whole assortment of adapters.
+
+### 1.2 Definitions
+
+* **TTL** - The Time To Live (TTL) of an item is the amount of time between
+when that item is stored and it is considered stale. The TTL is normally defined
+by an integer representing time in seconds.
+
+* **Expiration** - The actual time when an item is set to go stale.
+
+ An item with a 300 second TTL stored at 1:30:00 will have an expiration at
+ 1:35:00.
+
+* **Key** - A string that uniquely identifies the cached item.
+
+* **CacheItem** - An object that implements the `Psr\Cache\ItemInterface` interface.
+
+* **Cache** - An object that implements the `Psr\Cache\CacheInterface` interface.
+
+
+### 1.3 Cache
+
+Implementations MAY provide a mechanism for a user to specify a default TTL
+if one is not specified for a specific cache item. If no user-specified default
+is provided implementations MUST default to the maximum legal value allowed by
+the underlying implementation. If the underlying implementation does not
+support TTL, the user-specified TTL MUST be silently ignored.
+
+If your implementation is expected to work accross many different platforms then
+it is recommended to have your cache keys consist of no more than 32 ASCII characters
+ or the following symbols. ``,._-``
+
+2. Interfaces
+-------------
+
+### 2.1 ItemInterface
+
+By using the `CacheItem` class implementations can guarantee consistency across
+various systems.
+
+The `CacheItem` objects are generated by the `Cache` class. `CacheItem` objects
+encapsulate the key and value of the stored cache entry. `CacheItem` objects
+SHOULD NOT be created in any other way.
+
+```php
+
+<?php
+
+namespace Psr\Cache;
+
+interface ItemInterface
+{
+
+ /**
+ * Get the key associated with this CacheItem
+ *
+ * @return string
+ */
+ public function getKey();
+
+ /**
+ * Obtain the value of this cache item
+ *
+ * @return mixed
+ */
+ public function getValue();
+
+ /**
+ * This boolean value tells us if our cache item is currently in the cache or not
+ *
+ * @return boolean
+ */
+ public function isHit();
+
+}
+
+```
+
+### 2.2 CacheInterface
+
+This is the base interface class that developers should be looking to begin with. It provised provides the most basic functionality imaginable by a cache server which entails basic reading, writing and deleting of cache items.
+It will provide a generic API for library developers to allow applications to communicate to all popular cache backends.
+
+```php
+
+<?php
+
+namespace Psr\Cache;
+
+use Psr\Cache\ItemInterface;
+
+interface CacheInterface

I think a better suited name for this interface would be Psr\Cache\SingleAccessStore (or something similar), to clearly denote the fact that you can only get/set single items.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+{
+
+ /**
+ * Here we pass in a cache key to be fetched from the cache.
+ * A CacheItem object will be constructed and returned to us
+ *
+ * @param string $key The unique key of this item in the cache
+ *
+ * @return CacheItemInterface The newly populated CacheItem class representing the stored data in the cache
+ */
+ public function get($key);
@staabm
staabm added a note

What do you think about a lazy method, which takes a $key and a Closure which would be invoked when no cached value is found.
This simplifies client code to something like

$cachedValue = $cache->lazy($key, function() {
  // impl whatever should be done on cache miss
  // the returned value will be set into the CacheItem
});

This also reduces the need for the always repeated cache pattern

$item = $cache->get($key);
If(!$item->isHit()) {
  // do stuff
  $item->set($key, $value);
} else {
  $value = $item->getValue();
}
@staabm
staabm added a note

So the implementation of the lazy method would look more or less like the pattern which is otherwise used all over the applications

@dragoonis Owner

@staab please bring up these discussions on our mailing list. https://groups.google.com/d/msg/php-fig/UkSWS48eEgo/cbchuV0mlEgJ

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+ /**
+ * Persisting our data in the cache, uniquely referenced by a key with an optional expiration TTL time.
+ *
+ * @param string $key The key of the item to store
+ * @param mixed $value The value of the item to store
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
@jfsimon
jfsimon added a note

Maybe you shoud specify the unit for $ttl here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ *
+ * @return boolean True on success and false otherwise
+ */
+ public function set($key, $value, $ttl = null);
+
+ /**
+ * Remove an item from the cache by its unique key
+ *
+ * @param string $key The unique cache key of the item to remove
+ *
+ * @return boolean Returns true on success and otherwise false
+ */
+ public function remove($key);
+
+ /**
+ * This will wipe out the entire cache's keys
+ *
+ * @return boolean Returns true on success and otherwise false
+ */
+ public function clear();
+
+}
+
+```
+
+### 2.3 MultipleInterface

I think a better suited name for this interface would be Psr\Cache\MultipleAccessStore (or something similar), to clearly denote the fact that you can access multiple items in a single call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+This interface has methods for dealing with multiple sets of cache entries such as writing, reading or deleting multiple cache entries at a time. This is really useful when you have lots of cache reads/writes to perform then you can perform your operations in a single call to the cache server cutting down latency times dramatically.
+
+```php
+
+<?php
+
+namespace Psr\Cache;
+
+interface MultipleInterface
+{
+
+ /**
+ * Obtain multiple CacheItems by their unique keys
+ *
+ * @param array $keys A list of keys that can obtained in a single operation.
+ *
+ * @return array An array of CacheItem classes.
@staabm
staabm added a note

Type should be CacheItemInterface[]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ * The resulting array must use the CacheItem's key as the associative key for the array.
+ */
+ public function getMultiple($keys);
+
+ /**
+ * Persisting a set of key => value pairs in the cache, with an optional TTL.
+ *
+ * @param array $items An array of key => value pairs for a multiple-set operation.
@staabm
staabm added a note

Should this also support CacheItemInterface[]?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ * @param null|integer $ttl Optional. The TTL value of this item. If no value is sent and the driver supports TTL
+ * then the library may set a default value for it or let the driver take care of that.
+ *
+ * @return boolean The result of the multiple-set operation
+ */
+ public function setMultiple($items, $ttl = null);

How does one set individual TTLs for $items ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+ /**
+ * Remove multiple cache items in a single operation
+ *
+ * @param array $keys The array of keys to be removed
+ *
+ * @return array An array of 'key' => result, elements. Each array row has the key being deleted
+ * and the result of that operation. The result will be a boolean of true or false
+ * representing if the cache item was removed or not

Not really clear: what would be returned if the key was not in cache? false because it could not be removed? true because after the call to remove(), the key is still not in cache?
Same for remove().

@dragoonis Owner

If you were setting foo, bar, baz. then the result would be something like this

array(
    'foo' => true,
    'bar' => false,
    'baz' => true
);

In this case it is remove, not set. What is returned if you try to remove an item that is not in cache? The spec is not clear about this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
+ public function removeMultiple($keys);
+
+}
+```
+
+### 2.4 IncrementableInterface
+
+This interface provides the ability to increment and decrement cache entries by their specified value. Some cache backends support this natively so that you don't have to read the item and then increment it and write it back to the cache server, this can be done in a single call to the cache server since it's natively supported by many modern cache servers.

What is the behavior when trying to increment/decrement an entry that is not numeric?
Ex:

$cache->set('foo', 'bar');
// ... later in the code:
$cache->increment('foo', 1);
// or
$cache->decrement('foo', 1);
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+```php
+
+<?php
+
+namespace Psr\Cache;
+
+interface IncrementableInterface
+{
+
+ /**
+ * Increment a value in the cache by its step value, which defaults to 1
+ *
+ * @param string $key The cache item key
+ * @param integer $step The value to increment by, defaulting to 1
+ *
+ * @return boolean True on success and false on failure
+ */
+ public function increment($key, $step = 1);
+
+ /**
+ * Decrement a value in the cache by its step value, which defaults to 1
+ *
+ * @param string $key The cache item key
+ * @param integer $step The value to decrement by, defaulting to 1
+ *
+ * @return boolean True on success and false on failure
+ */
+ public function decrement($key, $step = 1);
+
+}
+```
+
+### 2.5 CacheAwareInterface
+
+This class allows any generic PHP class to become ``cache aware``. This means it can be used to detect if an instance knows about PSR\Cache and can have PSR\Cache instances injected into it the ``setCache`` method
+
+``` php
+<?php
+
+namespace Psr\Cache;
+
+interface CacheAwareInterface
+{
+ /**
+ * Sets a cache instance on the object
+ *
+ * @param CacheInterface $cache
+ * @return null
@staabm
staabm added a note

Should this setter support a fluid interface?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ */
+ public function setCache(CacheInterface $cache);
+}
+```
+
+3. Package
+----------
+
+The interfaces described as well as a test suite to verify your implementation
+are provided as part of the [psr/cache](https://packagist.org/packages/psr/cache) package.
+
+4. Credits
+----------
+
+Parts of this proposal is the result of many months of deliberation, team work and proposals which can be referenced here:
+
+ * https://github.com/tedivm/fig-standards/blob/Cache/proposed/PSR-Cache.md
+ * https://github.com/evert/fig-standards/blob/master/proposed/objectcache.md
+ * https://github.com/dlsniper/fig-standards/blob/cache-proposal/proposed/psr-cache.md
Something went wrong with that request. Please try again.