root/trunk/lib/casco/class.casco.php

<?php

/**
 * Casco: the factory class
 *
 * This class is responsible for bootstrapping the framework, managing
 * core strategies and registration/lookup of modules. It also has
 * control over the connection pool, instantiating new connection
 * objects on demand.
 *
 * Furthermore it is the place where all PHP language extensions (like
 * dynamic variables/context pattern and dynamic class
 * replacement/subclassing) are collected.
 *
 * @todo This is truly "the class that knew too much". We should
 *    separate some responsibilities into other classes.
 *
 * @package casco
 */
class casco extends module
{
        private static $MODULES     = array();
        private static $SUBCLASSES  = array();
        private static $COMPONENTS  = array();
        private static $CONNECTIONS = array();
        private static $CONTEXT     = array();
        private static $CONTEXT_NESTING = 0;
        
        static $finder;
        static $translator;
        static $cache;
        static $url;
        static $templator; 
        static $composer;
        static $automator;
        static $bouncer;

        /** The document root (on disk) of the CASCO application */
        static $docroot;
        /** The HTTP root (an URL) of the CASCO application */
        static $httproot;
        /**
         * Use {@link http://wush.net/trac/casco/wiki/Metasync
         * metasync}?  This is the global setting, which may be
         * overridden for individual connections.
         *
         * @see casco::register_connection()
         */
        static $metasync = true;

        /**
         * Enable caching?
         *
         * @todo Perhaps make this a static var of the cache class?
         */
        static $caching = true;
        
        /**
         * Show debugging info?
         *
         * @todo Remove this; it's silly to have one giant switch
         * that affects *all* components that might have something
         * to say for debugging.  Typically you're only interested
         * in debugging info of one particular component/module.
         */
        static $debug = false;
        
        ///////////////////////////////////////////////////////////
        // initialization
        ///////////////////////////////////////////////////////////

        /**
         * Initialize the CASCO framework.
         *
         * This causes all the bootstrapping to be performed that is
         * required for a fully working Casco.
         *
         * Steps that are undertaken include the following:
         * 1. All core strategy classes are instantiated in their
         *     vanilla implementations.
         * 2. For each registered module, the {@link module::subclassing()}
         *     function is invoked.
         * 3. Strategies are re-instantiated with (possibly) new implementations
         *     as determined by the subclassing() functions.
         * 4. For each registered module, the {@link module::init()}
         *     function is invoked.
         * 5. Finally, shutdown functions are registered.
         */
        static function init()
        {
                        // Start with vanilla classes (with one exception)
                self::$finder     = new finder();
                self::$cache      = new cache(self::$caching);
                self::$finder     = new finder_cached();        //it is better for performance to use the finder_cached as soon as possible. That's the reason why it is in core.
                self::$translator = new translator();
                self::$url        = new url();
                self::$templator  = new templator();
                self::$composer   = new composer();
                self::$automator  = new automator();
                self::$bouncer    = new bouncer();

                foreach (self::get_registered_modules() as $mod)
                {
                        $mod_class = self::get_module_class($mod['module']);
                        if ($mod_class) $mod_class::subclassing();
                }
                
                        //initialize the cache
                self::$cache = lib::create('cache', array(self::$caching));

                        //replace the vanilla finder with the one we REALLY want according to the configuration
                self::$finder = lib::create('finder', array(false));
                
                        //initialize the translator class
                self::$translator = lib::create('translator');
                
                        //initialize the url class
                self::$url = lib::create('url');
                $_GET = self::$url->decode($_GET);
                
                        //initialize the templator (template engine) class
                self::$templator = lib::create('templator');

                        //initialize the composer (composition engine) class
                self::$composer = lib::create('composer', array(self::composer()->get_overrides()));
                
                self::$automator = lib::create('automator');

                self::$bouncer = lib::create('bouncer');
                
                foreach (self::get_registered_modules() as $mod)
                {
                        $mod_class = self::get_module_class($mod['module']);
                        if ($mod_class) $mod_class::init();
                }
                register_shutdown_function(array('controller', 'destroy_expired_form_cookies'));
        }

        
        ///////////////////////////////////////////////////////////
        // db connections
        ///////////////////////////////////////////////////////////

