<?php
/**
 * File containing the ezcConfigurationManager class
 *
 * @package Configuration
 * @version 1.0beta2
 * @copyright Copyright (C) 2005 eZ systems as. All rights reserved.
 * @license http://ez.no/licenses/new_bsd New BSD License
 */
/**
 * ezcConfigurationManager provides easy access to application settings.
 *
 * Using this class removes the need to work with specific readers and writers
 * and also handles caching to speed up the process. This can be useful for
 * smaller applications which don't have too many settings and does not have
 * high memory or speed requirements.
 *
 * Before the manager can be used it must be configured so it knows where to
 * fetch the settings, this is usually at the start of the program.
 * <code>
 * $man = ezcConfigurationManager::getInstance();
 * $man->init( 'ezcConfigurationIniReader', 'settings', $options );
 * </code>
 *
 * After it is configured the rest of the code can simply access the global
 * instance and fetch the settings using getSetting().
 * <code>
 * $color = ezcConfigurationManager::getInstance()->setting( 'site', 'Colors', 'Background' );
 * </code>
 *
 * @see ezcConfiguration, ezcConfigurationReader, ezcConfigurationWriter
 *
 * @package Configuration
 * @version 1.0beta2
 */
class ezcConfigurationManager
{
    /**
     * The name of the class to create readers from. This class must implement
     * the ezcConfigurationReader interface, if not an exception is thrown when
     * it is created.
     *
     * @var ezcConfigurationReader
     */
    private $readerClass = null;

    /**
     * The main location of the configurations which is passed to each reader, this
     * is either the path on the filesystem or a PHP stream prefix.
     *
     * @var mixed
     */
    private $location = null;

    /**
     * Options for the readers, this is passed on when the reader is created
     * for the first time.
     *
     * @var array
     */
    private $options = array();

    /**
     * Maps the name of the configuration to the ezcConfiguration object.
     *
     * @var array
     */
    private $nameMap = array();

    /**
     * ezcConfigurationManager Singleton instance
     *
     * @var ezcConfigurationManager
     */
    static private $instance = null;

    /**
     * Constructs an empty manager.
     *
     * The constructor is private to prevent non-singleton.
     */
    private function __construct()
    {
    }

    /**
     * Returns the instance of the class ezcConfigurationManager.
     *
     * @return ezcConfigurationManager
     */
    public static function getInstance()
    {
        if ( is_null( self::$instance ) )
        {
            self::$instance = new ezcConfigurationManager();
        }
        return self::$instance;
    }

    /**
     * Initializes the manager.
     *
     * Initializes the manager with the values which will be used by the configuration
     * reader. It sets the default location and reader options and which reader to
     * use by specifying the class name.
     *
     * @param string $readerClass The name of the class to use as a
     *               configuration reader. This class must implement the
     *               ezcConfigurationReader interface.
     * @param string $location The main placement for the configuration. It is
     *               up to the specific reader to interpret this value.  This
     *               can for instance be used to determine the directory
     *               location for an INI file.
     * @param string $options Options for the configuration reader, this is
     *               passed on the reader specified in $readerClass when it is
     *               created. Check the documentation for the specific reader
     *               to see which options it supports.
     * @return void
     */
    public function init( $readerClass, $location, $options )
    {
        // Check if the passed classname actually exists
        if ( !class_exists( $readerClass, true ) )
        {
            throw new ezcConfigurationException( "Class <{$readerClass}> does not exist.", ezcConfigurationException::INVALID_READER_CLASS );
        }

        // Check if the passed classname actually implements the interface. We
        // have to do that with reflection here unfortunately
        $interfaceClass = new ReflectionClass( 'ezcConfigurationReader' );
        $handlerClass = new ReflectionClass( $readerClass );
        if ( !$handlerClass->isSubclassOf( $interfaceClass ) )
        {
            throw new ezcConfigurationException( "The class <{$readerClass}> does not implement the <ezcConfigurationReader> interface", ezcConfigurationException::INVALID_READER_CLASS );
        }

        $this->readerClass = $readerClass;
        $this->location = $location;
        $this->options = $options;
    }

    /**
     * Fetches a reader for the configuration $name.
     *
     * This method checks whether the configuration name was previously
     * requested. If it is not requested before, the method will construct a
     * new configuration reader based on the settings that were passed to this
     * class with the init() method.
     *
     * If the $mayFail parameter is set to true, then the function will not try
     * to call the load() method on the reader if a configuration doesn't
     * exists (this will throw an ezcConfigurationException::UNKNOWN_CONFIG).
     * If it is not passed, or set to false then load() will always be called,
     * with the possibility of the exception being thrown.
     *
     * @param string $name
     * @param bool $mayFail
     * @return ezcConfigurationReader The constructed reader
     */
    private function fetchReader( $name, $mayFail = false )
    {
        if ( !isset( $this->nameMap[$name] ) )
        {
            $className = $this->readerClass;
            $class = new $className();
            $class->init( $this->location, $name, $this->options );
            if ( $class->configExists() || !$mayFail )
            {
                $class->load();
            }
            $this->nameMap[$name] = $class;
        }
        return $this->nameMap[$name];
    }

