## 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:

       $application=new TApplication($configFile);
       $application->run();

- since: 3.0
- version: $Id: TApplication.php 2578 2008-12-01 22:50:15Z carlgmathisen $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /TApplication.php (line 112)

    TComponent
       |
       --TApplication

Direct descendents

Class | Description
--- | ---
TShellApplication | TShellApplication class.

Class Constant Summary
CONFIGCACHE_FILE = 'config.cache'
CONFIG_FILE = 'application.xml'
CONFIG_FILE_EXT = '.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
TApplication __construct ([string $basePath = 'protected'], [boolean $cacheConfig = true])
void applyConfiguration (TApplicationConfiguration $config, [boolean $withinService = false])
void clearGlobalState (string $key)
void completeRequest ()
void flushOutput ()
IStatePersister getApplicationStatePersister ()
TAssetManager getAssetManager ()
TAuthorizationRuleCollection getAuthorizationRules ()
string getBasePath ()
ICache getCache ()
string getConfigurationFile ()
TErrorHandler getErrorHandler ()
TGlobalization getGlobalization ([boolean $createIfNotExists = true])
mixed getGlobalState (string $key, [mixed $defaultValue = null])
string getID ()
TApplicationMode getMode ()
IModule getModule (mixed $id)
array getModules ()
string getPageServiceID ()
TMap getParameters ()
THttpRequest getRequest ()
boolean getRequestCompleted ()
THttpResponse getResponse ()
string getRuntimePath ()
TSecurityManager getSecurityManager ()
IService getService ()
THttpSession getSession ()
string getUniqueID ()
IUser getUser ()
void initApplication (string 0, string 1)
void loadGlobals ()
void onAuthentication ()
void onAuthenticationComplete ()
void onAuthorization ()
void onAuthorizationComplete ()
void onBeginRequest ()
void onEndRequest ()
void onError (mixed $param)
void onLoadState ()
void onLoadStateComplete ()
void onPreFlushOutput ()
void onPreRunService ()
void onSaveState ()
void onSaveStateComplete ()
void resolvePaths (string $basePath)
void run ()
void runService ()
void saveGlobals ()
void setApplicationStatePersister (IStatePersister $persister)
void setAssetManager (TAssetManager $value)
void setBasePath (string $value)
void setCache (ICache $cache)
void setConfigurationFile (string $value)
void setErrorHandler (TErrorHandler $handler)
void setGlobalization (TGlobalization $glob)
void setGlobalState (string $key, mixed $value, [mixed $defaultValue = null])
void setID (string $value)
void setMode (TApplicationMode $value)
void setModule (string $id, IModule $module)
void setPageServiceID (string $value)
void setRequest (THttpRequest $request)
void setResponse (THttpResponse $response)
void setRuntimePath (string $value)
void setSecurityManager (TSecurityManager $sm)
void setService (IService $value)
void setSession (THttpSession $session)
void setUser (IUser $user)
void startService (string $serviceID)
Methods
Constructor __construct (line 295)

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.

- access: public
- throws: TConfigurationException if configuration file cannot be read or the runtime path is invalid.

TApplication __construct ([string $basePath = 'protected'], [boolean $cacheConfig = true])

- 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.

applyConfiguration (line 856)

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 448)

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 398)

Completes current request processing.

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

- access: public

void completeRequest ()
flushOutput (line 1129)

Flushes output to client side.

- access: public

void flushOutput ()
getApplicationStatePersister (line 772)

- return: application state persister
- access: public

IStatePersister getApplicationStatePersister ()
getAssetManager (line 751)

- return: asset manager
- access: public

TAssetManager getAssetManager ()
getAuthorizationRules (line 844)

- return: list of authorization rules for the current request
- access: public

TAuthorizationRuleCollection getAuthorizationRules ()
getBasePath (line 537)

- return: the directory containing the application configuration file (absolute path)
- access: public

string getBasePath ()
getCache (line 793)

- return: the cache module, null if cache module is not installed
- access: public

ICache getCache ()
getConfigurationFile (line 553)

- return: the application configuration file (absolute path)
- access: public

string getConfigurationFile ()
getErrorHandler (line 709)

- return: the error handler module
- access: public

TErrorHandler getErrorHandler ()
getGlobalization (line 826)

- return: globalization module
- access: public

TGlobalization getGlobalization ([boolean $createIfNotExists = true])

- boolean $createIfNotExists: whether to create globalization if it does not exist

getGlobalState (line 419)

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 481)

- return: application ID
- access: public

string getID ()
getMode (line 521)

- return: application mode. Defaults to TApplicationMode::Debug.
- access: public

TApplicationMode getMode ()
getModule (line 619)

- return: the module with the specified ID, null if not found
- access: public

IModule getModule (mixed $id)
getModules (line 627)

- return: list of loaded application modules, indexed by module IDs
- access: public

array getModules ()
getPageServiceID (line 497)

- return: page service ID
- access: public

string getPageServiceID ()
getParameters (line 638)

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 646)

- return: the request module
- access: public

THttpRequest getRequest ()
getRequestCompleted (line 406)

- return: whether the current request is processed.
- access: public

boolean getRequestCompleted ()
getResponse (line 667)

- return: the response module
- access: public

THttpResponse getResponse ()
getRuntimePath (line 569)