        /**
         * Register a database connection in the CASCO connection pool.
         *
         * A connection configuration is an associative array with options
         * for the connection.  The following keys are mandatory:
         *
         * - <code>$config['class']</code>: The class that will be
         *    instantiated when the connection is requested with
         *    {@link casco::get_connection()}
         *
         * The following keys are optional:
         * - <code>$config['name']</code>: The name of the connection,
         *    used with {@link casco::get_connection()} to get the connection.
         * - <code>$config['instance']</code>: A pre-instantiated
         *    object to use for managing the connection.  If it does
         *    not exist, the class is automatically instantiated when
         *    the connection is first requested.
         *
         * NOTE: Do not use this function directly!
         * For user code, it is advisable to register connections
         * through the module class of the module that manages the
         * connection. This will allow the module to set some useful
         * defaults before registering the connection with the CASCO
         * connection pool.
         *
         * @param array $config The configuration for this connection.
         */
        static function register_connection($config)
        {
                $config = self::get_config_defaults($config);
                self::$CONNECTIONS[$config['name']] = $config;
        }

        /**
         * Set the defaults for a connection configuration.
         *
         * @param array $config The input config.
         * @return array The config with optionally added keys.
         */
        protected static function get_config_defaults($config)
        {
                if(!isset($config['name']))
                {
                        $config['name'] = 'default';
                }
                return $config;
        }

        /**
         * Retrieve a connection from the connection pool by name.
         *
         * If the connection was not yet established, the connection
         * managing class is instantiated (establishing a new connection)
         * and this object is returned. Otherwise, a pre-existing
         * connection manager is recycled.
         *
         * @param string $name (optional, defaults to 'default') The name of
         *                     the connection to retrieve.
         * @return mixed The connection object
         */
        static function get_connection($name = 'default')
        {
                if (!isset(self::$CONNECTIONS[$name]))
                {
                        throw new argument_exception('Unknown connection name: "'.$name.'"');
                }
                else if (!isset(self::$CONNECTIONS[$name]['instance']))
                {
                        $classname      = self::$CONNECTIONS[$name]['class'];
                        $config         = self::$CONNECTIONS[$name];
                        self::$CONNECTIONS[$name]['instance'] = lib::create($classname, array($config));
                }
                return self::$CONNECTIONS[$name]['instance'];
        }
        
        ///////////////////////////////////////////////////////////
        // module stuff
        ///////////////////////////////////////////////////////////

        /**
         * Get an instance for all models from all registered modules.
         *
         * @todo Why does this return instances? Why not just names?
         *       If anyone needs an instance, he can just instantiate
         *       these classes himself.
         *
         * @return array A list of instances of all models.
         */
        public static function get_models($module = '')
        {
                $models = array();
                if($module == '')
                {
                        foreach (self::get_registered_modules() as $module)
                        {
                                $models = self::append_models_from_module($models, $module);
                        }
                }
                else 
                {
                        $models = self::append_models_from_module($models, $module);
                }
                return $models;
        }

        /**
         * Find all models in the given module.
         *
         * @param array $models  The models found up till now.
         * @param string $module The name of the module to look in.
         * @return array The models found up till now, including this module.
         */
        static private function append_models_from_module($models, $module)
        {
                $filepath = self::get_local_path($module) . '/model/';
                if(is_dir($filepath))
                {
                        $d = dir($filepath);
                        while (false !== ($entry = $d->read())) 
                        {
                                if(is_dir($filepath.$entry) && $entry != '.' && $entry != '..' && $entry != '.svn')
                                {
                                                //models can have their own subdirectories, in which exists class.foobar.php
                                        $subd = dir($filepath.$entry);
                                        while (false !== ($subentry = $subd->read())) 
                                        {
                                                $model = self::get_model_by_path_name($filepath.$entry.'/', $subentry);
                                                if($model !== false)
                                                {
                                                        $models[] = $model;     
                                                }
                                        }
                                        $subd->close();                 
                                }
                                else 
                                {
                                                //models can be defined in files such as class.foobar.php inside the models directory
                                        $model = self::get_model_by_path_name($filepath, $entry);
                                        if($model !== false)
                                        {
                                                $models[] = $model;     
                                        }
                                }
                        }
                        $d->close();                    
                }
                return $models;
        }

