Cache Standard Interface #17

wants to merge 71 commits into
PHP FIG member

Proposed is a set of interfaces for a basic cache system, as well as extensions that can be used to build upon it. The goal of this PSR is to allow developers to create cache-aware libraries that can be integrated into existing frameworks and systems without the need for custom development.

Conversation has occurred on the list with regards to this, but additional discussion and PR's is highly encouraged.

tedivm and others added some commits Feb 25, 2012
@tedivm tedivm Added initial outline and interfaces.
This is the initial outline of the caching proposal, including the
interfaces themselves (which are the most fleshed out part of this
being added to the repo at the moment).
@tedivm tedivm Added main interfaces to their own files
This will allow people to actually use the interfaces.
@tedivm tedivm Added the goal from the mailing list, as well as some formatting 4d4439d
@tedivm tedivm Corrected some encoding errors 6cca7ec
@tedivm tedivm Added CacheIterator and CacheIterator 30dc94b
@tedivm tedivm Added documentation to the CacheItem interface 76726c4
@tedivm tedivm Added additional comments to the CacheIterator, CacheFactory and Cach…
…eIteratorFactory interfaces.
@tedivm tedivm Updated the format and added new sections
Changed some of the formatting around, added the "Multiple" section.
@tedivm tedivm Continued expanding the documentation in the interfaces. 2fcfa12
@tedivm tedivm Changed the names of the various interface files to drop the leading …
…(redundant) "Cache".
@tedivm tedivm Continued with renaming by updating comments and classes. 1746dd3
@tedivm tedivm Cleaned up formatting and whitespace. de5c4ab
@tedivm tedivm Expanded the PSR-Cache proposal.
Extensively expanded the proposal. Added the new interfaces (with
comments), wrote out the introduction and data sections, and cleaned up
a lot of formatting.
@tedivm tedivm Corrected formatting on the data list. 8512cf8
@tedivm tedivm Updated the return value for Cache\Item->clear() function.
Clarified that the clear function should return true as long as the
item is not in the cache at the end of the call, regardless of whether
it was removed or never existed.
@tedivm tedivm Added the Stackable and TaggableItem files. 78d672a
@tedivm tedivm Expanded the PSR
Clarified acceptable keys, clarified that null should explicitly be
null, altered header names, added text for namespaces, added the
TaggableItem interface, and removed the driver interface.
@tedivm tedivm Merged the Factory and IteratorFactory classes into the Pool class.
By merging the two classes into one we create more of an environment
class, which makes certain extensions significantly easier to architect
@tedivm tedivm Added the TaggablePool, StackablePool and StackableItem class. Remove…
…d the Stackable class.
@tedivm tedivm Updated the PSR proposal to add Stacks and change formatting. 1a74675
@tedivm tedivm Cleanup and commenting.
Ran through and made sure all class names were correct and fixed some
misspellings. Cleaned up the interfaces a bit, and then brought their
new comments back into the main proposal.
@tedivm tedivm Finished an unfinished thought. 122fad1
@tedivm tedivm Removed the Cache\Iterator in favor of a standard Iterator 51cfce4
@tedivm tedivm Correcting encoding issues in the Pool.php file. 9294e14
@tedivm tedivm Removed the Cache\Iterator interfaces, properly named the Pool interf…
@tedivm tedivm General proofread and cleanup. eac632e
@maerlyn maerlyn php opening tags for syntax highlight cb1fc6d
@tedivm tedivm Merge pull request #1 from maerlyn/Cache
php opening tags for syntax highlight
@eriksencosta eriksencosta fixed typo c5687d9
@tedivm tedivm Merge pull request #2 from eriksencosta/patch-1
fixed typo
@tedivm tedivm Changed "empty" to "flush" to avoid using reserved words. 4e9aa61
@evert evert Added objectcache proposal a58f1d7
@evert evert Changed namespace to PSR 21c4d7c
@evert evert Added $ttl argument and renamed method names as per suggestions on the
mailing list.
@dragoonis dragoonis Proposing the exists() method to check existence in the cache. db8af8a
@evert evert Added 'clear' a8b417c
@evert evert Added Multiple interface, and renamed PSR\Cache to PSR\Cache\Base 163c054
@evert evert Note about unset 1fc77ea
@evert evert Added EmulateMultiple cache ff91e0b
@evert evert Replaced 'ttl' argument with an 'options' array. fddd759
@evert evert Removed clear() method. Removed $options argument from set functions,
and put the $ttl argument back in.

+1 to pretty much everything about this.

@ghost Unknown and 1 other commented on an outdated diff Mar 16, 2012
@@ -0,0 +1,311 @@
+## 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 lead 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.
ghost Mar 16, 2012

Could you please format this markdown file at around 80 characters?

tedivm Mar 16, 2012 PHP FIG member



I assume the "set" function referred here, is Item::set(). Please feel free to correct my understanding if that wouldn't be the case, I can see some problems if not though. Working on namespaces, I encounter the same question, and I'm specifying persistence as bound to Item::set() only.

PHP FIG member

That is correct- the basic idea is that until an item is actually set with a value then nothing about that item needs to be written.

