<?php

/*
 * Framework SuperObject
 *
 * The Framework SuperObject is a class implemented using the singleton 
 * design pattern which allows custom libraries to be written and be 
 * "loaded" and made available throughout the entire site in a simple and 
 * intuitive manner.
 *
 * @package     FrameworkSuperObject
 * @author      Alan Briolat <alan@codescape.net>
 * @copyright   Copyright (c) 2007, Alan Briolat
 * @license     http://www.gnu.org/copyleft/gpl.html
 * @link        http://www.codeigniter.net/projects/ystv/fso
 */

// ------------------------------------------------------------------------

/**
 * Constants
 */
define('FSO_BASEDIR', dirname(__FILE__));

/**
 * Get FSO instance
 *
 * @return      FSO
 */
function &get_instance()
{
    return FSO::get_instance();
}

// ------------------------------------------------------------------------

/**
 * Framework SuperObject Singleton Class
 */
class FSO
{
    private static $_instance = null;
    private static $_modules = array();

    //  {{{ constructor

    /**
     * Class constructor
     *
     * Constructor cannot be used from outside of the class - use 
     * FSO::get_instance() instead
     *
     * @return      void
     */
    protected function __construct()
    {
        
    }

    //  }}}
    //  {{{ public static function __get( $module )
    
    /**
     * Get module
     *
     * Overload __get() so that $FSO->somemodule actually uses the relevant 
     * module.  To assign the module to a variable, use:
     *      $mymodule =& FSO::$modulename;
     * or
     *      $mymodule =& $FSO->modulename;
     *
     * @param       string      $module
     * @return      Object
     */

    public static function __get( $module )
    {
        $module = strtolower($module);
        if ( array_key_exists($module, self::$_modules) )
        {
            return self::$_modules[$module];
        }
        else
        {
            trigger_error("Module '$module' not loaded!", E_USER_WARNING);
            return null;
        }
    }

    //  }}}
    //  {{{ public static function &get_instance()

    /**
     * Get class instance
     *
     * Use this instead of instantiating the class:
     *      $FSO =& FSO::get_instance();
     *
     * @return      FSO
     */
    public static function &get_instance()
    {
        //  Create the instance if it doesn't exist
        if ( is_null(self::$_instance) )
        {
            self::$_instance = new FSO();
        }

        return self::$_instance;
    }

    //  }}}
    //  {{{ public static function &load_module( $class [, $alias [, $basedir]] )

    /**
     * Load a module
     *
     * Load a module by class name.  If the class is not already defined this
     * function will try and find it at $basedir/$class.php.  If the module has
     * already been loaded into the superobject it will be ignored.
     *
     * By default the new module will be found at $FSO->classname - use the 
     * $alias parameter to give the module a different name when loaded - this
     * allows the same module to be loaded multiple times if necessary.
     *
     * Returns a reference to the module just loaded (or the existing one if it
     * was already loaded).
     *
     * @param       string      $class
     * @param       array       $args
     * @param       string      $alias
     * @param       string      $basedir
     * @return      Object
     */
    public static function &load_module( $module, $args = null, $alias = null, $basedir = FSO_BASEDIR )
    {
        //  By default module variable name is same as module name
        $alias = is_null($alias) ? strtolower($module) : strtolower($alias);
        $args = empty($args) ? array() : $args;

        //  Check if the module is loaded already
        if ( !array_key_exists($alias, self::$_modules) )
        {
            self::load_class($module, $basedir);
            $ref = new ReflectionClass($module);
            self::$_modules[$alias] = $ref->newInstanceArgs($args);
        }

        //  Return the module
        return self::$_modules[$alias];
    }

    //  }}}
    //  {{{ public static function load_modules( $modules )

    /**
     * Load multiple modules
     *
     * Load all modules specified in an array.  Array elements correspond
     * exactly to args to load_module().
     *
     * @param       array       $modules
     * @return      void
     */
    public static function load_modules( array $modules )
    {
        foreach ( $modules as $module )
        {
            call_user_func_array(array('FSO', 'load_module'), $module);
        }
    }

    //  }}}
    //  {{{ public static function make_module( $module [, $args [, $basedir]] )

    /**
     * Make a module object
     *
     * Load a module, instantiate it and return it without making it part of the
     * superobject.  The advantage to this compared to just using 'new Module()' 
     * is that this handles loading the file and making sure the class exists 
     * first.
     *
     * @param       string      $module
     * @param       string      $basedir
     * @return      Object
     */
    public static function make_module( $module, $args = null, $basedir = FSO_BASEDIR )
    {
        $args = empty($args) ? array() : $args;
        self::load_class($module, $basedir);
        $ref = new ReflectionClass($module);
        return $ref->newInstanceArgs($args);
    }