        /**
         * Given a pathname, determine the model, load it and instantiate it.
         *
         * @param string $filepath The path to the model file.
         * @param string $name     The name of the model file.
         * @return An instance of that model.
         */
        static private function get_model_by_path_name($filepath, $name)
        {
                if(is_file($filepath.$name))
                {
                        $modelname_array = explode('.', $name);
                        if($modelname_array[0] == 'class')
                        {
                                self::require_model('model');
                                $modelbase = new ReflectionClass('model');
                                
                                require_once($filepath.$name);
                                $modelname = $modelname_array[1];
                                $modelreflection = new ReflectionClass($modelname);
                                if($modelreflection->isSubclassOf($modelbase))
                                {
                                        return new $modelname();                        
                                }
                        }
                }
                return false;
        }

        /**
         * Register a module.
         *
         * @param string $module The name of the module to register
         * @param string $localpath The path to the module directory
         *     on disk.  The name will be appended to this, so
         *     $localpath.$module is the directory in which will be looked
         *     for classes and assets etc.  Defaults to  casco::$docroot.'/lib'
         * @param string $remotepath The path to the module directory
         *     over HTTP. Same semantics as $localpath. Defaults to
         *     casco::$httproot.'/lib'.
         * @param string $dir The directory name of the module, if this
         *     differs from the name of the module. This is the name that
         *     will be appended to $localpath and $remotepath.
         */
        static function register_module($module, $localpath = '', $remotepath = '', $dir = '')
        {
                $config = array();
                $config['module'] = $module;
                
                        //if a containing path is specified, store it, else store defaults
                if($localpath != '')
                {
                        $config['local_path'] = $localpath;
                        $config['remote_path'] = $remotepath;
                }
                else
                {
                        $config['local_path'] = casco::$docroot.'lib/';
                        $config['remote_path'] = casco::$httproot.'lib/';
                }
                        //if the module directory is specified store it, else store the default (the module name itself)
                if($dir == '')
                {
                        $config['dir'] = $module;
                }
                else
                {
                        $config['dir'] = $dir;
                }
                if (!is_dir($config['local_path'].$config['dir']))
                {
                        throw new casco_exception('Could not find module "'.$module.'". Expected it in dir "'.$config['dir'].'" under "'.$config['local_path'].'". Check your config!');
                }
                        //store the module configuration data in the casco modules array
                self::$MODULES[$module] = $config;
                
                if (file_exists($config['local_path'].$config['dir'].'/init.php'))
                {
                        require_once($config['local_path'].$config['dir'].'/init.php');
                }
        }

        /**
         * Register a module only for a test.
         *
         * This is useful when a module has some test models or other
         * classes that it needs to load just for its tests, but not
         * in regular operation.
         *
         * The name of the module is determined by appending the name
         * of the test to the string 'module_'.
         *
         * Example: If you're in the test class file
         * <code>foo_module/model/my_model/test/class.test_my_model.php</code>
         * you can call
         * <code>register_test_module('foo_module', 'model', 'my_model')</code>
         * and it will load
         * <code>foo_module/model/my_model/test/module_test_my_model</code>
         *
         * Note that it is possible to load a test module from the test for
         * another class.
         *
         * @todo We don't need the parent_module arg because we can
         *     look up the test class, whose path looks like this:
         *     <casco_local_path>/<parent_module>/<classtype>/<classname>/test/test_<classname>
         *     Strip out casco_local_path and take the remaining first
         *     path component.
         *
         * @param string $parent_module The module in which the test
         *     lives.
         * @param string $classtype The major CASCO classtype of the
         *     class you are testing.
         * @param string $name The name of the class you are testing.
         */
        static function register_test_module($parent_module, $classtype, $name)
        {
                $dir = self::get_test_dir($classtype, $name);
                $module = 'module_test_'.$name;
                return self::register_module($module, casco::get_local_path($parent_module).$dir, casco::get_remote_path($parent_module).$dir);
        }

        /**
         * Get the name of the module class for the named module.
         *
         * @param string $module The name of the module you want
         *     to load the class from.
         *
         * @return string|false The name of the module class, or false
         *     if the named module has no module class.
         *
         * @see casco::register_module_class()
         */
        static function get_module_class($module)
        {
                if (isset(self::$MODULES[$module]['class']))
                {
                        return self::$MODULES[$module]['class'];
                }
                else
                {
                        return false;
                }
        }

