Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Proposal for an object cache #11

Closed
wants to merge 17 commits into from

6 participants

@evert

No description provided.

proposed/objectcache.md
((71 lines not shown))
+ * Check if the key exists in the cache.
+ *
+ * @param string $key
+ * @return boolean
+ */
+ function exists($key);
+
+ /**
+ * Clears the entire cache.
+ *
+ * Implementations may choose to ignore this. What happens in this case
+ * is up to the implementor.
+ *
+ * @return void
+ */
+ function clear();

Should not be on the interface imho. Given namespacing of cache keys the behavior even inside the same cache implementation is undefined. We shouldn't give users somethings that can't be trusted. We removed this method from Doctrine cache because of this.

@evert
evert added a note
@evert
evert added a note

Whoops.. the way the email was formatted it seemed like you were talking about exists() and clear(), but now I see that doesn't make as much sense.

We're been having all disucssions in this group:

http://groups.google.com/group/php-standards

Perhaps you feel like joining there and repeating your point?

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

Any reason the interface is called 'Base' instead of the more expressive 'Cache' ? Same goes for 'Multiple' => MultipleCache.

There's been some discussion around naming on the mailing list.

@norv

I really don't think defining an exists() on the cache is a good idea, in particular for a standard and a reference implementation of it. Because mainly of the reasons outlined by yourself as well as others, on making the implementations prone to race conditions.

If anything, the standard and its reference implementation should not promote (or enable too easily) buggy practices, at this level we're talking about here. (one I'm just pulling out of the legacy code...). And anyway, logically speaking, the result returned by exists() is simply not to be relied upon for more than strictly the moment of the call return, which is very error prone.

If exists() information is really needed - needed from the standard cache interface(s) - then probably the best way to provide it is through the discussed CacheEntry class, or CacheItem/CacheRecord as it's called in the alternative implementation.

@dlsniper

Hi @evert

If you still support the proposal I've came up with you, php-fig/fig-standards#63 then should this still be opened?

Thank you!

@evert

Closed this in favor of : #96

@dragoonis dragoonis closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Dec 14, 2011
  1. @evert

    Added objectcache proposal

    evert authored
  2. @evert

    Changed namespace to PSR

    evert authored
Commits on Dec 15, 2011
  1. @evert
  2. @dragoonis
  3. @evert

    Merge pull request #1 from dragoonis/patch-1

    evert authored
    Proposing the exists() method to check existence in the cache.
Commits on Dec 17, 2011
  1. @evert

    Added 'clear'

    evert authored
  2. @evert
Commits on Dec 21, 2011
  1. @evert
  2. @evert

    Note about unset

    evert authored
  3. @evert

    Added EmulateMultiple cache

    evert authored
  4. @evert
Commits on Feb 14, 2012
  1. @evert

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

    evert authored
    and put the $ttl argument back in.
Commits on Oct 22, 2012
  1. @evert
  2. @evert
  3. @evert

    Removed the obvious

    evert authored
  4. @evert
Commits on Oct 24, 2012
  1. @evert

    Fixed all PSR-2 violations.

    evert authored
This page is out of date. Refresh to see the latest.
Showing with 237 additions and 0 deletions.
  1. +237 −0 proposed/objectcache.md
