root/trunk/framework/TApplication.php

<?php
/**
 * TApplication class file
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.pradosoft.com/
 * @copyright Copyright &copy; 2005-2008 PradoSoft
 * @license http://www.pradosoft.com/license/
 * @version $Id$
 * @package System
 */

/**
 * Includes core interfaces essential for TApplication class
 */
require_once(PRADO_DIR.'/interfaces.php');

/**
 * Includes core classes essential for TApplication class
 */
Prado::using('System.TApplicationComponent');
Prado::using('System.TModule');
Prado::using('System.TService');
Prado::using('System.Exceptions.TErrorHandler');
Prado::using('System.Caching.TCache');
Prado::using('System.IO.TTextWriter');
Prado::using('System.Collections.TList');
Prado::using('System.Collections.TMap');
Prado::using('System.Collections.TStack');
Prado::using('System.Xml.TXmlDocument');
Prado::using('System.Security.TAuthorizationRule');
Prado::using('System.Security.TSecurityManager');
Prado::using('System.Web.THttpUtility');
Prado::using('System.Web.Javascripts.TJavaScript');
Prado::using('System.Web.THttpRequest');
Prado::using('System.Web.THttpResponse');
Prado::using('System.Web.THttpSession');
Prado::using('System.Web.Services.TPageService');
Prado::using('System.Web.TAssetManager');
Prado::using('System.I18N.TGlobalization');

/**
 * TApplication class.
 *
 * TApplication coordinates modules and services, and serves as a configuration
 * context for all Prado components.
 *
 * TApplication uses a configuration file to specify the settings of
 * the application, the modules, the services, the parameters, and so on.
 *
 * TApplication adopts a modular structure. A TApplication instance is a composition
 * of multiple modules. A module is an instance of class implementing
 * {@link IModule} interface. Each module accomplishes certain functionalities
 * that are shared by all Prado components in an application.
 * There are default modules and user-defined modules. The latter offers extreme
 * flexibility of extending TApplication in a plug-and-play fashion.
 * Modules cooperate with each other to serve a user request by following
 * a sequence of lifecycles predefined in TApplication.
 *
 * TApplication has four modes that can be changed by setting {@link setMode Mode}
 * property (in the application configuration file).
 * - <b>Off</b> mode will prevent the application from serving user requests.
 * - <b>Debug</b> mode is mainly used during application development. It ensures
 *   the cache is always up-to-date if caching is enabled. It also allows
 *   exceptions are displayed with rich context information if they occur.
 * - <b>Normal</b> mode is mainly used during production stage. Exception information
 *   will only be recorded in system error logs. The cache is ensured to be
 *   up-to-date if it is enabled.
 * - <b>Performance</b> mode is similar to <b>Normal</b> mode except that it
 *   does not ensure the cache is up-to-date.
 *
 * TApplication dispatches each user request to a particular service which
 * finishes the actual work for the request with the aid from the application
 * modules.
 *
 * TApplication maintains a lifecycle with the following stages:
 * - [construct] : construction of the application instance
 * - [initApplication] : load application configuration and instantiate modules and the requested service
 * - onBeginRequest : this event happens right after application initialization
 * - onAuthentication : this event happens when authentication is needed for the current request
 * - onAuthenticationComplete : this event happens right after the authentication is done for the current request
 * - onAuthorization : this event happens when authorization is needed for the current request
 * - onAuthorizationComplete : this event happens right after the authorization is done for the current request
 * - onLoadState : this event happens when application state needs to be loaded
 * - onLoadStateComplete : this event happens right after the application state is loaded
 * - onPreRunService : this event happens right before the requested service is to run
 * - runService : the requested service runs
 * - onSaveState : this event happens when application needs to save its state
 * - onSaveStateComplete : this event happens right after the application saves its state
 * - onPreFlushOutput : this event happens right before the application flushes output to client side.
 * - flushOutput : the application flushes output to client side.
 * - onEndRequest : this is the last stage a request is being completed
 * - [destruct] : destruction of the application instance
 * Modules and services can attach their methods to one or several of the above
 * events and do appropriate processing when the events are raised. By this way,
 * the application is able to coordinate the activities of modules and services
 * in the above order. To terminate an application before the whole lifecycle
 * completes, call {@link completeRequest}.
 *
 * Examples:
 * - Create and run a Prado application:
 * <code>
 * $application=new TApplication($configFile);
 * $application->run();
 * </code>
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id$
 * @package System
 * @since 3.0
 */