        /**
         * Register the module class for a given module.
         *
         * You must call this function in your module's
         * <code>init.php</code> if you define a module class there.
         *
         * It is advised to name your module classes
         * <code>mod_foo</code>, if the module name is
         * <code>foo</code>. In the future, this may be enforced
         * automatically in code.
         *
         * @param string $module The name of the module.
         * @param string $class  The name of the module class.
         */
        static function set_module_class($module, $class)
        {
                self::$MODULES[$module]['class'] = $class;
        }

        /**
         * Retrieve a list of all registered modules.
         *
         * @return array The names of the registered modules.
         */
        static function get_registered_modules()
        {
                return self::$MODULES;
        }

        /**
         * Check if the named module has been registered.
         *
         * @param string $module The name of the module to check.
         * @return boolean True if the module was registered, false if not.
         */
        static function is_registered($module)
        {
                if(isset(self::$MODULES[$module])) 
                {
                        return true;
                }
                else
                {
                        return false;
                }
        }

        /**
         * Get the module configuration array for a module.
         *
         * The array contains the following entries:
         * - 'local_path': The local path (on-disk) to the module,
         *    excluding the module name itself.
         * - 'remote_path': The remote path (HTTP) to the module,
         *    excluding the module name itself.
         * - 'dir': The directory name of the module.
         *
         * @param string $module The name of the module.
         * @return array The configuration.
         *
         * @see casco::register_module()
         */
        protected static function get_module($module)
        {
                $mod = self::$MODULES[$module];
                if (!isset($mod)) throw new argument_exception('Unknown module "'.$module.'"');
                return $mod;
        }

        /**
         * Get the local (on-disk) path to a module's root directory.
         *
         * {@internal If we force all modules to have a module class
         * (or generate one for them on-the-fly if it doesn't have
         * one) we can move these functions to the module's class.
         * the casco class would know less, which is good.}
         *
         * @param string $module The name of the module.
         * @return string The path up to that module's root dir.
         *
         * @see casco::get_remote_path()
         */
        static function get_local_path($module)
        {
                $mod = self::get_module($module);
                return $mod['local_path'].$mod['dir'].'/';
        }

        /**
         * Get the remote (HTTP) path to a module's root directory.
         *
         * @param string $module The name of the module.
         * @return string The URL up to that module's root dir.
         *
         * @see casco::get_local_path()
         */
        static function get_remote_path($module)
        {
                $mod = self::get_module($module);
                return $mod['remote_path'].$mod['dir'].'/';
        }
        
        ///////////////////////////////////////////////////////////
        // Accessors
        ///////////////////////////////////////////////////////////

        /**
         * Retrieve the current implementation for CASCO's {@link cache} strategy.
         *
         * @return cache The cache object.
         */
        static function cache()
        {
                return self::$cache;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link finder} strategy.
         *
         * @return finder The finder object.
         */
        static function finder()
        {
                return self::$finder;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link composer} strategy.
         *
         * @return composer The composer object.
         */
        static function composer()
        {
                return self::$composer;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link templator} strategy.
         *
         * @return templator The templator object.
         */
        static function templator()
        {
                return self::$templator;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link automator} strategy.
         *
         * @return automator The automator object.
         */
        static function automator()
        {
                return self::$automator;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link url} strategy.
         *
         * @return url The url object.
         */
        static function url()
        {
                return self::$url;
        }

        /**
         * Retrieve the current implementation for CASCO's {@link translator} strategy.
         *
         * @return translator The translator object.
         */
        static function translator()
        {
                return self::$translator;
        }
        
        /**
         * Retrieve the current implementation for CASCO's {@link bouncer} strategy.
         *
         * @return bouncer The bouncer object.
         */
        static function bouncer()
        {
                return self::$bouncer;
        }
        
        ///////////////////////////////////////////////////////////
        // global class override (subclass)
        ///////////////////////////////////////////////////////////

        /**
         * Define a class override.
         *
         * Using CASCO's
         * {@link http://wush.net/trac/casco/wiki/CookbookSubclassing
         *  subclassing mechanism}, override a class with another one.
         *
         * Simply put, this means that whenever anyone instantiates or
         * loads a class using {@link model::create()}, {@link lib::create()},
         * {@link model::load()}, {@link lib::load()},
         * or any of the other helper functions for {@link casco::req()}
         * or {@link casco::factory()}, CASCO will load another class
         * of your choice instead.
         *
         * @param $class    The name of the class that will be requested.
         * @param $subclass The name of the class to load instead.
         */
        static function subclass($class, $subclass)
        {
                self::$SUBCLASSES[$class] = $subclass;
        }

