Class TApplication

Description

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 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 Mode property (in the application configuration file).

  • Off mode will prevent the application from serving user requests.
  • Debug 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.
  • Normal 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.
  • Performance mode is similar to Normal 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 completeRequest.

Examples:

  • Create and run a Prado application:
    1.  $application=new TApplication($configFile);
    2.  $application->run();

  • author: Qiang Xue <qiang.xue@gmail.com>
  • version: $Id: TApplication.php 3151 2012-05-29 09:52:51Z ctrlaltca $
  • since: 3.0

Located in /TApplication.php (line 112)

TComponent
   |
   --TApplication
Direct descendents
Class Description
TShellApplication TShellApplication class.
Class Constant Summary
 CONFIGCACHE_FILE = 'config.cache'
 CONFIG_FILE_PHP = 'application.php'
 CONFIG_FILE_XML = 'application.xml'
 CONFIG_TYPE_PHP = 'php'
 CONFIG_TYPE_XML = 'xml'
 GLOBAL_FILE = 'global.cache'
 PAGE_SERVICE_ID = 'page'
 RUNTIME_PATH = 'runtime'
 STATE_DEBUG = 'Debug'
 STATE_NORMAL = 'Normal'
 STATE_OFF = 'Off'
 STATE_PERFORMANCE = 'Performance'
Method Summary
void applyConfiguration (TApplicationConfiguration $config, [boolean $withinService = false])
void clearGlobalState (string $key)
void completeRequest ()
TApplication __construct ([string $basePath = 'protected'], [boolean $cacheConfig = true], [ $configType = self::CONFIG_TYPE_XML])
void flushOutput ([boolean $continueBuffering = true])
string getBasePath ()
TGlobalization getGlobalization ([boolean $createIfNotExists = true])
mixed getGlobalState (string $key, [mixed $defaultValue = null])
string getID ()
IModule getModule ( $id)
array getModules ()
string getPageServiceID ()
boolean getRequestCompleted ()
string getRuntimePath ()
string getUniqueID ()
void initApplication (string 0, string 1)
void loadGlobals ()
void onAuthorization ()
void onBeginRequest ()
void onEndRequest ()
void onError (mixed $param)
void onLoadState ()
void onPreRunService ()
void onSaveState ()
void resolvePaths (string $basePath)
void run ()
void runService ()
void saveGlobals ()
void setAssetManager ( $value)
void setBasePath (string $value)
void setCache (ICache $cache)
void setConfigurationFile (string $value)
void setConfigurationType (string $value)
void setErrorHandler ( $handler)
void setGlobalization ( $glob)
void setGlobalState (string $key, mixed $value, [mixed $defaultValue = null], [boolean $forceSave = false])
void setID (string $value)
void setMode (TApplicationMode $value)
void setModule (string $id, IModule $module)
void setPageServiceID (string $value)
void setRequest ( $request)
void setResponse ( $response)
void setRuntimePath (string $value)
void setSecurityManager ( $sm)
void setService (IService $value)
void setSession ( $session)
void setUser (IUser $user)
void startService (string $serviceID)
Methods
applyConfiguration (line 946)

Applies an application configuration.

  • access: public
void applyConfiguration (TApplicationConfiguration $config, [boolean $withinService = false])
  • TApplicationConfiguration $config: the configuration
  • boolean $withinService: whether the configuration is specified within a service.
clearGlobalState (line 475)

Clears a global value.

The value cleared will no longer be available in this request and the following requests.

  • access: public
void clearGlobalState (string $key)
  • string $key: the name of the value to be cleared
completeRequest (line 422)

Completes current request processing.

This method can be used to exit the application lifecycles after finishing the current cycle.

  • access: public
void completeRequest ()
Constructor __construct (line 319)

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 protected directory under the directory containing the current running script.

  • throws: TConfigurationException if configuration file cannot be read or the runtime path is invalid.
  • access: public
