Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Cache Standard Interface #17

Closed
wants to merge 71 commits into from
@tedivm

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
@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).
9b1a7f5
@tedivm tedivm Added main interfaces to their own files
This will allow people to actually use the interfaces.
9e59ee3
@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.
46a9bf9
@tedivm tedivm Updated the format and added new sections
Changed some of the formatting around, added the "Multiple" section.
33d21d0
@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".
3f9bdec
@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.
4207195
@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.
1c26c13
@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.
1adcb18
@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
simply.
5fcba25
@tedivm tedivm Added the TaggablePool, StackablePool and StackableItem class. Remove…
…d the Stackable class.
72de566
@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.
7f75ef9
@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…
…aces
b3065ea
@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
3b0ece6
@eriksencosta eriksencosta fixed typo c5687d9
@tedivm tedivm Merge pull request #2 from eriksencosta/patch-1
fixed typo
5cf932e
@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.
abd1ac8
@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.
10ec8ad
@nateabele

+1 to pretty much everything about this.

@ghost Show outdated diff Hide outdated diff Unknown commented on an outdated diff
proposed/PSR-Cache.md
@@ -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
ghost added a note

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

@tedivm
tedivm added a note

Done.

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

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.

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
@norv norv Typo. 07f78ac
@norv norv php tags in Extensions interfaces.
Signed-off-by: Norv <norv@simplemachines.org>
74acb75
@tedivm tedivm Updated to clarify the types of data must be storable by the implemen…
…ting caching system.
ccc0d8c
@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.
1f80b40
@tedivm tedivm Merge pull request #6 from tedivm/cache_stacks
Updated the Stackable keys to have them start with a root slash.
1581579
@norv norv Clarification on Item::set() as the method binding to the underlying …
…system.

Added php tags.

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

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.
c60a371
@tedivm tedivm Merge pull request #8 from tedivm/cache_naming
Updated the names of the "get" functions to use "Item" instead of "Cache"
0d5703c
@tedivm tedivm Corrected typos and spelling 9cc61f3
@mrclay mrclay commented on the diff
proposed/PSR/Cache/Item.php
((54 lines not shown))
+ *
+ * @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
mrclay added a note

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

@mnapoli
mnapoli added a note

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

@mrclay
mrclay added a note

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 Owner

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
tedivm added a note

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

@Seldaek
Seldaek added a note

how about exists()?

@tedivm
tedivm added a note

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
Seldaek added a note
@mnapoli
mnapoli added a note

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

@tedivm
tedivm added a note

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- http://stash.tedivm.com/Invalidation.html ) then this standard should not get in their way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@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.
bca9603
tedivm and others added some commits
@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.
033e4bf
@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.
a62272c
@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.
4fd2505
@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.
648d59f
@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.
361bb8d
@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.
607d979
@philsturgeon

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
Commits on Feb 25, 2012
  1. @tedivm

    Added initial outline and interfaces.

    tedivm authored
    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).
  2. @tedivm

    Added main interfaces to their own files

    tedivm authored
    This will allow people to actually use the interfaces.
  3. @tedivm
Commits on Feb 26, 2012
  1. @tedivm

    Corrected some encoding errors

    tedivm authored
  2. @tedivm
Commits on Feb 27, 2012
  1. @tedivm
  2. @tedivm

    Added additional comments to the CacheIterator, CacheFactory and Cach…

    tedivm authored
    …eIteratorFactory interfaces.
  3. @tedivm

    Updated the format and added new sections

    tedivm authored
    Changed some of the formatting around, added the "Multiple" section.
  4. @tedivm
  5. @tedivm
  6. @tedivm
  7. @tedivm
  8. @tedivm

    Expanded the PSR-Cache proposal.

    tedivm authored
    Extensively expanded the proposal. Added the new interfaces (with
    comments), wrote out the introduction and data sections, and cleaned up
    a lot of formatting.
  9. @tedivm