- return: the directory storing cache data and application-level persistent data. (absolute path)
- access: public

string getRuntimePath ()
getSecurityManager (line 730)

- return: the security manager module
- access: public

TSecurityManager getSecurityManager ()
getService (line 589)

- return: the currently requested service
- access: public

IService getService ()
getSession (line 688)

- return: the session module, null if session module is not installed
- access: public

THttpSession getSession ()
getUniqueID (line 513)

- return: an ID that uniquely identifies this Prado application from the others
- access: public

string getUniqueID ()
getUser (line 809)

- return: the application user
- access: public

IUser getUser ()
initApplication (line 940)

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.

- access: protected
- throws: TConfigurationException if module is redefined of invalid type, or service not defined or of invalid type

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 460)

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 1029)

Raises OnAuthentication event.

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

- access: public

void onAuthentication ()
onAuthenticationComplete (line 1038)

Raises OnAuthenticationComplete event.

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

- access: public

void onAuthenticationComplete ()
onAuthorization (line 1047)

Raises OnAuthorization event.

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

- access: public

void onAuthorization ()
onAuthorizationComplete (line 1056)

Raises OnAuthorizationComplete event.

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

- access: public

void onAuthorizationComplete ()
onBeginRequest (line 1020)

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 1138)

Raises OnEndRequest event.

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

- access: public

void onEndRequest ()
onError (line 1006)

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 1065)

Raises OnLoadState event.

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

- access: public

void onLoadState ()
onLoadStateComplete (line 1075)

Raises OnLoadStateComplete event.

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

- access: public

void onLoadStateComplete ()
onPreFlushOutput (line 1121)

Raises OnPreFlushOutput event.

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

- access: public

void onPreFlushOutput ()
onPreRunService (line 1084)

Raises OnPreRunService event.

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

- access: public

void onPreRunService ()
onSaveState (line 1102)

Raises OnSaveState event.

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

- access: public

void onSaveState ()
onSaveStateComplete (line 1112)

Raises OnSaveStateComplete event.

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

- access: public

void onSaveStateComplete ()
resolvePaths (line 323)

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.

- access: protected
- see: TApplication::setConfigurationFile()
- see: TApplication::setRuntimePath()
- see: TApplication::setBasePath()

void resolvePaths (string $basePath)

- string $basePath: the application root path or the application configuration file

run (line 366)

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:

- TShellApplication::run() : Runs the application.

runService (line 1092)

Runs the requested service.

- access: public

void runService ()
saveGlobals (line 469)

Saves global values into persistent storage.

This method is invoked when OnSaveState event is raised.

- access: protected

void saveGlobals ()
setApplicationStatePersister (line 785)

- access: public

void setApplicationStatePersister (IStatePersister $persister)

- IStatePersister $persister: application state persister

setAssetManager (line 764)

- access: public

void setAssetManager (TAssetManager $value)

- TAssetManager $value: asset manager

setBasePath (line 545)

- access: public

void setBasePath (string $value)

- string $value: the directory containing the application configuration file

setCache (line 801)

- access: public

void setCache (ICache $cache)

- ICache $cache: the cache module

setConfigurationFile (line 561)

- access: public

void setConfigurationFile (string $value)

- string $value: the application configuration file (absolute path)

setErrorHandler (line 722)

- access: public

void setErrorHandler (TErrorHandler $handler)

- TErrorHandler $handler: the error handler module

setGlobalization (line 836)

- access: public

void setGlobalization (TGlobalization $glob)

- TGlobalization $glob: globalization module

setGlobalState (line 433)

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])

- 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

setID (line 489)

- access: public

void setID (string $value)

- string $value: application ID

setMode (line 529)

- access: public

void setMode (TApplicationMode $value)

- TApplicationMode $value: application mode

setModule (line 608)

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 505)

- access: public

void setPageServiceID (string $value)

- string $value: page service ID

setRequest (line 659)

- access: public

void setRequest (THttpRequest $request)

- THttpRequest $request: the request module

setResponse (line 680)

- access: public

void setResponse (THttpResponse $response)

- THttpRequest $response: the request module

setRuntimePath (line 577)

- access: public

void setRuntimePath (string $value)

- string $value: the directory storing cache data and application-level persistent data. (absolute path)

setSecurityManager (line 743)

- access: public

void setSecurityManager (TSecurityManager $sm)

- TSecurityManager $sm: the security manager module

setService (line 597)

- access: public

void setService (IService $value)

- IService $value: the currently requested service

setSession (line 701)

- access: public

void setSession (THttpSession $session)

- THttpSession $session: the session module

setUser (line 817)

- access: public

void setUser (IUser $user)

- IUser $user: the application user

startService (line 971)

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::__get()
> TComponent::__set()

Class Constants
CONFIGCACHE_FILE = 'config.cache' (line 142)

Config cache file

CONFIG_FILE = 'application.xml' (line 130)

Application configuration file name

CONFIG_FILE_EXT = '.xml' (line 134)

File extension for external config files

GLOBAL_FILE = 'global.cache' (line 146)

Global data file

PAGE_SERVICE_ID = 'page' (line 126)

Page service ID

RUNTIME_PATH = 'runtime' (line 138)

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 Sun, 11 Jan 2009 20:16:39 -0500 by phpDocumentor 1.3.0RC4