1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
<com:TContent ID="body" >
<h1 id="1801">Application Configurations</h1>
<p id="210213" class="block-content">
Application configurations are used to specify the global behavior of an application. They include specification of path aliases, namespace usages, module and service configurations, and parameters.
</p>
<p id="210214" class="block-content">
Configuration for an application is stored in an XML file named <tt>application.xml</tt>, which should be located under the application base path. Its format is shown in the following. Complete specification of application configurations can be found in the <a href="<%~../../../../../docs/specs/application.dtd%>">DTD</a> and <a href="<%~../../../../../docs/specs/application.xsd%>">XSD</a> files.
</p>
<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_210095">
<application PropertyName="PropertyValue" ...>
<paths>
<alias id="AliasID" path="AliasPath" />
<using namespace="Namespace" />
</paths>
<modules>
<module id="ModuleID" class="ModuleClass" PropertyName="PropertyValue" ... />
</modules>
<parameters>
<parameter id="ParameterID" class="ParameterClass" PropertyName="PropertyValue" ... />
</parameters>
<include file="path.to.extconfig" when="PHP expression" />
<services>
<service id="ServiceID" class="ServiceClass" PropertyName="PropertyValue" ... />
</services>
</application>
</com:TTextHighlighter>
<ul id="u1" class="block-content">
<li>The outermost element <tt><application></tt> corresponds to the <tt>TApplication</tt> instance. The <tt>PropertyName="PropertyValue"</tt> pairs specify the initial values for the properties of <tt>TApplication</tt>.</li>
<li>The <tt><paths></tt> element contains the definition of path aliases and the PHP inclusion paths for the application. Each path alias is specified via an <tt><alias></tt> whose <tt>path</tt> attribute takes an absolute path or a path relative to the directory containing the application configuration file. The <tt><using></tt> element specifies a particular path (in terms of namespace) to be appended to the PHP include paths when the application runs. PRADO defines two default aliases: <tt>System</tt> and <tt>Application</tt>. The former refers to the PRADO framework root directory, and the latter refers to the directory containing the application configuration file.</li>
<li>The <tt><modules></tt> element contains the configurations for a list of modules. Each module is specified by a <tt><module></tt> element. Each module is uniquely identified by the <tt>id</tt> attribute and is of type <tt>class</tt>. The <tt>PropertyName="PropertyValue"</tt> pairs specify the initial values for the properties of the module.</li>
<li>The <tt><parameters></tt> element contains a list of application-level parameters that are accessible from anywhere in the application. You may specify component-typed parameters like specifying modules, or you may specify string-typed parameters which take a simpler format as follows,
<com:TTextHighlighter Language="xml" CssClass="source block-content" id="code_210096">
<parameter id="ParameterID" value="ParameterValue" />
</com:TTextHighlighter>
Note, if the <tt>value</tt> attribute is not specified, the whole parameter XML node (of type <tt>TXmlElement</tt>) will be returned as the parameter value. In addition, the <tt>System.Util.TParameterModule</tt> module provides a way to load parameters from an external XML file. See more details in its API documentation.
</li>
<li>The <tt><include></tt> element allows one to include external configuration files. It has been introduced since v3.1.0. The <tt>file</tt> attribute specifies the external configuration file in namespace format. The extension name of the file must be <tt>.xml</tt>. The <tt>when</tt> attribute contains a PHP expression and is optional (defaults to true). Only when the expression evaluates true, will the external configuration file be included. The context of the expression is the application, i.e., <tt>$this</tt> in the expression would refer to the application object.
</li>
<li>The <tt><services></tt> element is similar to the <tt><modules></tt> element. It mainly specifies the services provided by the application. Within a <tt><service></tt> element, one can have any of the above elements. They will be effective only when the corresponding service is being requested.</li>
</ul>
<p id="210215" class="block-content">
An external configuration file has the same format as described above. Although the name of the root element does not matter, it is recommended to be <tt><configuration></tt>. External configurations will append to the main configuration. For example, if a path alias is specified in an external configuration, it will become available in addition to those aliases specified in the main configuration.
</p>
<p id="210216" class="block-content">
By default without explicit configuration, a PRADO application will load a few core modules, such as <tt>THttpRequest</tt>, <tt>THttpResponse</tt>, etc. It will also provide the <tt>TPageService</tt> as a default service. Configuration and usage of these modules and services are covered in individual sections of this tutorial. Note, if your application takes default settings for these modules and service, you do not need to provide an application configuration. However, if these modules or services are not sufficient, or you want to change their behavior by configuring their property values, you will need an application configuration.
</p>
<com:SinceVersion Version="3.2.2" />
<p class="block-content">
By default PRADO instanciates all modules defined in the application configuration at the beginning of the application lifecycle. This can hit the application performance if you have a lot of modules defined but not used at every request.
Since version 3.2.2 you can set the <tt>lazy</tt> property on modules defined in the application configuration to enable the lazy loading of that module.
<com:TTextHighlighter Language="xml" CssClass="source block-content">
<modules>
<module id="ModuleID" class="ModuleClass" lazy="true" PropertyName="PropertyValue" ... />
</modules>
</com:TTextHighlighter>
A module with the <tt>lazy</tt> property set won't be instanciated until the first time it gets actually used by the application:
<com:TTextHighlighter Language="php" CssClass="source block-content">
// requesting the lazy module to the application will instanciate it
Prado::getApplication()->getModule('ModuleID');
</com:TTextHighlighter>
</p>
<com:SinceVersion Version="3.2" />
<p class="block-content">
Since version 3.2 the application configuration can be stored in PHP array format in a file named <tt>application.php</tt>.
The format of the configuration file is exactly the same of its XML counterpart, but following the PHP syntax.
</p>
<com:TTextHighlighter Language="php" CssClass="source block-content">
<?php
return array(
'application' => array(
'PropertyName' => 'PropertyValue'
),
'modules' => array(
'ModuleID' => array(
'class' => 'ModuleClass',
'properties' => array(
'PropertyName' => 'PropertyValue'
),
),
),
'services' => array(
'ServiceID' => array(
'class' => 'ServiceClass',
'properties' => array(
'PropertyName' => 'PropertyValue'
),
),
),
);
</com:TTextHighlighter>
The use of a PHP application configuration must be defined in the <tt>TApplication</tt> constructor, tipically located in the <tt>index.php</tt> entry script:
<com:TTextHighlighter Language="php" CssClass="source block-content">
$application=new TApplication('protected',false,TApplication::CONFIG_TYPE_PHP);
$application->run();
</com:TTextHighlighter>
</com:TContent>
|