class TApplication extends TComponent
{
    /**
     * possible application mode.
     * @deprecated deprecated since version 3.0.4 (use TApplicationMode constants instead)
     */
    const STATE_OFF='Off';
    const STATE_DEBUG='Debug';
    const STATE_NORMAL='Normal';
    const STATE_PERFORMANCE='Performance';

    /**
     * Page service ID
     */
    const PAGE_SERVICE_ID='page';
    /**
     * Application configuration file name
     */
    const CONFIG_FILE='application.xml';
    /**
     * File extension for external config files
     */
    const CONFIG_FILE_EXT='.xml';
    /**
     * Runtime directory name
     */
    const RUNTIME_PATH='runtime';
    /**
     * Config cache file
     */
    const CONFIGCACHE_FILE='config.cache';
    /**
     * Global data file
     */
    const GLOBAL_FILE='global.cache';

    /**
     * @var array list of events that define application lifecycles
     */
    private static $_steps=array(
        'onBeginRequest',
        'onLoadState',
        'onLoadStateComplete',
        'onAuthentication',
        'onAuthenticationComplete',
        'onAuthorization',
        'onAuthorizationComplete',
        'onPreRunService',
        'runService',
        'onSaveState',
        'onSaveStateComplete',
        'onPreFlushOutput',
        'flushOutput'
    );

    /**
     * @var string application ID
     */
    private $_id;
    /**
     * @var string unique application ID
     */
    private $_uniqueID;
    /**
     * @var boolean whether the request is completed
     */
    private $_requestCompleted=false;
    /**
     * @var integer application state
     */
    private $_step;
    /**
     * @var array available services and their configurations indexed by service IDs
     */
    private $_services;
    /**
     * @var IService current service instance
     */
    private $_service;
    /**
     * @var array list of application modules
     */
    private $_modules=array();
    /**
     * @var TMap list of application parameters
     */
    private $_parameters;
    /**
     * @var string configuration file
     */
    private $_configFile;
    /**
     * @var string application base path
     */
    private $_basePath;
    /**
     * @var string directory storing application state
     */
    private $_runtimePath;
    /**
     * @var boolean if any global state is changed during the current request
     */
    private $_stateChanged=false;
    /**
     * @var array global variables (persistent across sessions, requests)
     */
    private $_globals=array();
    /**
     * @var string cache file
     */
    private $_cacheFile;
    /**
     * @var TErrorHandler error handler module
     */
    private $_errorHandler;
    /**
     * @var THttpRequest request module
     */
    private $_request;
    /**
     * @var THttpResponse response module
     */
    private $_response;
    /**
     * @var THttpSession session module, could be null
     */
    private $_session;
    /**
     * @var ICache cache module, could be null
     */
    private $_cache;
    /**
     * @var IStatePersister application state persister
     */
    private $_statePersister;
    /**
     * @var IUser user instance, could be null
     */
    private $_user;
    /**
     * @var TGlobalization module, could be null
     */
    private $_globalization;
    /**
     * @var TSecurityManager security manager module
     */
    private $_security;
    /**
     * @var TAssetManager asset manager module
     */
    private $_assetManager;
    /**
     * @var TAuthorizationRuleCollection collection of authorization rules
     */
    private $_authRules;
    /**
     * @var TApplicationMode application mode
     */
    private $_mode=TApplicationMode::Debug;

    /**
     * Constructor.
     * Sets application base path and initializes the application singleton.
     * Application base path refers to the root directory storing application
     * data and code not directly accessible by Web users.
     * By default, the base path is assumed to be the <b>protected</b>
     * directory under the directory containing the current running script.
     * @param string application base path or configuration file path.
     *        If the parameter is a file, it is assumed to be the application
     *        configuration file, and the directory containing the file is treated
     *        as the application base path.
     *        If it is a directory, it is assumed to be the application base path,
     *        and within that directory, a file named <b>application.xml</b>
     *        will be looked for. If found, the file is considered as the application
     *        configuration file.
     * @param boolean whether to cache application configuration. Defaults to true.
     * @throws TConfigurationException if configuration file cannot be read or the runtime path is invalid.
     */
    public function __construct($basePath='protected',$cacheConfig=true)
    {
        // register application as a singleton
        Prado::setApplication($this);

        $this->resolvePaths($basePath);

        if($cacheConfig)
            $this->_cacheFile=$this->_runtimePath.DIRECTORY_SEPARATOR.self::CONFIGCACHE_FILE;

        // generates unique ID by hashing the runtime path
        $this->_uniqueID=md5($this->_runtimePath);
        $this->_parameters=new TMap;
        $this->_services=array(self::PAGE_SERVICE_ID=>array('TPageService',array(),null));
        Prado::setPathOfAlias('Application',$this->_basePath);
    }