View
237 proposed/objectcache.md
@@ -0,0 +1,237 @@
+Cache Interface
+===============
+
+Many PHP frameworks define a PHP persistent object cache with various features.
+An object cache is something that may be useful in many parts of an
+application, and thus may be injected in quite a bit of subsystems.
+
+Many existing frameworks, libraries and applications redefine these systems,
+often including APC, Memcached and many others.
+
+This document proposes a very simple standard interface. It is meant to cover
+*just* the base functionality most cache libraries provide.
+
+We realize that this interface will not cover every usecase, nor do we expect
+this to be the case. We hope for the cache providers that already have an
+existing implementation and wish to not break backwards compatibility, an
+adapter can be provided for compatibility with this standard.
+
+1. The base interface
+---------------------
+
+```php
+namespace PSR\Cache;
+
+interface Base
+{
+
+ /**
+ * Stores a new value in the cache.
+ *
+ * The key must be provided as a string, the value may be any
+ * serializable PHP value.
+ *
+ * Use the $ttl argument to specify how long the cache is valid for.
+ * The time-to-live is specified in seconds.
+ *
+ * If $ttl is not specified, the implementation may choose a default.
+ * The $ttl argument should be considered a 'suggestion'. The
+ * implementation may ignore it.
+ *
+ * @param string $key
+ * @param mixed $value
+ * @param int $ttl
+ * @return void
+ */
+ public function set($key, $value, $ttl = null);
+
+ /**
+ * Fetches an object from the cache.
+ *
+ * If the object did not exist, this method must return null.
+ *
+ * @param string $key
+ * @return mixed
+ */
+ public function get($key);
+
+ /**
+ * Deletes an item from the cache.
+ *
+ * This method must succeed, even if the item did not exist.
+ *
+ * @param string $key
+ * @return void
+ */
+ public function delete($key);
+
+
+ /**
+ * Check if the key exists in the cache.
+ *
+ * @param string $key
+ * @return boolean
+ */
+ public function exists($key);
+
+}
+```
+
+2. Bulk Operations
+------------------
+
+For some cases it's beneficial to request multiple objects at once. One big
+benefit is that requests can be pipelined, thus reducing latency.
+
+For these cases the Multiple interface may be implemented.
+
+```php
+namespace PSR\Cache;
+
+interface Multiple extends Base
+{
+
+ /**
+ * Stores multiple items in the cache at once.
+ *
+ * The items must be provided as an associative array.
+ *
+ * @param array $items
+ * @param int $ttl
+ * @return void
+ */
+ public function setMultiple(array $items, $ttl = null);
+
+ /**
+ * Fetches multiple items from the cache.
+ *
+ * The returned structure must be an associative array. If items were
+ * not found in the cache, they should not be included in the array.
+ *
+ * This means that if none of the items are found, this method must
+ * return an empty array.
+ *
+ * @param string $keys
+ * @return array
+ */
+ public function getMultiple($keys);
+
+ /**
+ * Deletes multiple items from the cache at once.
+ *
+ * @param array $key
+ * @return void
+ */
+ public function deleteMultiple($keys);
+
+ /**
+ * Check for multiple items if they appear in the cache.
+ *
+ * All items must be returned as an array. And each must array value
+ * must either be set to true, or false.
+ *
+ * @param array $keys
+ * @return array
+ */
+ public function existsMultiple($keys);
+
+}
+```
+
+If the backend does not natively implement bulk operations, it can still
+be easily emulated. The following trait could be used as an example to emulate
+this.
+
+**Note that this trait is strictly an example, and MUST NOT be considered as
+part of the standard.**
+
+```php
+
+trait EmulateMultiple
+{
+
+ /**
+ * Stores multiple items in the cache at once.
+ *
+ * The items must be provided as an associative array.
+ *
+ * @param array $items
+ * @param int $ttl
+ * @return void
+ */
+ public function setMultiple(array $items, $ttl = null)
+ {
+
+ foreach($items as $key=>$value) {
+ $this->set($key, $value, $ttl);
+ }
+
+ }
+
+ /**
+ * Fetches multiple items from the cache.
+ *
+ * The returned structure must be an associative array. If items were
+ * not found in the cache, they should not be included in the array.
+ *
+ * This means that if none of the items are found, this method must
+ * return an empty array.
+ *
+ * @param string $keys
+ * @return array
+ */
+ public function getMultiple($keys)
+ {
+
+ return array_map(
+ array($this, 'get'),
+ $keys
+ );
+
+ }
+
+ /**
+ * Deletes multiple items from the cache at once.
+ *
+ * @param array $key
+ * @return void
+ */
+ public function deleteMultiple($keys)
+ {
+
+ foreach($keys as $key) {
+ $this->delete($key);
+ }
+
+ }
+
+ /**
+ * Check for multiple items if they appear in the cache.
+ *
+ * All items must be returned as an array. And each must array value
+ * must either be set to true, or false.
+ *
+ * @param array $keys
+ * @return array
+ */
+ public function existsMultiple($keys)
+ {
+
+ return array_map(
+ array($this, 'exists'),
+ $keys
+ );
+
+ }
+
+}
+```
+
+3. Notes
+--------
+
+* This document does not define how to handle error conditions, such as the
+ inability to store an item, due to for example a backend being down.
+* This document does not define what constitutes valid keys. Backends may have
+ restrictions around this. It is recommended for the calling code to use
+ sane keys, and possibly run a hash function if needed.
Something went wrong with that request. Please try again.