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
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.tool.framework.clitool">
<title>Using the CLI Tool</title>
<para>
The <acronym>CLI</acronym>, or command line tool (internally known as the console tool),
is currently the primary interface for dispatching <classname>Zend_Tool</classname>
requests. With the <acronym>CLI</acronym> tool, developers can issue tooling requests
inside the "command line windows", also commonly known as a "terminal"
window. This environment is predominant in the *nix environment, but
also has a common implementation in windows with the
<filename>cmd.exe</filename>, console2 and also with the Cygwin project.
</para>
<sect2 id="zend.tool.framework.clitool.setup-general">
<title>Setting up the CLI tool</title>
<para>
To issue tooling requests via the command line client, you first
need to set up the client so that your system can handle the "zf"
command. The command line client, for all intents and purposes, is
the <filename>.sh</filename> or <filename>.bat</filename> file that is provided with
your Zend Framework distribution. In trunk, it can be found here:
<ulink
url="http://framework.zend.com/svn/framework/standard/trunk/bin/">http://framework.zend.com/svn/framework/standard/trunk/bin/</ulink>.
</para>
<para>
As you can see, there are 3 files in the <filename>/bin/</filename>
directory: a <filename>zf.php</filename>, <filename>zf.sh</filename>, and
<filename>zf.bat</filename>. The <filename>zf.sh</filename> and the
<filename>zf.bat</filename> are the operating system specific client
wrappers: <filename>zf.sh</filename> for the *nix environment, and
<filename>zf.bat</filename> for the Win32 environment. These client wrappers are
responsible for finding the proper <filename>php.exe</filename>, finding the
<filename>zf.php</filename>, and passing on the client request. The
<filename>zf.php</filename> is the responsible for handling understanding
your environment, constructing the proper include_path, and passing
what is provided on the command line to the proper library component
for dispatching.
</para>
<para>
Ultimately, you want to ensure two things to make everything work
regardless of the operating system you are on:
</para>
<orderedlist>
<listitem>
<para>
<filename>zf.sh/zf.bat</filename> is reachable from your system
path. This is the ability to call <command>zf</command> from
anywhere on your command line, regardless of what your
current working directory is.
</para>
</listitem>
<listitem>
<para>
<filename>ZendFramework/library</filename> is in your
<property>include_path</property>.
</para>
</listitem>
</orderedlist>
<note>
<para>
Note: while the above are the most ideal
requirements, you can simply download Zend Framework and expect it
to work as <filename>./path/to/zf.php</filename> some command.
</para>
</note>
</sect2>
<sect2 id="zend.tool.framework.clitool.setup-starnix">
<title>Setting up the CLI tool on Unix-like Systems</title>
<para>
The most common setup in the *nix environment, is to copy the
<filename>zf.sh</filename> and <filename>zf.php</filename> into the same directory
as your <acronym>PHP</acronym> binary. This can generally be found in one of the
following places:
</para>
<programlisting language="text"><![CDATA[
/usr/bin
/usr/local/bin
/usr/local/ZendServer/bin/
/Applications/ZendServer/bin/
]]></programlisting>
<para>
To find out the location of your <acronym>PHP</acronym> binary, you can execute 'which
php' on the command line. This will return the location of the <acronym>PHP</acronym>
binary you will be using to run <acronym>PHP</acronym> scripts in this environment.
</para>
<para>
The next order of business is to ensure that Zend Framework
library is set up correctly inside of the system <acronym>PHP</acronym>
<property>include_path</property>. To find out where your
<property>include_path</property> is located, you can execute <command>php -i</command>
and look for the <property>include_path</property> variable, or more succinctly,
execute <command>php -i | grep include_path</command>. Once you have found where
your <property>include_path</property> is located (this will generally be
something like <filename>/usr/lib/php</filename>, <filename>/usr/share/php</filename>,
<filename>/usr/local/lib/php</filename>, or similar), ensure that the contents of the
<filename>/library/</filename> directory are put
inside your <property>include_path</property> specified directory.
</para>
<para>
Once you have done those two things, you should be able to issue a
command and get back the proper response like this:
</para>
<para>
<inlinegraphic scale="100" align="center" valign="middle"
fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG" />
</para>
<para>
If you do not see this type of output, go back and check your setup
to ensure you have all of the necessary pieces in the proper place.
</para>
<para>
There are a couple of alternative setups you might want to employ
depending on your servers configuration, your level of access, or
for other reasons.
</para>
<para>
<emphasis>Alternative Setup</emphasis> involves keeping the Zend
Framework download together as is, and creating a link from a <constant>PATH</constant>
location to the <filename>zf.sh</filename>. What this means is you can
place the contents of the ZendFramework download into a location
such as <filename>/usr/local/share/ZendFramework</filename>, or more locally
like <filename>/home/username/lib/ZendFramework</filename>, and creating a
symbolic link to the <filename>zf.sh</filename>.
</para>
<para>
Assuming you want to put the link inside <filename>/usr/local/bin</filename>
(this could also work for placing the link inside
<filename>/home/username/bin/</filename> for example) you would issue a
command similar to this:
</para>
<programlisting language="sh"><![CDATA[
ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf
# OR (for example)
ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
]]></programlisting>
<para>
This will create a link which you should be able to access globally
on the command line.
</para>
</sect2>
<sect2 id="zend.tool.framework.clitool.setup-windows">
<title>Setting up the CLI tool on Windows</title>
<para>
The most common setup in the Windows Win32 environment, is to copy
the <filename>zf.bat</filename> and <filename>zf.php</filename> into the same
directory as your <acronym>PHP</acronym> binary. This can generally be found in one of
the following places:
</para>
<programlisting language="text"><![CDATA[
C:\PHP
C:\Program Files\ZendServer\bin\
C:\WAMP\PHP\bin
]]></programlisting>
<para>
You should be able to run <filename>php.exe</filename> on the command line.
If you are not able to, first check the documentation that came with
your <acronym>PHP</acronym> distribution, or ensure that the path to
<filename>php.exe</filename> is in your
Windows <constant>PATH</constant> environment variable.
</para>
<para>
The next order of business is to ensure that Zend Framework
library is set up correctly inside of the system <acronym>PHP</acronym>
<property>include_path</property>. To find out where your
<property>include_path</property> is located, you can type <command>php -i</command> and
look for the <property>include_path</property> variable, or more succinctly
execute <command>php -i | grep include_path</command> if you have Cygwin setup with
grep available. Once you have found where your
<property>include_path</property> is located (this will generally be
something like <filename>C:\PHP\pear</filename>, <filename>C:\PHP\share</filename>,
<filename>C:\Program%20Files\ZendServer\share</filename> or similar), ensure
that the contents of the library/ directory are put inside your
<property>include_path</property> specified directory.
</para>
<para>
Once you have done those two things, you should be able to issue a
command and get back the proper response like this:
</para>
<para>
<inlinegraphic scale="100" align="center" valign="middle"
fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG" />
</para>
<para>
If you do not see this type of output, go back and check your setup
to ensure you have all of the necessary pieces in the proper place.
</para>
<para>
There are a couple of alternative setups you might want to employ
depending on your server's configuration, your level of access, or
for other reasons.
</para>
<para>
<emphasis>Alternative Setup</emphasis> involves keeping the Zend
Framework download together as is, and altering both your system
<constant>PATH</constant> as well as the <filename>php.ini</filename> file.
In your user's environment, make sure to add
<filename>C:\Path\To\ZendFramework\bin</filename>, so that your
<filename>zf.bat</filename> file is executable. Also, alter the
<filename>php.ini</filename> file to ensure that
<filename>C:\Path\To\ZendFramework\library</filename> is in your
<property>include_path</property>.
</para>
</sect2>
<sect2 id="zend.tool.framework.clitool.setup-othernotes">
<title>Other Setup Considerations</title>
<para>
If for some reason you do not want Zend Framework library inside
your <property>include_path</property>, there is another option. There are
two special environment variables that <filename>zf.php</filename> will
utilize to determine the location of your Zend Framework
installation.
</para>
<para>
The first is <constant>ZEND_TOOL_INCLUDE_PATH_PREPEND</constant>, which will
prepend the value of this environment variable to the system
(<filename>php.ini</filename>) <property>include_path</property> before loading the
client.
</para>
<para>
Alternatively, you might want to use
<constant>ZEND_TOOL_INCLUDE_PATH</constant> to completely
<emphasis>replace</emphasis> the system <property>include_path</property>
for one that makes sense specifically for the <command>zf</command>
command line tool.
</para>
</sect2>
<sect2 id="zend.tool.framework.clitool.continuing">
<title>Where To Go Next?</title>
<para>
At this point, you should be set up to start initiating some more
"interesting" commands. To get going, you can issue the
<command>zf --help</command> command to see what is available to you.
</para>
<para>
<inlinegraphic scale="100" align="center" valign="middle"
fileref="figures/zend.tool.framework.clihelp.png" format="PNG" />
</para>
<para>
Continue on to the <classname>Zend_Tool_Project</classname> "Create Project"
section to understand how to use the <command>zf</command> script for
project creation.
</para>
</sect2>
</sect1>
|