TApplication __construct ([string $basePath = 'protected'], [boolean $cacheConfig = true], [ $configType = self::CONFIG_TYPE_XML])
  • string $basePath: 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 application.xml will be looked for. If found, the file is considered as the application configuration file.
  • boolean $cacheConfig: whether to cache application configuration. Defaults to true.
  • $configType
flushOutput (line 1224)

Flushes output to client side.

  • access: public
void flushOutput ([boolean $continueBuffering = true])
  • boolean $continueBuffering: whether to continue buffering after flush if buffering was active
getApplicationConfigurationClass (line 936)
  • access: protected
void getApplicationConfigurationClass ()
getApplicationStatePersister (line 854)
  • return: application state persister
  • access: public
IStatePersister getApplicationStatePersister ()
getAssetManager (line 833)
  • return: asset manager
  • access: public
TAssetManager getAssetManager ()
getAuthorizationRules (line 929)
  • return: list of authorization rules for the current request
  • access: public
TAuthorizationRuleCollection getAuthorizationRules ()
getBasePath (line 564)
  • return: the directory containing the application configuration file (absolute path)
  • access: public
string getBasePath ()
getCache (line 875)
  • return: the cache module, null if cache module is not installed
  • access: public
ICache getCache ()
getConfigurationFile (line 580)
  • return: the application configuration file (absolute path)
  • access: public
string getConfigurationFile ()
getConfigurationFileExt (line 612)
  • return: the applictaion configuration type. default is 'xml'
  • access: public
string getConfigurationFileExt ()
getConfigurationFileName (line 631)
  • return: the default configuration file name
  • access: public
string getConfigurationFileName ()
getConfigurationType (line 596)
  • return: the application configuration file (absolute path)
  • access: public
string getConfigurationType ()
getErrorHandler (line 791)
  • return: the error handler module
  • access: public
TErrorHandler getErrorHandler ()
getGlobalization (line 908)
  • return: globalization module
  • access: public
TGlobalization getGlobalization ([boolean $createIfNotExists = true])
  • boolean $createIfNotExists: whether to create globalization if it does not exist
getGlobalState (line 443)

Returns a global value.

A global value is one that is persistent across users sessions and requests.

  • return: the global value corresponding to $key
  • access: public
mixed getGlobalState (string $key, [mixed $defaultValue = null])
  • string $key: the name of the value to be returned
  • mixed $defaultValue: the default value. If $key is not found, $defaultValue will be returned
getID (line 508)
  • return: application ID
  • access: public
string getID ()
getMode (line 548)
  • return: application mode. Defaults to TApplicationMode::Debug.
  • access: public
TApplicationMode getMode ()
getModule (line 701)
  • return: the module with the specified ID, null if not found
  • access: public
IModule getModule ( $id)
  • $id
getModules (line 709)
  • return: list of loaded application modules, indexed by module IDs
  • access: public
array getModules ()
getPageServiceID (line 524)
  • return: page service ID
  • access: public
string getPageServiceID ()
getParameters (line 720)

Returns the list of application parameters.

Since the parameters are returned as a TMap object, you may use the returned result to access, add or remove individual parameters.

  • return: the list of application parameters
  • access: public
TMap getParameters ()
getRequest (line 728)
  • return: the request module
  • access: public
THttpRequest getRequest ()
getRequestCompleted (line 430)
  • return: whether the current request is processed.
  • access: public
boolean getRequestCompleted ()
getResponse (line 749)
  • return: the response module
  • access: public
THttpResponse getResponse ()
getRuntimePath (line 651)
  • return: the directory storing cache data and application-level persistent data. (absolute path)
  • access: public
string getRuntimePath ()
getSecurityManager (line 812)
  • return: the security manager module
  • access: public
TSecurityManager getSecurityManager ()
getService (line 671)
  • return: the currently requested service
  • access: public
IService getService ()
getSession (line 770)
  • return: the session module, null if session module is not installed
  • access: public