Commits on Feb 28, 2012
  1. @tedivm

    Updated the return value for Cache\Item->clear() function.

    tedivm authored
    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.
  2. @tedivm
  3. @tedivm

    Expanded the PSR

    tedivm authored
    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.
  4. @tedivm

    Merged the Factory and IteratorFactory classes into the Pool class.

    tedivm authored
    By merging the two classes into one we create more of an environment
    class, which makes certain extensions significantly easier to architect
    simply.
  5. @tedivm
  6. @tedivm
  7. @tedivm

    Cleanup and commenting.

    tedivm authored
    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.
  8. @tedivm

    Finished an unfinished thought.

    tedivm authored
  9. @tedivm
Commits on Feb 29, 2012
  1. @tedivm
  2. @tedivm
  3. @tedivm

    General proofread and cleanup.

    tedivm authored
  4. @maerlyn
  5. @tedivm

    Merge pull request #1 from maerlyn/Cache

    tedivm authored
    php opening tags for syntax highlight
Commits on Mar 2, 2012
  1. @eriksencosta

    fixed typo

    eriksencosta authored
  2. @tedivm

    Merge pull request #2 from eriksencosta/patch-1

    tedivm authored
    fixed typo
  3. @tedivm
Commits on Mar 3, 2012
  1. @evert @tedivm

    Added objectcache proposal

    evert authored tedivm committed
  2. @evert @tedivm

    Changed namespace to PSR

    evert authored tedivm committed
  3. @evert @tedivm

    Added $ttl argument and renamed method names as per suggestions on the

    evert authored tedivm committed
    mailing list.
  4. @dragoonis @tedivm
  5. @evert @tedivm

    Added 'clear'

    evert authored tedivm committed
  6. @evert @tedivm
  7. @evert @tedivm

    Note about unset

    evert authored tedivm committed
  8. @evert @tedivm

    Added EmulateMultiple cache

    evert authored tedivm committed
  9. @evert @tedivm

    Replaced 'ttl' argument with an 'options' array.

    evert authored tedivm committed
  10. @evert @tedivm

    Removed clear() method. Removed $options argument from set functions,

    evert authored tedivm committed
    and put the $ttl argument back in.
Commits on Mar 16, 2012
  1. @tedivm
  2. @tedivm
Commits on May 14, 2012
  1. @tedivm

    Corrected typo.

    tedivm authored
Commits on May 26, 2012
  1. @norv

    I'd prefer invalidate(), personally, but we should use at least flush…

    norv authored
    …() since already documented.
Commits on May 27, 2012
  1. @tedivm

    Merge pull request #3 from norv/patch-1

    tedivm authored
    Fixed empty()
  2. @tedivm

    Merge pull request #4 from norv/Cache

    tedivm authored
    Typo.
  3. @tedivm

    Merge pull request #5 from norv/Cache

    tedivm authored
    php tags in Extensions interfaces.
Commits on May 28, 2012
  1. @norv

    Typo.

    norv authored
  2. @norv

    php tags in Extensions interfaces.

    norv authored
    Signed-off-by: Norv <norv@simplemachines.org>
  3. @tedivm
Commits on Jun 1, 2012
  1. @tedivm

    Updated the Stackable keys to have them start with a root slash.

    tedivm authored
    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.
  2. @tedivm

    Merge pull request #6 from tedivm/cache_stacks

    tedivm authored
    Updated the Stackable keys to have them start with a root slash.
  3. @norv

    Clarification on Item::set() as the method binding to the underlying …

    norv authored
    …system.
    
    Added php tags.
    
    Signed-off-by: Norv <norv@simplemachines.org>
  4. @tedivm

    Merge pull request #7 from norv/Cache

    tedivm authored
    Clarification on Item::set()
Commits on Jun 13, 2012
  1. @tedivm

    Updated the names of the "get" functions to use "Item" instead of "Ca…

    tedivm authored
    …che"
    
    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.
  2. @tedivm

    Merge pull request #8 from tedivm/cache_naming

    tedivm authored
    Updated the names of the "get" functions to use "Item" instead of "Cache"
  3. @tedivm

    Corrected typos and spelling

    tedivm authored