    /**
     * Resolves application-relevant paths.
     * This method is invoked by the application constructor
     * to determine the application configuration file,
     * application root path and the runtime path.
     * @param string the application root path or the application configuration file
     * @see setBasePath
     * @see setRuntimePath
     * @see setConfigurationFile
     */
    protected function resolvePaths($basePath)
    {
        // determine configuration path and file
        if(empty($basePath) || ($basePath=realpath($basePath))===false)
            throw new TConfigurationException('application_basepath_invalid',$basePath);
        if(is_file($basePath.DIRECTORY_SEPARATOR.self::CONFIG_FILE))
            $configFile=$basePath.DIRECTORY_SEPARATOR.self::CONFIG_FILE;
        else if(is_file($basePath))
        {
            $configFile=$basePath;
            $basePath=dirname($configFile);
        }
        else
            $configFile=null;

        // determine runtime path
        $runtimePath=$basePath.DIRECTORY_SEPARATOR.self::RUNTIME_PATH;
        if(is_writable($runtimePath))
        {
            if($configFile!==null)
            {
                $runtimePath.=DIRECTORY_SEPARATOR.basename($configFile).'-'.Prado::getVersion();
                if(!is_dir($runtimePath))
                {
                    if(@mkdir($runtimePath)===false)
                        throw new TConfigurationException('application_runtimepath_failed',$runtimePath);
                    @chmod($runtimePath, PRADO_CHMOD); //make it deletable
                }
                $this->setConfigurationFile($configFile);
            }
            $this->setBasePath($basePath);
            $this->setRuntimePath($runtimePath);
        }
        else
            throw new TConfigurationException('application_runtimepath_invalid',$runtimePath);

    }

    /**
     * Executes the lifecycles of the application.
     * This is the main entry function that leads to the running of the whole
     * Prado application.
     */
    public function run()
    {
        try
        {
            $this->initApplication();
            $n=count(self::$_steps);
            $this->_step=0;
            $this->_requestCompleted=false;
            while($this->_step<$n)
            {
                if($this->_mode===self::STATE_OFF)
                    throw new THttpException(503,'application_unavailable');
                if($this->_requestCompleted)
                    break;
                $method=self::$_steps[$this->_step];
                Prado::trace("Executing $method()",'System.TApplication');
                $this->$method();
                $this->_step++;
            }
        }
        catch(Exception $e)
        {
            $this->onError($e);
        }
        $this->onEndRequest();
    }

    /**
     * Completes current request processing.
     * This method can be used to exit the application lifecycles after finishing
     * the current cycle.
     */
    public function completeRequest()
    {
        $this->_requestCompleted=true;
    }

    /**
     * @return boolean whether the current request is processed.
     */
    public function getRequestCompleted()
    {
        return $this->_requestCompleted;
    }

    /**
     * Returns a global value.
     *
     * A global value is one that is persistent across users sessions and requests.
     * @param string the name of the value to be returned
     * @param mixed the default value. If $key is not found, $defaultValue will be returned
     * @return mixed the global value corresponding to $key
     */
    public function getGlobalState($key,$defaultValue=null)
    {
        return isset($this->_globals[$key])?$this->_globals[$key]:$defaultValue;
    }

    /**
     * Sets a global value.
     *
     * A global value is one that is persistent across users sessions and requests.
     * Make sure that the value is serializable and unserializable.
     * @param string the name of the value to be set
     * @param mixed the global value to be set
     * @param mixed the default value. If $key is not found, $defaultValue will be returned
     */
    public function setGlobalState($key,$value,$defaultValue=null)
    {
        $this->_stateChanged=true;
        if($value===$defaultValue)
            unset($this->_globals[$key]);
        else
            $this->_globals[$key]=$value;
    }

    /**
     * Clears a global value.
     *
     * The value cleared will no longer be available in this request and the following requests.
     * @param string the name of the value to be cleared
     */
    public function clearGlobalState($key)
    {
        $this->_stateChanged=true;
        unset($this->_globals[$key]);
    }

    /**
     * Loads global values from persistent storage.
     * This method is invoked when {@link onLoadState OnLoadState} event is raised.
     * After this method, values that are stored in previous requests become
     * available to the current request via {@link getGlobalState}.
     */
    protected function loadGlobals()
    {
        $this->_globals=$this->getApplicationStatePersister()->load();
    }

