<?php
/**
 * File containing the ezcCacheManager class.
 *
 * @package Cache
 * @version 1.0beta2
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 * @filesource
 */

/**
 * Class to manage multiple ezcCacheStorage objects at once. Implements
 * singleton for caches which access a certain location The usage of this 
 * class is not mandatory, but recommended. ezcCacheStorage objects can 
 * also be used on their own.
 *
 * <code>
 *   // Global configuration
 *   
 *   $options = array(
 *       'ttl'   => 60*60*24*2,     // Default would be 1 day, here 2 days
 *   );
 *   CacheManager::createCache( 'content', '/var/cache/content', 'ezcCacheStorageView', $options );
 *   CacheManager::createCache( 'template', '/var/cache/templates', 'ezcCacheStorageTemplate', $options );
 *
 *   // Somewhere in the application
 *   
 *   $cache = CacheManager::getCache( 'content' );
 *
 *   $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
 *   $id = getUniqueId();
 *
 *   $data = '';
 *   // Check if data is available in the cache
 *   if ( !( $data = $cache->restore( $id, $attributes )) ) {
 *      // No, so create data...
 *      $data = generateMyData();
 *      // ... and store it inside the cache
 *      $cache->store( $id, $attributes, $data );
 *   }
 *
 *   // Somewhere else...
 *   
 *   $cache = CacheManager::getCache( 'template' );
 *
 *   // Remove all cache blocks of node 2
 *   $cache->delete( null, array( 'node' => 2 ) );
 * </code>
 * 
 * @package Cache
 */
class ezcCacheManager 
{
    /**
     * Keeps track of the ezcCacheStorage instances.
     * Each cache is created only once per request on the first time it is
     * accessed. Until then, only it's configuration is stored in the
     * {@link ezcCacheManager::$configurations} array.
     *
     * @var array( ezcCacheStorage )
     */
    private static $caches = array();

    /**
     * ezcCacheStorage configurations
     * Storage to keep track of ezcCacheStorage configurations. For each 
     * configured cache the configuration is initially stored here.
     * {@link ezcCacheStorage} objects are created on first access.
     *
     * @var array( string )
     */
    private static $configurations = array();

    /**
     * Private. This is a static class only.
     *
     * @see {ezcCacheManager::createCache()}
     * @see {ezcCacheManager::getCache()}
     */
    private function __construct() 
    { 
    }

    /**
     * Creates a new cache in the manager.
     * This method is used to create a new cache inside the manager.
     * Each cache has a unique ID to access it during the application
     * runtime. Each location may only be used by 1 cache. 
     *
     * The $storageClass parameter musst be a subclass of 
     * {@link ezcCacheStorage} and tells the manager which object 
     * will be used for the cache.
     *
     * The $location parameter depends on the kind of {@link ezcCacheStorage}
     * used for the cache you create. Usually this is a directory on your
     * file system, but may also be e.g. a data source name, if you cache in
     * a database or similar.
     *
     * The $options array consists of several standard attributes and can
     * additionally contain options defined by the {@link ezcCacheStorage} 
     * class. Standard options are:
     *
     * <code>
     * array(
     *      'ttl'   => 60*60*24,    // Time-to-life, default: 1 day
     * );
     * </code>
     *
     * @param string $id             ID of the cache to create.
     * @param string $location       Location to create the cache in.
     * @param string $storageClass   Subclass of {@link ezcCacheStorage}.
     * @param array(string) $options Options for the cache.
     *
     * @throws ezcCacheManagerException
     *         If the given location is invalid (does not exist, is not a 
     *         directory, is not writeable)
     *         {@link ezcCacheManagerException::INVALID_LOCATION}.
     * @throws ezcCacheManagerException
     *         If the given location is already in use by another cache
     *         {@link ezcCacheManagerException::USED_LOCATION}.
     * @throws ezcCacheManagerException
     *         If the given storage class does not exist or is no subclas of 
     *         ezcCacheStorage
     *         {@link ezcCacheManagerException::INVALID_STORAGE_CLASS}.
     * @return void
     */
    public static function createCache( $id, $location, $storageClass, $options = array() ) 
    {
        // Sanity check existance.
        if ( !file_exists( $location ) || !is_dir( $location ) || !is_writeable( $location ) ) 
        {
            throw new ezcCacheManagerException( 
                '<' . $location . '> is not a valid location for a ezcCache.',
                ezcCacheManagerException::INVALID_LOCATION
            );
        }
        $location = realpath( $location );
        // Sanity check double taken locations.
        foreach ( self::$configurations as $confId => $config )
        {
            if ( $config['location'] == $location ) {
                throw new ezcCacheManagerException( 
                    'Location <' . $location . '> already in use by cache with ID <' . $confId . '>.',
                    ezcCacheManagerException::USED_LOCATION
                );
            }
        }
        // Sanity check storage class. Used @ to avoid nasty warning on non-existant classes.
        if ( !@class_exists( $storageClass ) || !is_subclass_of( $storageClass, 'ezcCacheStorage' ) )
        {
            throw new ezcCacheManagerException( 
                '<' . $storageClass . '> is not a valid class or does not extend the abstract ezcCacheStorage class.',
                ezcCacheManagerException::INVALID_STORAGE_CLASS
            );
        }
        self::$configurations[$id] = array(
            'location' => $location,
            'class'    => $storageClass,
            'options'  => $options,
        );
    }

    /**
     * Returns the ezcCacheStorage object with the given ID.
     * The cache ID has to be defined before using the 
     * {@link ezcCacheManager::createCache()} method. If no instance of this
     * cache does exist yet, it's created on the fly. If one exists, it will 
     * be reused.
     * 
     * @param string $id       The ID of the cache to return.
     * @return ezcCacheStorage The cache with the given ID.
     *
     * @throws ezcCacheManagerException
     *         If the given cache ID does not exist
     *         {@link ezcCacheManagerException::INVALID_ID}.
     * @throws ezcCacheStorageException
     *         If the storage location does not exist
     *         {@link ezcCacheStorageException::LOCATION_NOT_AVAILABLE}.
     * @throws ezcCacheStorageException
     *         If the storage location is not a directory
     *         {@link ezcCacheStorageException::LOCATION_NOT_AVAILABLE}.
     * @throws ezcCacheStorageException
     *         If the storage location is not writeable
     *         {@link ezcCacheStorageException::LOCATION_NOT_WRITEABLE}.
     * @throws ezcBaseConfigException
     *         If an unknown option is set
     *         {@link ezcBaseConfigException::UNKNOWN_CONFIG_SETTING}.
     */
    public static function getCache( $id ) 
    {
        // Look for already existing cache object
        if ( !isset( self::$caches[$id] ) ) 
        {
            // Failed, look for configuration
            if ( !isset( self::$configurations[$id] ) )
            {
                throw new ezcCacheManagerException(
                    'No cache or cache configuration known with ID <' . $id . '>.',
                    ezcCacheManagerException::INVALID_ID
                );
            }
            $class = self::$configurations[$id]['class'];
            self::$caches[$id] = new $class( self::$configurations[$id]['location'], self::$configurations[$id]['options'] );
        }
        return self::$caches[$id];
    }
}
?>