Config Class

<?php

namespace Woss;

/**
 * @name        Config
 * @package     \Woss
 * @extends     \Woss\Config\Flags
 * @implements  \ArrayAccess, \Coutable, \Iterator
 * @uses        \Woss\Config\Exception
 * @version     v1.0.0
 * @since       v1.0.0
 * @filesource  woss/libraries/Config.php
 */

class Config extends \Woss\Config\Flags implements \ArrayAccess, \Countable, \Iterator {

    /**
     * @var  array  $_config  Lista de itens de configuração
     * @since  v1.0.0
     */

    protected $_config = array();

    /**
     * @var  integer  $_index  Índice do item atual da iteração
     * @since  v1.0.0
     */

    protected $_index = 0;

    /**
     * @var  array  $_shortcuts  Lista de atalhos
     * @since  v1.0.0
     */

    protected $_shortcuts = array();

    /**
     * Construtor da classe Config
     *
     * @param   array | Config      $config     Lista de configurações iniciais
     * @param   array               $flags      Configurações pré-definidas
     * @return  Config
     * @access  public
     * @since   v1.0.0
     * @final
     */

    final public function __construct($config = NULL, $flags = array()) {

        // Verifica se há configurações iniciais

        if ( $config !== NULL ) {

            // Valida as configurações iniciais

            if ( (is_array($config) && $this->_is_associative_array($config) || ($config instanceof \Woss\Config) || ($config instanceof \Woss\Config\Ini) || ($config instanceof \Woss\Config\Php)) ) {

                // Define as configurações

                $this->merge($config);

            } else {

                // Dispara uma exceção de erro

                throw new \Woss\Config\Exception ( \Woss\Config\Exception :: NOT_VALID_START_CONFIG );

            }

        }

        // Configura as flags

    parent::__construct($flags);

    }

    /**
     * Retorna o valor de um item ou grupo de configuração
     *
     * @param   string      $name       Nome do item ou grupo de configuração
     * @param   mixed       $default    Valor padrão retornado caso o item não esteja definido
     * @return  mixed
     * @access  public
     * @since   v1.0.0
     */

    public function get ($name, $default = NULL) {

        // Verifica se o item é um atalho

        if ( $this->is_shortcut($name) === TRUE ) $name = $this->_shortcuts[$name];

        // Retorna o valor do item de configuração

        return ($this->is_set($name)) ? $this->_get_item($name) : $default;

    }

    /**
     * Retorna o valor de um item ou grupo de configuração
     *
     * @param   string      $name       Nome do item ou grupo de configuração
     * @return  mixed
     * @access  public
     * @since   v1.0.0
     */

    public function __get ($name) {

        // Retorna o valor do item de configuração

        return $this->get($name, FALSE);

    }

    /**
     * Define o valor de um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @param   mixed       $value      Valor do item
     * @param   boolean     $overwrite  Permite o item ser sobrescrito quando este já existir
     * @return  mixed
     * @access  public
     * @since   v1.0.0
     */

    public function set ($name, $value, $overwrite = TRUE) {

        // Verifica se a lista é apenas leitura

        if ( ! $this->_is_set_flag(self::READ_ONLY) ) {

            // Verifica se o item já está definido e pode ser sobrescrito

            if ( $this->is_set($name) && !($overwrite) ) {

                // Dispara uma exceção de erro

                throw new \Woss\Config\Exception ( \Woss\Config\Exception :: ITEM_NOT_OVERWRITE );

            } else {

                // Recupera a referência ao item de configuração

                $name =& $this->_get_item($name);

                // Define seu novo valor

                $name = $value;

            }

        } else {

            // Dispara uma exceção de erro

            throw new \Woss\Config\Exception ( \Woss\Config\Exception :: READ_ONLY );

        }

    }

    /**
     * Define o valor de um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @param   mixed       $value      Valor do item
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function __set ($name, $value) {

        // Define o valor de um item de configuração

        $this->set($name, $value);

    }

    /**
     * Verifica se determinado item está definido
     *
     * @param   string      $name       Nome do item de configuração
     * @return  boolean
     * @access  public
     * @since   v1.0.0
     */

    public function is_set ($name) {

        // Copia a lista de itens de configuração

        $config = $this->_config;

        // Percorre a lista

        foreach (array_map("trim", explode('.', $name)) as $group) {

            // Verifica se o grupo está definido

            if ( ! array_key_exists($group, $config) ) {

                // Retorna falso

                return FALSE;

            }

            // Move a lista ao sub-grupo

            $config = $config[$group];

        }

        // Retorna verdadeiro

        return TRUE;

    }

    /**
     * Verifica se determinado item está definido
     *
     * @param   string      $name       Nome do item de configuração
     * @return  boolean
     * @access  public
     * @since   v1.0.0
     */