        /**
         * Get the real name of the class to load.
         *
         * Given any class name, return the class that would be loaded
         * when this class is requested. Usually it will just return
         * the same name you give as input, but when subclassing is
         * active (see {@link casco::subclass()}), another class name
         * might be returned instead.
         *
         * @param string $name The name of the originally requested class.
         * @return string The name of the class that actually will be loaded.
         */
        static function get_real_classname($name)
        {
                if(isset(self::$SUBCLASSES[$name])) 
                {
                        return self::$SUBCLASSES[$name];
                }
                else 
                {
                        return $name;
                }
        }

        /**
         * Retrieve an associative array of all classes that have been
         * overridden using the subclassing mechanism.
         *
         * @return array The mapping of class name to subclass name.
         *
         * @see casco::subclass()
         */
        static function get_subclasses()
        {
                return self::$SUBCLASSES;
        }
        
        ///////////////////////////////////////////////////////////
        // factory functions
        ///////////////////////////////////////////////////////////
        ///////////////////////////////////////////////////////////

        ///////////////////////////////////////////////////////////
        /// Require functions
        ///////////////////////////////////////////////////////////

        /**
         * Require a class to be loaded.
         *
         * It's recommended to use the convenience functions like
         * {@link lib::load()}, {@link model::load()}
         * etc instead of directly using this function.
         *
         * <b>Always</b> use this function or, better, one of the
         * convenience functions to load CASCO classes.
         * <b>Never</b> use any of the built-in PHP functions like
         * {@link require()} or {@link require_once()} to load CASCO
         * classes. The reason for this is that using this function
         * allows CASCO to invoke its special subclassing system. See
         * {@link casco::subclass()} for more info.
         *
         * Only if you are loading <b>non-CASCO classes</b> from external
         * libraries, you should use {@link require_once()}.
         *
         * @param string $type The major CASCO type of the class to load.
         *     This can be one of 'model', 'controller', 'view',
         *     'lib', 'plugin' or any additional major CASCO types
         *     introduced by a module (for example: 'skin' if
         *     casco_core_skinning is loaded).
         * @param string $name The name of the class to load.
         */
        static function req($name, $type)
        {
                if(!class_exists($name, false)) // class not already loaded?
                {
                        $path = self::$finder->find_class($name, $type);
                        if($path === false)
                                throw(new casco_exception('Could not load given class: '.$name.' of type: '.$type));
                        require_once($path);
                }
        }


        /**
         * Require a test class for another CASCO class to be loaded.
         *
         * This function is slightly different in that it does not
         * require you to pass it the name of the test class, but the
         * name of the class <i>for which you are loading the
         * test</i>.
         *
         * @param $classtype The major CASCO class type of the class for
         *          which we want to load the test.
         * @param $name The name of the class for which we want to load
         *          the test.
         * @param string $name The name of the class to load.
         * @return boolean True if the class was loaded, false if it could
         *     not be found.
         *
         * @todo move this?
         */
        static function require_test($classtype, $name)
        {
                return casco::req('test_'.$name, self::get_test_dir($classtype, $name));
        }
        
        ///////////////////////////////////////////////////////////
        /// Instantiation functions ///
        ///////////////////////////////////////////////////////////
        