    /**
     * Saves global values into persistent storage.
     * This method is invoked when {@link onSaveState OnSaveState} event is raised.
     */
    protected function saveGlobals()
    {
        if($this->_stateChanged)
        {
            $this->_stateChanged=false;
            $this->getApplicationStatePersister()->save($this->_globals);
        }
    }

    /**
     * @return string application ID
     */
    public function getID()
    {
        return $this->_id;
    }

    /**
     * @param string application ID
     */
    public function setID($value)
    {
        $this->_id=$value;
    }

    /**
     * @return string an ID that uniquely identifies this Prado application from the others
     */
    public function getUniqueID()
    {
        return $this->_uniqueID;
    }

    /**
     * @return TApplicationMode application mode. Defaults to TApplicationMode::Debug.
     */
    public function getMode()
    {
        return $this->_mode;
    }

    /**
     * @param TApplicationMode application mode
     */
    public function setMode($value)
    {
        $this->_mode=TPropertyValue::ensureEnum($value,'TApplicationMode');
    }

    /**
     * @return string the directory containing the application configuration file (absolute path)
     */
    public function getBasePath()
    {
        return $this->_basePath;
    }

    /**
     * @param string the directory containing the application configuration file
     */
    public function setBasePath($value)
    {
        $this->_basePath=$value;
    }

    /**
     * @return string the application configuration file (absolute path)
     */
    public function getConfigurationFile()
    {
        return $this->_configFile;
    }

    /**
     * @param string the application configuration file (absolute path)
     */
    public function setConfigurationFile($value)
    {
        $this->_configFile=$value;
    }

    /**
     * @return string the directory storing cache data and application-level persistent data. (absolute path)
     */
    public function getRuntimePath()
    {
        return $this->_runtimePath;
    }

    /**
     * @param string the directory storing cache data and application-level persistent data. (absolute path)
     */
    public function setRuntimePath($value)
    {
        $this->_runtimePath=$value;
    }

    /**
     * @return IService the currently requested service
     */
    public function getService()
    {
        return $this->_service;
    }

    /**
     * @param IService the currently requested service
     */
    public function setService($value)
    {
        $this->_service=$value;
    }

    /**
     * Adds a module to application.
     * Note, this method does not do module initialization.
     * @param string ID of the module
     * @param IModule module object
     */
    public function setModule($id,IModule $module)
    {
        if(isset($this->_modules[$id]))
            throw new TConfigurationException('application_moduleid_duplicated',$id);
        else
            $this->_modules[$id]=$module;
    }

    /**
     * @return IModule the module with the specified ID, null if not found
     */
    public function getModule($id)
    {
        return isset($this->_modules[$id])?$this->_modules[$id]:null;
    }

    /**
     * @return array list of loaded application modules, indexed by module IDs
     */
    public function getModules()
    {
        return $this->_modules;
    }

    /**
     * Returns the list of application parameters.
     * Since the parameters are returned as a {@link TMap} object, you may use
     * the returned result to access, add or remove individual parameters.
     * @return TMap the list of application parameters
     */
    public function getParameters()
    {
        return $this->_parameters;
    }

    /**
     * @return THttpRequest the request module
     */
    public function getRequest()
    {
        if(!$this->_request)
        {
            $this->_request=new THttpRequest;
            $this->_request->init(null);
        }
        return $this->_request;
    }

    /**
     * @param THttpRequest the request module
     */
    public function setRequest(THttpRequest $request)
    {
        $this->_request=$request;
    }

    /**
     * @return THttpResponse the response module
     */
    public function getResponse()
    {
        if(!$this->_response)
        {
            $this->_response=new THttpResponse;
            $this->_response->init(null);
        }
        return $this->_response;
    }

    /**
     * @param THttpRequest the request module
     */
    public function setResponse(THttpResponse $response)
    {
        $this->_response=$response;
    }

    /**
     * @return THttpSession the session module, null if session module is not installed
     */
    public function getSession()
    {
        if(!$this->_session)
        {
            $this->_session=new THttpSession;
            $this->_session->init(null);
        }
        return $this->_session;
    }

    /**
     * @param THttpSession the session module
     */
    public function setSession(THttpSession $session)
    {
        $this->_session=$session;
    }

    /**
     * @return TErrorHandler the error handler module
     */
    public function getErrorHandler()
    {
        if(!$this->_errorHandler)
        {
            $this->_errorHandler=new TErrorHandler;
            $this->_errorHandler->init(null);
        }
        return $this->_erro