    public function __isset ($name) {

        // Verifica se determinado item está definido

        return $this->is_set($name);

    }

    /**
     * Exclui um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function delete ($name) {

        // Verifica se a lista é apenas leitura

        if ( ! $this->_is_set_flag(self::READ_ONLY) ) {

            // Verifica se o item possui grupos

            if ( strrpos($name, '.') !== FALSE ) {

                // Recupera a posição inicial do nome do item

                $index = strrpos($name, '.');

                // Define os nomes do item e grupo

                $item  = substr($name, $index+1);
                $group = substr($name, 0, $index);

                // Recupera a referência ao grupo

                $group =& $this->_get_item($group);

                // Exclui o item da lista

                unset ($group[$item]);

            } else {

                // Exclui o item da lista

                unset ($this->_config[$name]);

            }

        } else {

            // Dispara uma exceção de erro

            throw new \Woss\Config\Exception ( \Woss\Config\Exception :: READ_ONLY );

         }

    }

    /**
     * Exclui um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function __unset ($name) {

        // Exclui um item da lista

        $this->delete($name);

    }

    /**
     * Limpa a lista de itens de configuração
     *
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function clear () {

        // Verifica se a lista é apenas leitura

        if ( ! $this->_is_set_flag(self::READ_ONLY) ) {

            // Limpa a lista completa

            $this->_config = array();
            $this->_index = 0;

        } else {

            // Dispara uma exceção de erro

            throw new \Woss\Config\Exception ( \Woss\Config\Exception :: READ_ONLY );

        }

    }

    /**
     * Retorna a quantidade de itens definidos
     *
     * @return  integer
     * @access  public
     * @since   v1.0.0
     */

    public function count () {

        // Retorna a quantidade de itens definidos em primeiro nível

        return count($this->_config);

    }

    /**
     * Mescla várias listas de configuração
     *
     * @param   array | Config | Ini | Php      Lista de configuração a ser mesclada
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function merge () {

        // Verifica se a lista é apenas leitura

        if ( ! $this->_is_set_flag(self::READ_ONLY) ) {

            // Recupera a lista de listas de configuração

            $lists = func_get_args();

            // Percorre a lista de listas

            foreach ($lists as $list) {

                // Verifica se a lista é válida

                if ( (is_array($list) && $this->_is_associative_array($list) || ($list instanceof \Woss\Config) || ($list instanceof \Woss\Config\Ini) || ($list instanceof \Woss\Config\Php)) ) {

                    // Verifica se a lista é instância de Config

                    if ( $list instanceof Config ) {

                        // Mescla as configurações com as novas

                        $this->_config = array_merge($this->_config, $list->return_as_array());

                    } else if ( is_array($list) ) {

                        // Percorre a lista

                        foreach ($list as $name => $value) {

                            // Define os itens de configuração

                            $this->set($name, $value);

                        }

                    } else {

                        // Mescla as configurações com as novas

                        $this->_config = array_merge($this->_config, $list->as_array());

                    }

                } else {

                    // Dispara uma exceção de erro

                    throw new \Woss\Config\Exception ( \Woss\Config\Exception :: MESCLE_FAIL );

                }

            }

        } else {

            // Dispara uma exceção de erro

            throw new \Woss\Config\Exception ( \Woss\Config\Exception :: READ_ONLY );

        }

    }

    /**
     * Mescla uma lista de configuração armazendando em um grupo
     *
     * @param   array | Config      $list       Lista de configuração a ser mesclada
     * @param   string              $group      Nome do grupo
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function merge_as_group ($list, $group) {

        // Verifica se a lista é apenas leitura

        if ( ! $this->_is_set_flag(self::READ_ONLY) ) {

            // Verifica se a lista é válida

            if ( (is_array($list) && $this->_is_associative_array($list) || ($list instanceof \Woss\Config) || ($list instanceof \Woss\Config\Ini) || ($list instanceof \Woss\Config\Php)) ) {

                // Verifica se o item já está definido

                if ( ! $this->is_set($group) ) $this->set($group, array());

                // Recupera a referência ao item

                $item =& $this->_get_item($group);

                // Verifica se é instância de Config

                if ( $list instanceof Config ) {

                    // Mescla as configurações com as novas

                    $item = array_merge($item, $list->return_as_array());

                } else {

                    // Mescla as configurações com as novas

                    $item = array_merge($item, $list);

                }

            } else {

                // Dispara uma exceção de erro

                throw new \Woss\Config\Exception ( \Woss\Config\Exception :: MESCLE_FAIL );

            }

        } else {

            // Dispara uma exceção de erro

            throw new \Woss\Config\Exception ( \Woss\Config\Exception :: READ_ONLY );

        }

    }

    /**
     * Copia um item ou grupo de configuração para outro
     *
     * @param   string      $source         Nome do item ou grupo de configuração de origem
     * @param   string      $destination    Nome do item ou grupo de configuração de destino
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function copy ($source, $destination) {

        // Copia o valor de um item em outro

        $this->set($destination, $this->get($source));

    }

    /**
     * Cria um atalho para ou item ou grupo de configuração
     *
     * @param   string      $name       Nome do item ou grupo de configuração
     * @param   string      $shortcut   Nome do atalho
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function shortcut ($name, $shortcut) {

        // Cria um atalho na lista

        $this->_shortcuts[$shortcut] = $name;

    }

    /**
     * Verifica se determinada string é atalho para um item ou grupo de configuração
     *
     * @param   string      $shortcut   Nome do atalho a ser validado
     * @return  boolean
     * @access  public
     * @access  v1.0.0
     */