        /**
         * Load and instantiate a class.
         *
         * Like {@link casco::req()}, but also instantiate the class.
         *
         * It's recommended to use the convenience functions like
         * {@link lib::create()}, {@link model::create()}
         * etc instead of directly using this function.
         *
         * @param string $type The major CASCO type of the class.
         *
         * @param string $name The name of the class to load.
         *
         * @param array  $arguments A list of arguments to pass to
         *     the constructor of the class. (This is limited to 10
         *     arguments because of technical limitations)
         *
         * @param boolean $allow_subclass Allow casco to substitute
         *     an instance of another class for the requested one,
         *     if one was defined by {@link casco::subclass()}.
         *
         * @return mixed An instance of the requested class.
         * @throws casco_exception if the class could not be found
         *     or instantiated.
         */
        static function factory($name, $type, $arguments = array(), $allow_subclass = true)
        {
                if($allow_subclass === true)
                {
                        $name = casco::get_real_classname($name);
                }

                // We check here for class_exists to avoid the overhead of unneccessarily calling req()
                if (!class_exists($name, false))
                {
                        casco::req($name, $type);
                }

                // A sort call_user_func_array-workalike for constructing objects
                if ($arguments === array()) { // newInstanceArgs doesn't work for 
                        return new $name;
                } else {
                        $rc = new ReflectionClass($name);
                        return $rc->newInstanceArgs($arguments);
                }
                // Alternatively (but slightly slower):
                // return call_user_func_array(array(new ReflectionClass($name), 'newInstance'), $arguments);
        }

        /**
         * Instantiate a test class for another CASCO class.
         *
         * This function is slightly different in that it does not
         * require you to pass it the name of the test class, but the
         * name of the class <i>for which you are loading the
         * test</i>.
         *
         * @param $classtype The major CASCO class type of the class for
         *          which we want to instantiate the test.
         * @param $name The name of the class for which we want to
         *          instantiate the test.
         *
         * @param array  $arguments A list of arguments to pass to
         *     the constructor of the class. (This is limited to 10
         *     arguments because of technical limitations)
         *
         * @param boolean $allow_subclass Allow casco to substitute
         *     an instance of another class for the requested one,
         *     if one was defined by {@link casco::subclass()}.
         *
         * @return mixed An instance of the requested class.
         * @throws casco_exception if the class could not be found
         *     or instantiated.
         *
         * @todo move this?
         */
        static function test($classtype, $name, $arguments = array(), $allow_subclass = true)
        {
                return casco::factory('test_'.$name, self::get_test_dir($classtype, $name), $arguments, $allow_subclass);
        }

        protected static function get_test_dir($classtype, $name)
        {
                return $classtype.'/'.$name.'/test/';
        }

        ///////////////////////////////////////////////////////////
        // Context functions
        ///////////////////////////////////////////////////////////

        /**
         * Call function with modified context.
         *
         * Add or modify keys in the context, then call the given
         * function with the supplied arguments list. When the
         * function returns, the context is restored to what it was
         * before {@link casco::call_with_altered_context()} was invoked.
         *
         * Example:
         * <code>
         * // Assume context for 'foo' was previously set to 'bar'...
         * echo casco::get_context('foo');
         * casco::call_with_altered_context(array('foo' => 'qux'), 'my_func');
         * echo casco::get_context('foo');
         *
         * function my_func()
         * {
         *     echo casco::get_context('foo');
         * }
         * </code>
         * This outputs:
         * <pre>
         * bar
         * qux
         * bar
         * </pre>
         *
         * For more information, please see
         * {@link http://wush.net/trac/casco/wiki/ContextPattern The wiki
         *  page about the "Context Pattern"}.
         *
         * @param array $alterations The new key/value pairs to
         *                            set/add to the context
         * @param string|array $func The function to call, as per {@link call_user_func()}
         * @return mixed The value returned by $func
         */
        static function call_with_altered_context($alterations, $func, $args=array())
        {
                foreach($alterations as $key => $value)
                {
                        if (!isset(self::$CONTEXT[$key]))
                                $old_value = null;  // XXX Fix this! isset() abuse!
                        else
                                $old_value = self::$CONTEXT[$key];
                        self::$CONTEXT[$key] = $value;
                        $alterations[$key] = $old_value;
                }
                try
                {
                        $retval = call_user_func_array($func, $args);
                }
                catch(Exception $e)
                {
                        foreach($alterations as $key => $value)
                        {
                                if (isset($alterations[$key]))
                                        self::$CONTEXT[$key] = $alterations[$key];
                                else
                                        unset(self::$CONTEXT[$key]);
                        }
                        throw($e);
                }
                foreach($alterations as $key => $value)
                {
                        if (isset($alterations[$key]))
                                self::$CONTEXT[$key] = $alterations[$key];
                        else
                                unset(self::$CONTEXT[$key]);
                }
                return $retval;
        }