norv and others added some commits May 28, 2012
@norv norv Typo. 07f78ac
@norv norv php tags in Extensions interfaces.
Signed-off-by: Norv <>
@tedivm tedivm Updated to clarify the types of data must be storable by the implemen…
…ting caching system.
@tedivm tedivm Updated the Stackable keys to have them start with a root slash.
This was brought up on the mailing list and seemed like a reasonable
idea. It also will make it easier for implementing libraries to use one
class for systems that use stackable and non-stackable components,
making it easier to segment the two pools (internal namespacing or
something) as there will *always* be a slash when Stackables are used.
@tedivm tedivm Merge pull request #6 from tedivm/cache_stacks
Updated the Stackable keys to have them start with a root slash.
@norv norv Clarification on Item::set() as the method binding to the underlying …

Added php tags.

Signed-off-by: Norv <>
@tedivm tedivm Merge pull request #7 from norv/Cache
Clarification on Item::set()
@tedivm tedivm Updated the names of the "get" functions to use "Item" instead of "Ca…

As discussed on the mailing list, there may be some confusion over the
"getCache" and "getCacheIterator" functions since there is no actual
cache object. By changing them to "getItem" and "getItemIterator" we
make it much more clear what is actually returned.
@tedivm tedivm Merge pull request #8 from tedivm/cache_naming
Updated the names of the "get" functions to use "Item" instead of "Cache"
@tedivm tedivm Corrected typos and spelling 9cc61f3
@mrclay mrclay commented on the diff Nov 8, 2012
+ *
+ * @param mixed $value
+ * @param int|DateInterval|DateTime $ttl
+ * @return bool
+ */
+ function set($value, $ttl = null);
+ /**
+ * Validates the current state of the item in the cache.
+ *
+ * An item is considered a miss when it does not exist or has passed its
+ * expiration.Implementing Library can define additional miss conditions.
+ *
+ * @return bool
+ */
+ function isMiss();
mrclay Nov 8, 2012

Almost all validators I've seen pass with a positive result, so I'd prefer to see this as isValid, isAvailable, etc.

mnapoli Nov 9, 2012 PHP FIG member

+1 : if (! isMiss) is less readable than if (! isAvailable) (avoid double negatives)

mrclay Nov 9, 2012

BTW I realize that you chose isMiss because most checks would be testing for a fail before regenerating the cached value, but I still think it looks funny in the interface.

dragoonis Dec 12, 2012

I'm in agreement here. The isValid() or isAvailable() are much closer to what I'd expect from the proposal. @tedivm can you please update your PR to make this a true check rather than a false check?

tedivm Dec 12, 2012 PHP FIG member

Is here a preference? I'm thinking "isValid" is better than "isAvailable".

Seldaek Dec 12, 2012

how about exists()?

tedivm Dec 12, 2012 PHP FIG member

I'm not a big fan of exists, as whether an item exists or is valid are really two separate questions. The "get" function may be able to return a value that exists, but is past it's ttl and therefore no longer valid, at which point the developers using the library needs to make a decision about what they'd like to do. In most cases they'll treat validity and existence as the same, but that won't always be the case.

Seldaek via email Dec 12, 2012
mnapoli Dec 12, 2012 PHP FIG member

IMO it shouldn't be possible to get a cache entry that expired.
Edit: I agree with @Seldaek

tedivm Dec 12, 2012 PHP FIG member

90% of the time you're right, but I don't think we should exclude the 10% time when it's reasonable. There are many, many cases where it's more valuable to use a stale value (presumably while another process is regenerating the proper value), rather than enter a stampede (aka the dog pile affect) or pause to wait for the value to return.

Keep in mind this isn't saying get has to return anything- it doesn't. What this is saying is that the option is there for a library to expand it's functionality within the scope of this proposal. If a library wants to have a "standard" Pool and Item class, but also wants an extended Item class that handles validation differently (such as by doing any of the following- ) then this standard should not get in their way.

@tedivm tedivm Removed Extensions from Proposal
The extensions were removed so the focus could be on the core standard.
Should this standard pass they'll be brought up for discussion and vote
on their own.
tedivm and others added some commits Feb 26, 2013
@tedivm tedivm Merge remote-tracking branch 'upstream/master' c4667ae
@tedivm tedivm Merge branch 'master' into Cache 9103460
@tedivm tedivm Removed old PSR
Accidentally tossed an old PSR in here when merging with the main
fig-standards branch.
@tedivm tedivm Removed Cache Extensions 6e23f63
@tedivm tedivm Changed the "isMiss" function to "isValid".
This was based off of Paul's suggestion in the mailing list, and tries
to make the function call more intuitive.
@tedivm tedivm Changed the "flush" function to "empty"
This change was made to provide clarity, as some libraries use "flush"
to mean "save changes" which is pretty much the opposite of what's
happening here.
@simensen simensen Added "Key Concepts" section to help explain naming conventions. 5a2976c
@tedivm tedivm Merge pull request #10 from simensen/description
Added "Key Concepts" section to help explain naming conventions.
@simensen simensen Value should be able to be set to null. 769cb23
@tedivm tedivm Merge pull request #12 from simensen/value-null
Value should be able to be set to null.
@simensen simensen Use clear instead of empty as empty is a reserved word. 6a105ff
@tedivm tedivm Merge pull request #13 from simensen/empty-to-clear
Use clear instead of empty as empty is a reserved word.

This proposal has been superseded by #96. Please continue discussion over on the mailing list topic.

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