Proposal for additional notes on the increment/decrement operations.

IncrementableInterface.markdown

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.

• Implementations MUST allow any integer to be incremented and decremented (i.e. decrementing 0 yields -1) by any [positive?] integer.
• If a key does not exist, implementations MUST NOT create a new cache item and instead return false.
• If a cache item does not hold an integer, implementations MUST NOT attempt to cast or coerce and instead return false.
• TODO: Incrementing by 0 ... ?
• TODO: What happens to negative $step values?

<?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);

}