    //  }}}
    //  {{{ public static function &get_module( $alias )

    /**
     * Get a module
     *
     * Return a reference to an already-loaded module if it exists.  Use this if
     * you want to get to a single module without having an reference to the FSO
     * object.
     *      FSO::get_module('mymodule');
     * An alternative to 
     *      FSO::get_instance()->mymodule;
     *
     * @param       string      $module
     * @return      Object
     */
    public static function &get_module( $module )
    {
        $module = strtolower($module);
        if ( array_key_exists($module, self::$_modules) )
        {
            return self::$_modules[$module];
        }
        else
        {
            trigger_error("Module '$module' is not loaded!", E_USER_WARNING);
            return null;
        }
    }

    //  }}}
    //  {{{ private static function load_class( $class [, $basedir] )

    /**
     * Load a class
     *
     * Helper function to try everything possible to get a class loaded if it's 
     * not loaded already
     *
     * @param       string      $class
     * @param       string      $basedir
     * @return      void
     */
    private static function load_class( $class, $basedir = FSO_BASEDIR )
    {
        $class = strtolower($class);
        $path = rtrim($basedir, '/')."/$class.php";


        //  Only do something if the class isn't defined yet
        if ( !class_exists($class) )
        {
            //  If the file exists load it
            if ( file_exists($path) )
            {
                include_once($path);
            }

            //  ... and check to see if that file defined the class!
            if ( !class_exists($class) )
            {
                trigger_error("Module '$class' could not be found - "
                    . "please check that it is defined and/or that it "
                    . "exists at '$path'", E_USER_ERROR);
            }
        }
    }

    //  }}}
}

// ------------------------------------------------------------------------

/**
 * Framework SuperObject Module Class
 *
 * This class should not be instantiated directly.  It should be extended by
 * classes that are to be loaded as modules, to give access to all the other
 * modules with the simple $this->module syntax.
 *
 * Remember to call parent::__construct() in the constructor of the subclass!
*/
abstract class FSO_Module
{
    protected $FSO = null;

    //  {{{ constructor

    /**
     * Constructor
     *
     * Get the FSO object so it can be used by the class and its subclasses
     *
     * @return      void
     */
    public function __construct()
    {
        $this->FSO =& FSO::get_instance();
    }

    //  }}}
    //  {{{ public function __get( $module )

    /**
     * Get module
     *
     * Overload __get() so that requests for $this->somemodule get passed to 
     * the underlying FSO object
     *
     * @param       string      $module
     * @return      Object
     */
    public function __get( $module )
    {
        return $this->FSO->$module;
    }

    //  }}}
}

// ------------------------------------------------------------------------

/**
 * Franework SuperObject Database Module Class
 *
 * This class duplicates all of the abilities of FSO_Module above, however it
 * extends the PDO class so that database functions can be accessed from 
 * module->function directly.
 */

abstract class FSO_DB_Module extends PDO
{
    protected $FSO = null;

    //  {{{ constructor

    /**
     * Constructor
     *
     * Get the FSO object so it can be used by the class and its subclasses
     *
     * @return      void
     */
    public function __construct($dsn, $user, $pass)
    {
        $this->FSO =& FSO::get_instance();
        parent::__construct($dsn, $user, $pass);
        $this->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_WARNING);
        $this->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('FSO_DB_Statement'));
    }

    //  }}}
    //  {{{ public function query( $query [, $param1 [, $param2] ...] )

    /**
     * Use prepared statements
     *
     * Make all queries safe - overhead of single prepared statements is 
     * negligible so use them for single queries.  Parameters passed do not
     * need to be escaped.
     *
     * @return      FSO_DB_Statement
     */
    public function query()
    {
        $args = func_get_args();
        $query = array_shift($args);
        $stmt = $this->prepare($query);
        $stmt->execute($args);
        return $stmt;
    }

    //  }}}
}

// ------------------------------------------------------------------------

/**
 * Franework SuperObject Database Statement Class
 *
 * This extends PDOStatment so that we can add some nice stuff to it
 */

class FSO_DB_Statement extends PDOStatement
{
    /**
     * Returns an array with 2 elements:
     *
     *      'data'  => array of rows as associative arrays (fieldname => value)
     *      'rowcount'  => number of rows in the result set
     */
    public function fetchAllRows()
    {
        $ret = array();
        $ret['data'] = $this->fetchAll(PDO::FETCH_ASSOC);
        $ret['rowcount'] = count($ret['data']);
        $ret['numrows'] = $ret['rowcount'];
        return $ret;
    }
}

?>