THttpSession getSession ()
getUniqueID (line 540)
  • return: an ID that uniquely identifies this Prado application from the others
  • access: public
string getUniqueID ()
getUser (line 891)
  • return: the application user
  • access: public
IUser getUser ()
initApplication (line 1031)

Loads configuration and initializes application.

Configuration file will be read and parsed (if a valid cached version exists, it will be used instead). Then, modules are created and initialized; Afterwards, the requested service is created and initialized.

  • throws: TConfigurationException if module is redefined of invalid type, or service not defined or of invalid type
  • access: protected
void initApplication (string 0, string 1)
  • string 0: configuration file path (absolute or relative to current executing script)
  • string 1: cache file path, empty if no present or needed
loadGlobals (line 487)

Loads global values from persistent storage.

This method is invoked when OnLoadState event is raised. After this method, values that are stored in previous requests become available to the current request via getGlobalState.

  • access: protected
void loadGlobals ()
onAuthentication (line 1123)

Raises OnAuthentication event.

This method is invoked when the user request needs to be authenticated.

  • access: public
void onAuthentication ()
onAuthenticationComplete (line 1132)

Raises OnAuthenticationComplete event.

This method is invoked right after the user request is authenticated.

  • access: public
void onAuthenticationComplete ()
onAuthorization (line 1141)

Raises OnAuthorization event.

This method is invoked when the user request needs to be authorized.

  • access: public
void onAuthorization ()
onAuthorizationComplete (line 1150)

Raises OnAuthorizationComplete event.

This method is invoked right after the user request is authorized.

  • access: public
void onAuthorizationComplete ()
onBeginRequest (line 1114)

Raises OnBeginRequest event.

At the time when this method is invoked, application modules are loaded and initialized, user request is resolved and the corresponding service is loaded and initialized. The application is about to start processing the user request.

  • access: public
void onBeginRequest ()
onEndRequest (line 1233)

Raises OnEndRequest event.

This method is invoked when the application completes the processing of the request.

  • access: public
void onEndRequest ()
onError (line 1100)

Raises OnError event.

This method is invoked when an exception is raised during the lifecycles of the application.

  • access: public
void onError (mixed $param)
  • mixed $param: event parameter
onLoadState (line 1159)

Raises OnLoadState event.

This method is invoked when the application needs to load state (probably stored in session).

  • access: public
void onLoadState ()
onLoadStateComplete (line 1169)

Raises OnLoadStateComplete event.

This method is invoked right after the application state has been loaded.

  • access: public
void onLoadStateComplete ()
onPreFlushOutput (line 1215)

Raises OnPreFlushOutput event.

This method is invoked right before the application flushes output to client.

  • access: public
void onPreFlushOutput ()
onPreRunService (line 1178)

Raises OnPreRunService event.

This method is invoked right before the service is to be run.

  • access: public
void onPreRunService ()
onSaveState (line 1196)

Raises OnSaveState event.

This method is invoked when the application needs to save state (probably stored in session).

  • access: public
void onSaveState ()
onSaveStateComplete (line 1206)

Raises OnSaveStateComplete event.

This method is invoked right after the application state has been saved.

  • access: public
void onSaveStateComplete ()
resolvePaths (line 347)

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.

void resolvePaths (string $basePath)
  • string $basePath: the application root path or the application configuration file
run (line 390)

Executes the lifecycles of the application.

This is the main entry function that leads to the running of the whole Prado application.

  • access: public
void run ()

Redefined in descendants as:
runService (line 1186)

Runs the requested service.

  • access: public
void runService ()
saveGlobals (line 496)

Saves global values into persistent storage.

This method is invoked when OnSaveState event is raised.

  • access: protected
void saveGlobals ()
setApplicationStatePersister (line 867)
  • access: public
void setApplicationStatePersister (IStatePersister $persister)
setAssetManager (line 846)
  • access: public
void setAssetManager ( $value)
setBasePath (line 572)
  • access: public
