<?php
/**
 * patSession 
 * 
 * $Id: patSession.php 58 2009-06-17 08:18:04Z gerd $
 *
 * @package patSession
 * 
 * @author gERD Schaufelberger <gerd@php-tools.net>
 * @copyright 2004 http://www.php-tools.net
 * @license LGPL
 */
 
/**
 * patSession allows easy access to session values
 * - usable in static or object mode
 * - support for singleton
 *
 * @version 2.2.1
 * @package patSession
 * 
 * @author gERD Schaufelberger <gerd@php-tools.net>
 * @copyright 2004-2006 http://www.php-tools.net
 * @license LGPL
 */
class patSession
{
   /**
    * error definition: session not active
    */                                 
    const ERROR_NOT_ACTIVE = 1;

   /**
    * error definition: could not load driver
    */                                 
    const ERROR_DRIVER_NOT_FOUND = 2;
    
    /**
    * error definition: session not destroyed
    */                                 
    const ERROR_NOT_DESTROYED = 3;

    /*
     * Session States
     */
    const STATE_NEW                 =   'new';
    const STATE_ACTIVE              =   'active';
    const STATE_EXPIRED             =   'expired';
    const STATE_DESTROYED           =   'destroyed';
    const STATE_RESTART             =   'restart';
    const STATE_CLOSED              =   'closed';
    const STATE_REFERER_NOT_ALLOWED =   'referer_not_allowed';
    const STATE_FIX_IP_FAILED       =   'fix_ip_failed';
    const STATE_FIX_BROWSER_FAILED  =   'fix_browser_failed';
    const STATE_TOKEN_MISMATCH      =   'token_mismatch';


   /**
    * storage driver singleton
    * @var object
    */
    static private $_singleton = null;

   /**
    * storage drivers
    * @var array
    */
    static private $_factory = array();

    /**
     * list of include folders
     * @var array
     */
    static private $incDirs =   array();

   /**
    * Singleton
	* create a single instance of patSession driver
	*
	* @static
	* @access public
	* @param string $id name-prefix used for internal storage of session-data
	* @param string $storage named storage driver
	* @param array $options optional parameter passed to the storage driver
	* @return object $session patSession object
	*/
    public static function &singleton( $id = 'session', $storage = 'Native', $options = array() )
    {
        // check whether instance was already created
        if( self::$_singleton ) {
            return self::$_singleton;
        }
        
        // create driver
        $driver	=&	patSession::createDriver( $id, $storage, $options );
        if( patErrorManager::isError( $driver ) ) {
            return $driver;
        }
        
        // remember driver
        self::$_singleton =& $driver;
        
        return $driver;
    }

   /**
	* factory
	* Allows to create multiple instances of patSession
	* Each instance must differ in name of prefix, otherwise this function return a previously created object.
	*
	* @static
	* @access public
	* @param string $id name-prefix used for internal storage of session-data
	* @param string $storage named storage driver
	* @param array $options optional parameter passed to the storage driver
	* @return object $session patSession object
	*/
    public static function &create( $id = 'session', $storage = 'Native', $options = array() )
    {
		// check whether instance was already created
		if( isset( self::$_factory[$storage . '_' . $id] ) ) {
			return self::$_factory[$storage . '_' . $id];
		}
		
		// create driver
		$driver	=&	patSession::createDriver( $id, $storage, $options );
		if( patErrorManager::isError( $driver ) ) {
			return $driver;
		}
		
		// remember driver
		self::$_factory[$storage . '_' . $id]	=& $driver;
		
		return $driver;
    }

    /**
     * load driver and create a instance of it
     *
     * @param string $id session-id
     * @param string $storage named storage-driver
     * @param array $options optional parameter passed to the storage driver
     * @return patSession_Storage
     */
    protected static function &createDriver( $id, $storage, &$options )
    {
        $driver =   ucfirst(  $storage );
        $name   =   'patSession_Storage_' . $storage;
        
        if( !class_exists( 'patSession_Storage', false ) ) {
            include dirname( __FILE__ ) . '/patSession/Storage.php';
        }
        
        if( !class_exists( $name, false ) && !self::includeClass( $driver ) ) {
            // create error! 
            $error =& patErrorManager::raiseError( 'patSession:' . self::ERROR_DRIVER_NOT_FOUND,
                            'Storage driver not found!',
                            'Driver "'. $storage .'" not found - maybe patSession::addIncludeDir() helps.'
                            );
            return $error;
        }
        
        $driver = new $name( $id, $options );
        return $driver;
    }

    /**
     * load patSession class
     * 
     * walk through all include dirs and try to load class
     * 
     * @param string $class
     * @param string $path
     * @return bool true if file was included
     */
    protected static function includeClass( $class, $path = 'Storage' )
    {
        $incDirs    =   self::$incDirs;
        while( $dir = array_pop( $incDirs ) ) {
            $file   =  $dir . '/' . $path . '/' . $class . '.php';
            if( !file_exists( $file  ) ) {
                continue;
            }
            
            require $file;
            return true;
        }
        
        return false;
    }    
    
    /**
     * add include folder
     *
     * Add folder with higher priority to load classes from
     * 
     * @see resetIncludeDir()
     * @param string $dir
     */
    public static function addIncludeDir( $dir )
    {
        self::$incDirs[]    =   $dir;
    }
    
    /**
     * reset list of include dirs
     *
     * Flush include dir array and fill it with a single entry. 
     * By default, patSession's internal include dir is set. 
     * 
     * @param string $dir
     */
    public static function resetIncludeDir( $dir = null )
    {
        self::$incDirs  =   array();
        
        if ( !$dir ) {
            $dir    =   dirname( __FILE__ ) . '/patSession';
        }
        self::addIncludeDir( $dir );
    }
}

// init 
patSession::resetIncludeDir();
?>