class DrupalCacheArray

abstract class DrupalCacheArray implements ArrayAccess {
    
    /**
     * A cid to pass to cache_set() and cache_get().
     */
    protected $cid;
    
    /**
     * A bin to pass to cache_set() and cache_get().
     */
    protected $bin;
    
    /**
     * An array of keys to add to the cache at the end of the request.
     */
    protected $keysToPersist = array();
    
    /**
     * Storage for the data itself.
     */
    protected $storage = array();
    
    /**
     * Constructs a DrupalCacheArray object.
     *
     * @param $cid
     *   The cid for the array being cached.
     * @param $bin
     *   The bin to cache the array.
     */
    public function __construct($cid, $bin) {
        $this->cid = $cid;
        $this->bin = $bin;
        if ($cached = cache_get($this->cid, $this->bin)) {
            $this->storage = $cached->data;
        }
    }
    
    /**
     * Implements ArrayAccess::offsetExists().
     */
    public function offsetExists($offset) {
        return $this->offsetGet($offset) !== NULL;
    }
    
    /**
     * Implements ArrayAccess::offsetGet().
     */
    public function offsetGet($offset) {
        if (isset($this->storage[$offset]) || array_key_exists($offset, $this->storage)) {
            return $this->storage[$offset];
        }
        else {
            return $this->resolveCacheMiss($offset);
        }
    }
    
    /**
     * Implements ArrayAccess::offsetSet().
     */
    public function offsetSet($offset, $value) {
        $this->storage[$offset] = $value;
    }
    
    /**
     * Implements ArrayAccess::offsetUnset().
     */
    public function offsetUnset($offset) {
        unset($this->storage[$offset]);
    }
    
    /**
     * Flags an offset value to be written to the persistent cache.
     *
     * If a value is assigned to a cache object with offsetSet(), by default it
     * will not be written to the persistent cache unless it is flagged with this
     * method. This allows items to be cached for the duration of a request,
     * without necessarily writing back to the persistent cache at the end.
     *
     * @param $offset
     *   The array offset that was requested.
     * @param $persist
     *   Optional boolean to specify whether the offset should be persisted or
     *   not, defaults to TRUE. When called with $persist = FALSE the offset will
     *   be unflagged so that it will not be written at the end of the request.
     */
    protected function persist($offset, $persist = TRUE) {
        $this->keysToPersist[$offset] = $persist;
    }
    
    /**
     * Resolves a cache miss.
     *
     * When an offset is not found in the object, this is treated as a cache
     * miss. This method allows classes implementing the interface to look up
     * the actual value and allow it to be cached.
     *
     * @param $offset
     *   The offset that was requested.
     *
     * @return
     *   The value of the offset, or NULL if no value was found.
     */
    protected abstract function resolveCacheMiss($offset);
    
    /**
     * Writes a value to the persistent cache immediately.
     *
     * @param $data
     *   The data to write to the persistent cache.
     * @param $lock
     *   Whether to acquire a lock before writing to cache.
     */
    protected function set($data, $lock = TRUE) {
        // Lock cache writes to help avoid stampedes.
        // To implement locking for cache misses, override __construct().
        $lock_name = $this->cid . ':' . $this->bin;
        if (!$lock || lock_acquire($lock_name)) {
            if ($cached = cache_get($this->cid, $this->bin)) {
                $data = $cached->data + $data;
            }
            cache_set($this->cid, $data, $this->bin);
            if ($lock) {
                lock_release($lock_name);
            }
        }
    }
    
    /**
     * Destructs the DrupalCacheArray object.
     */
    public function __destruct() {
        if ($this->bin == 'cache_form' && !variable_get('drupal_cache_array_persist_cache_form', FALSE)) {
            return;
        }
        $data = array();
        foreach ($this->keysToPersist as $offset => $persist) {
            if ($persist) {
                $data[$offset] = $this->storage[$offset];
            }
        }
        if (!empty($data)) {
            $this->set($data);
        }
    }

}