void setBasePath (string $value)
  • string $value: the directory containing the application configuration file
setCache (line 883)
  • access: public
void setCache (ICache $cache)
  • ICache $cache: the cache module
setConfigurationFile (line 588)
  • access: public
void setConfigurationFile (string $value)
  • string $value: the application configuration file (absolute path)
setConfigurationType (line 604)
  • access: public
void setConfigurationType (string $value)
  • string $value: the application configuration type. 'xml' and 'php' are valid values
setErrorHandler (line 804)
  • access: public
void setErrorHandler ( $handler)
setGlobalization (line 921)
  • access: public
void setGlobalization ( $glob)
setGlobalState (line 458)

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.

  • access: public
void setGlobalState (string $key, mixed $value, [mixed $defaultValue = null], [boolean $forceSave = false])
  • string $key: the name of the value to be set
  • mixed $value: the global value to be set
  • mixed $defaultValue: the default value. If $key is not found, $defaultValue will be returned
  • boolean $forceSave: wheter to force an immediate GlobalState save. defaults to false
setID (line 516)
  • access: public
void setID (string $value)
  • string $value: application ID
setMode (line 556)
  • access: public
void setMode (TApplicationMode $value)
setModule (line 690)

Adds a module to application.

Note, this method does not do module initialization.

  • access: public
void setModule (string $id, IModule $module)
  • string $id: ID of the module
  • IModule $module: module object
setPageServiceID (line 532)
  • access: public
void setPageServiceID (string $value)
  • string $value: page service ID
setRequest (line 741)
  • access: public
void setRequest ( $request)
setResponse (line 762)
  • access: public
void setResponse ( $response)
setRuntimePath (line 659)
  • access: public
void setRuntimePath (string $value)
  • string $value: the directory storing cache data and application-level persistent data. (absolute path)
setSecurityManager (line 825)
  • access: public
void setSecurityManager ( $sm)
setService (line 679)
  • access: public
void setService (IService $value)
  • IService $value: the currently requested service
setSession (line 783)
  • access: public
void setSession ( $session)
setUser (line 899)
  • access: public
void setUser (IUser $user)
  • IUser $user: the application user
startService (line 1062)

Starts the specified service.

The service instance will be created. Its properties will be initialized and the configurations will be applied, if any.

  • access: public
void startService (string $serviceID)
  • string $serviceID: service ID

Inherited Methods

Inherited From TComponent

TComponent::addParsedObject()
TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::createdOnTemplate()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__call()
TComponent::__get()
TComponent::__set()
TComponent::__sleep()
TComponent::__wakeup()
Class Constants
CONFIGCACHE_FILE = 'config.cache' (line 158)

Config cache file

CONFIG_FILE_EXT_PHP = '.php' (line 146)

File extension for external config files

CONFIG_FILE_EXT_XML = '.xml' (line 134)

File extension for external config files

CONFIG_FILE_PHP = 'application.php' (line 142)

Application configuration file name

CONFIG_FILE_XML = 'application.xml' (line 130)

Application configuration file name

CONFIG_TYPE_PHP = 'php' (line 150)

Configuration file type, application.php and config.php

CONFIG_TYPE_XML = 'xml' (line 138)

Configuration file type, application.xml and config.xml

GLOBAL_FILE = 'global.cache' (line 162)

Global data file

PAGE_SERVICE_ID = 'page' (line 126)

Page service ID

RUNTIME_PATH = 'runtime' (line 154)

Runtime directory name

STATE_DEBUG = 'Debug' (line 119)
STATE_NORMAL = 'Normal' (line 120)
STATE_OFF = 'Off' (line 118)

possible application mode.

  • deprecated: deprecated since version 3.0.4 (use TApplicationMode constants instead)
STATE_PERFORMANCE = 'Performance' (line 121)

Documentation generated on Mon, 25 Jun 2012 14:37:17 +0200 by phpDocumentor 1.4.3