        /**
         * Get a value from the current context.
         *
         * @param  string $key The name of the value to get.
         * @param  mixed  $default The default value, if context is not set
         * @return mixed  The value stored in the context.
         *                $default if the key has no matching value.
         */
        static function get_context($key, $default=null)
        {
                if(isset(self::$CONTEXT[$key]))
                {
                        return self::$CONTEXT[$key];
                }
                else
                {
                        return $default;
                }
        }

        /**
         * Set a context value in-place.
         *
         * This "leaks out" of the current scope, so be extremely careful in using this.
         *
         * @param  string $key The name of the value to get.
         * @param  mixed  $value The value to set the key to
         */
        static function set_context($key, $value)
        {
                self::$CONTEXT[$key] = $value;
        }
        
        static function debug_context($print = true)
        {
                _debug_array(self::$CONTEXT, $print);
        }

        ///////////////////////////////////////////////////////////
        // Miscellaneous functions
        ///////////////////////////////////////////////////////////

        /**
         * Sort an array using insertion sort.
         *
         * Sort an array using the
         * {@link http://en.wikipedia.org/wiki/Insertion_sort Insertion Sort}
         * algorithm.
         *
         * @param array $array The array to sort.
         * @return array The same array as $array, but sorted.
         */
        static function insertion_sort($array)
        {
                        // Sorts a given array by insertion sort (Decrease and conquer technique)
                for($i = 1; $i < (count($array)+1); $i++)
                {
                        $j = $i-1;
                        if($key == '')
                        {
                                        // sort based on the value
                                while($j >= 0 && $array[$j] > $array[$j+1] && count($array) > $j+1)
                                {
                                                // swap the items
                                        $val = $array[$j];
                                        $array[$j] = $array[$j+1];
                                        $array[$j+1] = $val;
                                        $j--;
                                }                               
                        }
                        else 
                        {
                                        // sort based on a key
                                while($j[$key] >= 0 && $array[$j][$key] > $array[$j+1][$key] && count($array) > $j+1)
                                {
                                                // swap the items
                                        $val = $array[$j];
                                        $array[$j] = $array[$j+1];
                                        $array[$j+1] = $val;
                                        $j--;
                                }                                       
                        }
        
                }
                return $array;
        }

        /**
         * Get the parent class for another class by name.
         *
         * If the class is not known to PHP yet, this loads the file
         * and retries.
         *
         * You should always use this function if you want to know
         * the parent class of a class, because the class may not
         * be loaded yet in some situations.
         *
         * @param string $classtype The major CASCO classtype.
         * @param string $classname The name of the class for which we
         *     want to know the parent.
         * @param string The name of the parent class.
         */
        static function get_parent_class($classtype, $classname)
        {
                if(!class_exists($classname))
                {
                        $deffile = self::$finder->find_class($classname, $classtype, false);
                        if($deffile !== false)
                        {
                                require_once($deffile);
                        }
                }
                return get_parent_class($classname);
        }

        /**
         * Escape a string so that it can be embedded in eval()ed code.
         *
         * Example: casco::php_escape_string('foo\'$bar') => 'foo\\\'$bar'
         * You will need to wrap _single_ (not double!) quotes around this
         * string when you want to eval it (this function mirrors
         * functions like mysql_escape_string, pg_escape_string etc)
         *
         * @param  string $str The string to escape
         * @return string The escaped equivalent of the input string
         */
        static function php_escape_string($str)
        {
                // addslashes also escapes double quotes, which means
                // extra backslashes will creep into the string.
                return str_replace('\\"', '"', addslashes($str));
        }

        /**
         * Redirect to a URL and stop processing.
         *
         * It is highly recommended to use this function and not the
         * default PHP header('Location: '), because this function
         * takes care to discard all output buffers and stop any
         * further processing. This abandons the script.
         *
         * This function is used, for example, in 'permission denied'
         * cases, so that the user does not get to see any output
         * rendered up to the point where it is determined he's not
         * supposed to see anything.
         *
         * @param array $url The URL to redirect to
         * @param array $response_code The HTTP response code to use (default = 302)
         */
        static function redirect($url, $response_code = 302)
        {
                while(ob_get_level() > 0) ob_end_clean();

                if(is_string($url))
                        $url_string = $url;
                else
                        $url_string = url($url);
                header('Location: '.$url_string, true, $response_code);
                die('See <a href="'.$url_string.'">'.$url_string.'</a>');
        }
}

?>