Commits on Nov 9, 2012
  1. @tedivm

    Removed Extensions from Proposal

    tedivm authored
    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.
Commits on Feb 26, 2013
  1. @tedivm
  2. @tedivm
  3. @tedivm

    Removed old PSR

    tedivm authored
    Accidentally tossed an old PSR in here when merging with the main
    fig-standards branch.
  4. @tedivm

    Removed Cache Extensions

    tedivm authored
Commits on Feb 27, 2013
  1. @tedivm

    Changed the "isMiss" function to "isValid".

    tedivm authored
    This was based off of Paul's suggestion in the mailing list, and tries
    to make the function call more intuitive.
  2. @tedivm

    Changed the "flush" function to "empty"

    tedivm authored
    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.
Commits on Mar 5, 2013
  1. @simensen
  2. @tedivm

    Merge pull request #10 from simensen/description

    tedivm authored
    Added "Key Concepts" section to help explain naming conventions.
Commits on Mar 7, 2013
  1. @simensen
  2. @tedivm

    Merge pull request #12 from simensen/value-null

    tedivm authored
    Value should be able to be set to null.
  3. @simensen
  4. @tedivm

    Merge pull request #13 from simensen/empty-to-clear

    tedivm authored
    Use clear instead of empty as empty is a reserved word.
