PhutilKeyValueCache.php

<?php

/**
 * Interface to a key-value cache like Memcache or APC. This class provides a
 * uniform interface to multiple different key-value caches and integration
 * with PhutilServiceProfiler.
 *
 * @task  kvimpl    Key-Value Cache Implementation
 */
abstract class PhutilKeyValueCache extends Phobject {


/* -(  Key-Value Cache Implementation  )------------------------------------- */


  /**
   * Determine if the cache is available. For example, the APC cache tests if
   * APC is installed. If this method returns false, the cache is not
   * operational and can not be used.
   *
   * @return bool True if the cache can be used.
   * @task kvimpl
   */
  public function isAvailable() {
    return false;
  }


  /**
   * Get a single key from cache. See @{method:getKeys} to get multiple keys at
   * once.
   *
   * @param   string  Key to retrieve.
   * @param   wild    Optional value to return if the key is not found. By
   *                  default, returns null.
   * @return  wild    Cache value (on cache hit) or default value (on cache
   *                  miss).
   * @task kvimpl
   */
  final public function getKey($key, $default = null) {
    $map = $this->getKeys(array($key));
    return idx($map, $key, $default);
  }


  /**
   * Set a single key in cache. See @{method:setKeys} to set multiple keys at
   * once.
   *
   * See @{method:setKeys} for a description of TTLs.
   *
   * @param   string    Key to set.
   * @param   wild      Value to set.
   * @param   int|null  Optional TTL.
   * @return  this
   * @task kvimpl
   */
  final public function setKey($key, $value, $ttl = null) {
    return $this->setKeys(array($key => $value), $ttl);
  }


  /**
   * Delete a key from the cache. See @{method:deleteKeys} to delete multiple
   * keys at once.
   *
   * @param   string  Key to delete.
   * @return  this
   * @task kvimpl
   */
  final public function deleteKey($key) {
    return $this->deleteKeys(array($key));
  }


  /**
   * Get data from the cache.
   *
   * @param   list<string>        List of cache keys to retrieve.
   * @return  dict<string, wild>  Dictionary of keys that were found in the
   *                              cache. Keys not present in the cache are
   *                              omitted, so you can detect a cache miss.
   * @task kvimpl
   */
  abstract public function getKeys(array $keys);


  /**
   * Put data into the key-value cache.
   *
   * With a TTL ("time to live"), the cache will automatically delete the key
   * after a specified number of seconds. By default, there is no expiration
   * policy and data will persist in cache indefinitely.
   *
   * @param dict<string, wild>  Map of cache keys to values.
   * @param int|null            TTL for cache keys, in seconds.
   * @return this
   * @task kvimpl
   */
  abstract public function setKeys(array $keys, $ttl = null);


  /**
   * Delete a list of keys from the cache.
   *
   * @param list<string> List of keys to delete.
   * @return this
   * @task kvimpl
   */
  abstract public function deleteKeys(array $keys);


  /**
   * Completely destroy all data in the cache.
   *
   * @return this
   * @task kvimpl
   */
  abstract public function destroyCache();

}