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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.tool.framework.extending">
<title>Extending and Configuring Zend_Tool_Framework</title>
<sect2 id="zend.tool.framework.console-client">
<title>Customizing Zend_Tool Console Client</title>
<para>
As of Zend Framework 1.9, <classname>Zend_Tool_Framework</classname> allows developers
to store information, provider specific configuration values, and custom files in a
special location on the developers machine. These configuration values and files can be
used by providers to extend functionality, customize functionality, or any other reasons
a provider sees fit.
</para>
<para>
The primary purpose, and the purpose most immediately used by existing providers is to
allow developers to customize the way the "out of the box" providers do work.
</para>
<para>
One of the more commonly requested features is to be able to provide custom project
profiles to <classname>Zend_Tool_Project</classname>'s Project Provider. This would
allow developers to store a custom profile in a special place that can be used
repeatedly by the <classname>Zend_Tool</classname> system in order to build custom
profiles. Another commonly requested feature is to be able to configure the behavior of
providers with a configuration setting. In order to achieve this, not only do we have to
have a <classname>Zend_Tool</classname> configuration file, but we also have to have a
place to find this configuration file.
</para>
<sect3 id="zend.tool.framework.console-client.home-directory">
<title>The Home Directory</title>
<para>
Before the Console Client can start searching for a <classname>Zend_Tool</classname>
configuration file or a local storage directory, it must first be able to identify
where the "home directory" is located.
</para>
<para>
On *nix-based machines, <acronym>PHP</acronym> will be populated with an environment
variable named <constant>HOME</constant> with a path to the current users home
directory. Typically, this path will be very similar to
<filename>/home/myusername</filename>.
</para>
<para>
On Windows-based machines, <acronym>PHP</acronym> will typically be populated with
an environment variable named <constant>HOMEPATH</constant> with the current users
home directory. This directory is usually found in either
<filename>C:\Documents and Settings\Username\</filename>, or in Vista at
<filename>C:\Users\Username</filename>.
</para>
<para>
If either a home directory cannot be found, or you wish to change the location of
where <classname>Zend_Tool_Framework</classname> Console Client finds the home
directory, you can provide an environment variable named
<constant>ZF_HOME</constant> to specify where to find the home directory.
</para>
</sect3>
<sect3 id="zend.tool.framework.console-client.local-storage">
<title>Local Storage</title>
<para>
Once a home directory can be located, <classname>Zend_Tool_Framework</classname>'s
Console Client can either autodiscover the local storage directory, or it can be
told where to expect the local storage directory.
</para>
<para>
Assuming the home directory has been found (here noted as <varname>$HOME</varname>),
the Console Client will then look for the local storage directory in
<filename>$HOME/.zf/</filename>. If found, it will set the local storage directory
to this location.
</para>
<para>
If the directory cannot be found, or the developer wishes to override this location,
that can be done by setting an environment variable. Regardless if
<varname>$HOME</varname> has been previously set or not, the developer may supply
the environment variable <constant>ZF_STORAGE_DIR</constant>.
</para>
<para>
Once the path to a local storage directory is found, the directory
<emphasis>must</emphasis> exist for it to be passed into the
<classname>Zend_Tool_Framework</classname> runtime, as it will not be created for
you.
</para>
</sect3>
<sect3 id="zend.tool.framework.console-client.configuration-file">
<title>User Configuration</title>
<para>
Like local storage, once a home directory can be located,
<classname>Zend_Tool_Framework</classname>'s Console Client can then either attempt
to autodiscover the path to a configuration file, or it can be told specifically
where to find the configuration file.
</para>
<para>
Assuming the home directory has been found (here noted as <varname>$HOME</varname>),
the Console Client will then attempt to look for the existence of a configuration
file located at <filename>$HOME/.zf.ini</filename>. This file, if found, will be
used as the configuration file for <classname>Zend_Tool_Framework</classname>.
</para>
<para>
If that location does not exist, but a local storage directory does, then the
Console Client will then attempt to locate the configuration file within the local
storage directory. Assuming the local storage directory exists in
<varname>$LOCAL_STORAGE</varname>, then if a file exists as
<filename>$LOCAL_STORAGE/zf.ini</filename>, it will be found by the Console Client
and utilized as the <classname>Zend_Tool_Framework</classname> configuration file.
</para>
<para>
If the file cannot be autodiscovered or the developer wishes to specify the location
of location of the configuration file, the developer can do so by setting an
environment variable. If the environment variable
<constant>ZF_CONFIG_FILE</constant> is set, then its value will be used as the
location of the configuration file to use with the Console Client. The
<constant>ZF_CONFIG_FILE</constant> can point to any
<classname>Zend_Config</classname> readable <acronym>INI</acronym>,
<acronym>XML</acronym> or <acronym>PHP</acronym> File.
</para>
<para>
If the file does not exist in either the autodiscovered or the provided location, it
will not be used as <classname>Zend_Tool_Framework</classname> does not attempt to
create the file automatically.
</para>
</sect3>
<sect3 id="zend.tool.framework.console-client.configuration-content">
<title>User Configuration File Content</title>
<para>
The configuration file should be structured as a <classname>Zend_Config</classname>
configuration file, in <acronym>INI</acronym> format, and without any sections being
defined. First level keys should be used by the provider searching for a specific
value. For example, if the "Project" provider is expecting a "profiles" directory,
then it should typically be understood that it will search for the following
<acronym>INI</acronym> key value pair:
</para>
<programlisting language="php"><![CDATA[
project.profile = some/path/to/some-directory
]]></programlisting>
<para>
The only reserved <acronym>INI</acronym> prefix is the value "php". The "php" prefix
to values will be reserved to store names and values of runtime settable
<acronym>PHP</acronym> values, such as <property>include_path</property> or
<property>error_reporting</property>. To override the
<property>include_path</property> and <property>error_reporting</property> with an
<acronym>INI</acronym> value, a developer would set:
</para>
<programlisting language="php"><![CDATA[
php.include_path = "/path/to/includes1:/path/to/includes2"
php.error_reporting = 1
]]></programlisting>
<important>
<para>
The reserved prefix "php" only works with <acronym>INI</acronym> files. You
can't set <acronym>PHP</acronym> <acronym>INI</acronym> values with
<acronym>PHP</acronym> or <acronym>XML</acronym> config.
</para>
</important>
</sect3>
</sect2>
</sect1>
|