    public function is_shortcut ($shortcut) {

        // Verifica se determinado atalho está definido

        return array_key_exists($shortcut, $this->_shortcuts);

    }

    /**
     * Retorna a lista de itens de configuração em forma de array
     *
     * @return  array
     * @access  public
     * @since   v1.0.0
     */

    public function as_array () {

        // Retorna a lista de itens de configuração

        return $this->_config;

    }

    /**
     * Retorna o item de iteração atual
     *
     * @return  mixed
     * @access  public
     * @since   v1.0.0
     */

    public function current () {

        // Retorna o item corrente

        return current($this->_config);

    }

    /**
     * Retorna o índice do item de iteração atual
     *
     * @return  integer
     * @access  public
     * @since   v1.0.0
     */

    public function key () {

        // Retorna a chave do índice corrente

        return key($this->_config);

    }

    /**
     * Move o ponteiro de iteração ao próximo elemento
     *
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function next () {

        // Move o ponteiro ao próximo item

        next($this->_config);
        ++$this->_index;

    }

    /**
     * Move o ponteiro de iteração ao início da lista
     *
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function rewind () {

        // Reinicia a iteração, movendo o ponteiro ao início da lista

        reset($this->_config);
        $this->_index = 0;

    }

    /**
     * Verifica se há mais itens durante a iteração
     *
     * @return  boolean
     * @access  public
     * @since   v1.0.0
     */

    public function valid () {

        // Verifica se há mais itens na iteração

        return ($this->_index < count($this->_config));

    }

    /**
     * Verifica se determinado item de configuração está definido
     *
     * @param   string      $name       Nome do item de configuração
     * @return  boolean
     * @access  public
     * @since   v1.0.0
     */

    public function offsetExists ($name) {

        // Verifica se determinado item está definido

        return $this->is_set($name);

    }

    /**
     * Retorna o valor de um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @return  mixed
     * @access  public
     * @since   v1.0.0
     */

    public function offsetGet ($name) {

        // Retorna o valor de um item de configuração

        return $this->get($name, FALSE);

    }

    /**
     * Define o valor de um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @param   mixed       $value      Valor do item
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function offsetSet ($name, $value) {

        // Define o valor de um item de configuração

        $this->set($name, $value);

    }

    /**
     * Exclui um item de configuração
     *
     * @param   string      $name       Nome do item de configuração
     * @return  void
     * @access  public
     * @since   v1.0.0
     */

    public function offsetUnset ($name) {

        // Exclui um item de configuração

        $this->delete($name);

    }

    /**
     * Retorna a referência a um item de configuração. Se o item não existir, este é, então, criado
     *
     * @param   string      $name       Nome do item de configuração
     * @return  mixed
     * @access  protected
     * @since   v1.0.0
     * @final
     */

    final protected function & _get_item ($name) {

        // Recupera a referência ao início da lista de itens

        $config =& $this->_config;

        // Percorre os grupos do item

        foreach (array_map("trim", explode('.', $name)) as $group) {

            // Verifica se o grupo está definido

            if ( ! array_key_exists($group, $config) ) $config[$group] = array();

            // Move a lista ao sub-grupo

            $config =& $config[$group];

        }

        // Returna a referência ao item

        return $config;

    }

    /**
     * Verifica se uma array é da forma associativa
     *
     * @param   array       $array      Array a ser validada
     * @return  boolean
     * @access  protected
     * @since   v1.0.0
     * @final
     */

    final protected function _is_associative_array (array $array) {

        // Percorre a array

        foreach ($array as $key => $value) {

            // Verifica se a chave corrente é do tipo inteiro

            if ( is_integer($key) ) {

                // Retorna falso

                return FALSE;

            }

        }

        // Retorna verdadeiro

        return TRUE;

    }

}