This page is out of date. Refresh to see the latest.
View
247 proposed/PSR-Cache.md
@@ -0,0 +1,247 @@
+## 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.
+
+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.
+
+
+## Goal
+
+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.
+
+
+## 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, or a DateInterval object.
+
+* **Expiration** - The actual time when an item is set to go stale. This it
+typically calculated by adding the TTL to the time when an object is stored, but
+can also be explicitly set with DateTime object.
+
+ 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. Implementing
+Libraries are responsible for any encoding or escaping required by their
+backends, but must be able to supply the original key if needed. Keys should not
+contain the special characters listed:
+
+ {}()/\@
+
+* **Miss** - An item is considered missing from the cache when it isn't there
+or has an expiration in the past. Additional Miss conditions can be defined by
+the Implementing Library as long as these conditions are met (at no point should
+an expired item not be considered a miss).
+
+* **Calling Library** - The library or code that actually needs the cache
+services. This library will utilize caching services that implement this
+standard's interfaces, but will otherwise have no knowledge of the
+implementation of those caching services.
+
+* **Implementing Library** - This library is responsible for implementing
+this standard in order to provide caching services to any Calling Library. The
+Implementing Library must provide classes which implement the Cache\Pool and
+Cache\Item interfaces.
+
+
+## Data
+
+
+Acceptable data includes all serializable PHP data types-
+
+* **Strings** - Simple, complex and large strings of any encoding.
+* **Integers** - Positive, negative and large integers (>32 bit).
+* **Floats** - Positive, negative and large.
+* **Boolean**- true, false.
+* **Null** - not a wrapper or object, but the actual null value.
+* **Arrays** - indexed, associative and multidimensional.
+* **Object** - those that support the PHP serialize functionality.
+
+All data passed into the Implementing Library must be returned exactly as
+passed. If this is not possible for whatever reason then it is preferable to
+respond with a cache miss than with corrupted data.
+
+
+## Key Concepts
+
+### Pool
+
+The pool represents a collection of items in a caching system. The pool
+conceptually contains all of the items. When you want to get something out of
+the caching system, you use the Pool to create the Item object. A Pool can
+return one Item or many Items, and the pool can be used to clear all of the
+items in the cache.
+
+
+### Items
+
+An item represents a single key/value pair inside of a caching system. It is
+associated with a "key" that can't be changed, and a value that can be set or
+retrieved. The status of the item (hit or miss) is relevant only to that
+particular item.
+
+
+## Interfaces
+
+
+### Cache\Pool
+
+The main focus of the Cache\Pool object is to accept a key from the Calling
+Library and return the associated Cache\Item object. The majority of the Pool
+object's implementation is up to the Implementing Library, including all
+configuration, initialization and the injection itself into the Calling Library.
+
+Items can be retrieved from the Cache\Pool individually using the getItem
+function, or in groups by retrieving an Iterator object from the
+getItemIterator function.
+
+```php
+<?php
+namespace PSR\Cache;
+
+/**
+ * Cache\Pool generates Cache\Item objects.
+ */
+interface Pool
+{
+ /**
+ * Returns objects which implement the Cache\Item interface.
+ *
+ * Provided key must be unique for each item in the cache. Implementing
+ * Libraries are responsible for any encoding or escaping required by their
+ * backends, but must be able to supply the original key if needed. Keys
+ * should not contain the special characters listed:
+ * {}()/\@
+ *
+ * @param string $key
+ * @return PSR\Cache\Item
+ */
+ function getItem($key);
+
+ /**
+ * Returns a group of cache objects as an \Iterator
+ *
+ * Bulk lookups can often by streamlined by backend cache systems. The
+ * returned iterator will contain a Cache\Item for each key passed.
+ *
+ * @param array $keys
+ * @return \Iterator
+ */
+ function getItemIterator($keys);
+
+ /**
+ * Clears the cache pool of all items.
+ *
+ * @return bool
+ */
+ function clear();
+}
+```
+
+
+### Cache\Item
+
+The Cache\Item object encapsulates the storage and retrieval of cache items.
+Each Cache\Item is generated by a Cache\Pool, which is responsible for any
+required setup as well as associating the object with a unique Key (how this is
+accomplished is the responsibility of the Implementing Library). Cache\Item
+objects can store and retrieve any type of PHP value defined in the Data section
+of this document.
+
+```php
+<?php
+namespace PSR\Cache;
+
+/**
+ * Cache\Item defines an interface for interacting with objects inside a cache.
+ *
+ * The Cache\Item interface defines an item inside a cache system, which can be
+ * filled with any PHP value capable of being serialized. Each item Cache\Item
+ * should be associated with a specific key, which can be set according to the
+ * implementing system and is typically passed by the Cache\Pool object.
+ */
+interface Item
+{
+ /**
+ * Returns the key for the current cache item.
+ *
+ * The key is loaded by the Implementing Library, but should be available to
+ * the higher level callers when needed.
+ *
+ * @return string
+ */
+ function getKey();
+
+ /**
+ * Retrieves the item from the cache associated with this objects key.
+ *
+ * Value returned must be identical to the value original stored by set().
+ *
+ * If the cache is empty then null should be returned. However, null is also
+ * a valid cache item, so the isMiss function should be used to check
+ * validity.
+ *
+ * @return mixed
+ */
+ function get();
+
+ /**
+ * Stores a value into the cache.
+ *
+ * The $value argument can be any item that can be serialized by PHP,
+ * although the method of serialization is left up to the Implementing
+ * Library.
+ *
+ * The $ttl can be defined in a number of ways. As an integer or
+ * DateInverval object the argument defines how long before the cache should
+ * expire. As a DateTime object the argument defines the actual expiration
+ * time of the object. Implementations are allowed to use a lower time than
+ * passed, but should not use a longer one.
+ *
+ * If no $ttl is passed then the item can be stored indefinitely or a
+ * default value can be set by the Implementing Library.
+ *
+ * Returns true if the item was successfully stored.
+ *
+ * @param mixed $value
+ * @param int|DateInterval|DateTime $ttl
+ * @return bool
+ */
+ function set($value = null, $ttl = null);
+
+ /**
+ * Validates the current state of the item in the cache.
+ *
+ * Checks the validity of a cache result. If the object is good (is not a
+ * miss, and meets all the standards set by the Implementing Library) then
+ * this function returns true.
+ *
+ * @return bool
+ */
+ function isValid();
+
+ /**
+ * Removes the current key from the cache.
+ *
+ * Returns true if the item is no longer present (either because it was
+ * removed or was not present to begin with).
+ *
+ * @return bool
+ */
+ function remove();
+}
+```
View
80 proposed/PSR/Cache/Item.php
@@ -0,0 +1,80 @@
+<?php
+
+namespace PSR\Cache;
+
+/**
+ * Cache\Item defines an interface for interacting with objects inside a cache.
+ *
+ * The Cache\Item interface defines an item inside a cache system, which can be
+ * filled with any PHP value capable of being serialized. Each item Cache\Item
+ * should be associated with a specific key, which can be set according to the
+ * implementing system and is typically passed by the Cache\Pool object.
+ */
+interface Item
+{
+ /**
+ * Returns the key for the current cache item.
+ *
+ * The key is loaded by the Implementing Library, but should be available to
+ * the higher level callers when needed.
+ *
+ * @return string|false
+ */
+ function getKey();
+
+ /**
+ * Retrieves the item from the cache associated with this objects key.
+ *
+ * Value returned must be identical to the value original stored by set().
+ *
+ * If the cache is empty then null should be returned. However, null is also
+ * a valid cache item, so the isMiss function should be used to check
+ * validity.
+ *
+ * @return mixed
+ */
+ function get();
+
+ /**
+ * Stores a value into the cache.
+ *
+ * The $value argument can be any item that can be serialized by PHP, although
+ * the method of serialization is left up to the Implementing Library.
+ *
+ * The $ttl can be defined in a number of ways. As an integer or
+ * DateInterval object the argument defines how long before the cache should
+ * expire. As a DateTime object the argument defines the actual expiration
+ * time of the object. Implementations are allowed to use a lower time than
+ * passed, but should not use a longer one.
+ *
+ * If no $ttl is passed then the item can be stored indefinitely or a
+ * default value can be set by the Implementing Library.
+ *
+ * Returns true if the item was successfully stored.
+ *
+ * @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
mrclay added a note

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

@mnapoli
mnapoli added a note

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

@mrclay
mrclay added a note

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 Owner

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
tedivm added a note

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

@Seldaek
Seldaek added a note

how about exists()?

@tedivm
tedivm added a note

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
Seldaek added a note
@mnapoli
mnapoli added a note

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

@tedivm
tedivm added a note

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- http://stash.tedivm.com/Invalidation.html ) then this standard should not get in their way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+ /**
+ * Removes the current key from the cache.
+ *
+ * Returns true if the item is no longer present (either because it was
+ * removed or was not present to begin with).
+ *
+ * @return bool
+ */
+ function remove();
+}
View
42 proposed/PSR/Cache/Pool.php
@@ -0,0 +1,42 @@
+<?php
+
+namespace PSR\Cache;
+
+/**
+ * Cache\Pool generates Cache\Item objects.
+ */
+interface Pool
+{
+ /**
+ * Returns objects which implement the Cache\Item interface.
+ *
+ * Provided key must be unique for each item in the cache. Implementing
+ * Libraries are responsible for any encoding or escaping required by their
+ * backends, but must be able to supply the original key if needed. Keys
+ * should not contain the special characters listed:
+ * {}()/\@
+ *
+ * @param string $key
+ * @return PSR\Cache\Item
+ */
+ function getItem($key);
+
+ /**
+ * Returns a group of cache objects as an \Iterator
+ *
+ * Bulk lookups can often by streamlined by backend cache systems. The
+ * returned iterator will contain a Cache\Item for each key passed.
+ *
+ * @param array $keys
+ * @return \Iterator
+ */
+ function getItemIterator($keys);
+
+ /**
+ * Empties the cache pool of all items.
+ *
+ * @return bool
+ */
+ function flush();
+
+}
Something went wrong with that request. Please try again.