    /**
     * Returns whether the setting $setting exists in group $group in the
     * configuration named $name.
     *
     * @throws ezcConfigurationException::UNKNOWN_CONFIG if the configuration does not
     *         exist.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return bool
     */
    public function hasSetting( $name, $group, $setting )
    {
        $reader = $this->fetchReader( $name );
        $config = $reader->getConfig();
        if ( $config )
        {
            return $reader->getConfig()->hasSetting( $group, $setting );
        }
        else
        {
            throw new ezcConfigurationException( "The configuration <{$name}> does not exist.", ezcConfigurationException::UNKNOWN_CONFIG );
        }
    }

    /**
     * Returns the configuration object for a the configuration named $name.
     *
     * @param string $name
     * @return ezcConfiguration
     */
    private function fetchConfig( $name )
    {
        return $this->fetchReader( $name )->getConfig();
    }

    /**
     * Returns configuration setting.
     *
     * This method fetches a setting depending on the $name, $group and
     * $setting parameters. The $functionType parameter determines what type of
     * seting (mixed, boolean, number, string or array) should be retrieve. The
     * name that you have to pass is one 'setting', 'boolSetting',
     * 'numberSetting', 'stringSetting' or 'arraySetting'. This is not checked
     * as this is a private function.
     *
     * @throws ezcConfigurationException::UNKNOWN_CONFIG if the configuration does not
     *         exist.
     * @throws ezcConfigurationException::UNKNOWN_GROUP if the group does not
     *         exist.
     * @throws ezcConfigurationException::UNKNOWN_SETTING if the setting does
     *         not exist.
     *
     * @param string $functionType
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return mixed
     */
    private function fetchSetting( $functionType, $name, $group, $setting )
    {
        return $this->fetchConfig( $name )->$functionType( $group, $setting );
    }

    /**
     * Returns the value of the setting $setting in group $group in the configuration
     * named $name.
     *
     * Uses the fetchSetting() method to fetch the value, this method can throw
     * exceptions. This method also validates whether the value is actually a
     * boolean value.
     *
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return mixed
     */
    public function getSetting( $name, $group, $setting )
    {
        return $this->fetchSetting( 'getSetting', $name, $group, $setting );
    }

    /**
     * Returns the value of the setting $setting in group $group in the configuration
     * named $name.
     *
     * Uses the fetchSetting() method to fetch the value, this method can throw
     * exceptions. This method also validates whether the value is actually a
     * boolean value.
     *
     * @see fetchSetting
     *
     * @throws ezcConfigurationException::SETTING_NOT_BOOL if the setting value
     *         is not a boolean.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return bool
     */
    public function getBoolSetting( $name, $group, $setting )
    {
        return $this->fetchSetting( 'getBoolSetting', $name, $group, $setting );
    }

    /**
     * Returns the value of the setting $setting in group $group in the configuration
     * named $name.
     *
     * Uses the fetchSetting() method to fetch the value, this method can throw
     * exceptions. This method also validates whether the value is actually an
     * integer value.
     *
     * @see fetchSetting
     *
     * @throws ezcConfigurationException::SETTING_NOT_INT if the setting value
     *         is not a number.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return int
     */
    public function getNumberSetting( $name, $group, $setting )
    {
        return $this->fetchSetting( 'getNumberSetting', $name, $group, $setting );
    }

    /**
     * Returns the value of the setting $setting in group $group in the configuration
     * named $name.
     *
     * Uses the fetchSetting() method to fetch the value, this method can throw
     * exceptions. This method also validates whether the value is actually a
     * string value.
     *
     * @see fetchSetting
     *
     * @throws ezcConfigurationException::SETTING_NOT_STRING if the setting
     *         value is not a string.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return string
     */
    public function getStringSetting( $name, $group, $setting )
    {
        return $this->fetchSetting( 'getStringSetting', $name, $group, $setting );
    }

    /**
     * Returns the value of the setting $setting in group $group in the configuration
     * named $name.
     *
     * Uses the fetchSetting() method to fetch the value, this method can throw
     * exceptions. This method also validates whether the value is actually an
     * array value.
     *
     * @see fetchSetting
     *
     * @throws ezcConfigurationException::SETTING_NOT_ARRAY if the setting
     *         value is not an array.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return array
     */
    public function getArraySetting( $name, $group, $setting )
    {
        return $this->fetchSetting( 'getArraySetting', $name, $group, $setting );
    }

    /**
     * Returns the values of the settings $settings in group $group in the configuration
     * named $name.
     *
     * @throws ezcConfigurationException::UNKNOWN_GROUP if the group does not
     *         exist.
     * @throws ezcConfigurationException::UNKNOWN_SETTING if one of the
     *         settings does not exist.
     * @throws ezcConfigurationException::UNKNOWN_CONFIG if the configuration
     *         does not exist.
     * @param string $name
     * @param string $group
     * @param string $setting
     * @return array
     */
    public function getSettings( $name, $group, $settings )
    {
        $config = $this->fetchConfig( $name );
        return $config->getSettings( $group, $settings );
    }

    /**
     * Returns true if the configuration named $name exists.
     *
     * @param string $name
     * @return bool
     */
    public function exists( $name )
    {
        $reader = $this->fetchReader( $name, true );
        return $reader->configExists();
    }
}
?>