| blob | 555afa88f4415f2f65a97f24e2c4e6ca6283554e |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.tool.framework.clitool">
4 <title>Using the CLI Tool</title>
6 <para>
7 The <acronym>CLI</acronym>, or command line tool (internally known as the console tool),
8 is currently the primary interface for dispatching <classname>Zend_Tool</classname>
9 requests. With the <acronym>CLI</acronym> tool, developers can issue tooling requests
10 inside the "command line windows", also commonly known as a "terminal"
11 window. This environment is predominant in the *nix environment, but
12 also has a common implementation in windows with the
13 <filename>cmd.exe</filename>, console2 and also with the Cygwin project.
14 </para>
16 <sect2 id="zend.tool.framework.clitool.setup-general">
17 <title>Setting up the CLI tool</title>
19 <para>
20 To issue tooling requests via the command line client, you first
21 need to set up the client so that your system can handle the "zf"
22 command. The command line client, for all intents and purposes, is
23 the <filename>.sh</filename> or <filename>.bat</filename> file that is provided with
24 your Zend Framework distribution. In trunk, it can be found here:
25 <ulink
26 url="http://framework.zend.com/svn/framework/standard/trunk/bin/">http://framework.zend.com/svn/framework/standard/trunk/bin/</ulink>.
27 </para>
29 <para>
30 As you can see, there are 3 files in the <filename>/bin/</filename>
31 directory: a <filename>zf.php</filename>, <filename>zf.sh</filename>, and
32 <filename>zf.bat</filename>. The <filename>zf.sh</filename> and the
33 <filename>zf.bat</filename> are the operating system specific client
34 wrappers: <filename>zf.sh</filename> for the *nix environment, and
35 <filename>zf.bat</filename> for the Win32 environment. These client wrappers are
36 responsible for finding the proper <filename>php.exe</filename>, finding the
37 <filename>zf.php</filename>, and passing on the client request. The
38 <filename>zf.php</filename> is the responsible for handling understanding
39 your environment, constructing the proper include_path, and passing
40 what is provided on the command line to the proper library component
41 for dispatching.
42 </para>
44 <para>
45 Ultimately, you want to ensure two things to make everything work
46 regardless of the operating system you are on:
47 </para>
49 <orderedlist>
50 <listitem>
51 <para>
52 <filename>zf.sh/zf.bat</filename> is reachable from your system
53 path. This is the ability to call <command>zf</command> from
54 anywhere on your command line, regardless of what your
55 current working directory is.
56 </para>
57 </listitem>
59 <listitem>
60 <para>
61 <filename>ZendFramework/library</filename> is in your
62 <property>include_path</property>.
63 </para>
64 </listitem>
65 </orderedlist>
67 <note>
68 <para>
69 Note: while the above are the most ideal
70 requirements, you can simply download Zend Framework and expect it
71 to work as <filename>./path/to/zf.php</filename> some command.
72 </para>
73 </note>
74 </sect2>
76 <sect2 id="zend.tool.framework.clitool.setup-starnix">
77 <title>Setting up the CLI tool on Unix-like Systems</title>
79 <para>
80 The most common setup in the *nix environment, is to copy the
81 <filename>zf.sh</filename> and <filename>zf.php</filename> into the same directory
82 as your <acronym>PHP</acronym> binary. This can generally be found in one of the
83 following places:
84 </para>
86 <programlisting language="text"><![CDATA[
87 /usr/bin
88 /usr/local/bin
89 /usr/local/ZendServer/bin/
90 /Applications/ZendServer/bin/
91 ]]></programlisting>
93 <para>
94 To find out the location of your <acronym>PHP</acronym> binary, you can execute 'which
95 php' on the command line. This will return the location of the <acronym>PHP</acronym>
96 binary you will be using to run <acronym>PHP</acronym> scripts in this environment.
97 </para>
99 <para>
100 The next order of business is to ensure that Zend Framework
101 library is set up correctly inside of the system <acronym>PHP</acronym>
102 <property>include_path</property>. To find out where your
103 <property>include_path</property> is located, you can execute <command>php -i</command>
104 and look for the <property>include_path</property> variable, or more succinctly,
105 execute <command>php -i | grep include_path</command>. Once you have found where
106 your <property>include_path</property> is located (this will generally be
107 something like <filename>/usr/lib/php</filename>, <filename>/usr/share/php</filename>,
108 <filename>/usr/local/lib/php</filename>, or similar), ensure that the contents of the
109 <filename>/library/</filename> directory are put
110 inside your <property>include_path</property> specified directory.
111 </para>
113 <para>
114 Once you have done those two things, you should be able to issue a
115 command and get back the proper response like this:
116 </para>
118 <para>
119 <inlinegraphic scale="100" align="center" valign="middle"
120 fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG" />
121 </para>
123 <para>
124 If you do not see this type of output, go back and check your setup
125 to ensure you have all of the necessary pieces in the proper place.
126 </para>
128 <para>
129 There are a couple of alternative setups you might want to employ
130 depending on your servers configuration, your level of access, or
131 for other reasons.
132 </para>
134 <para>
135 <emphasis>Alternative Setup</emphasis> involves keeping the Zend
136 Framework download together as is, and creating a link from a <constant>PATH</constant>
137 location to the <filename>zf.sh</filename>. What this means is you can
138 place the contents of the ZendFramework download into a location
139 such as <filename>/usr/local/share/ZendFramework</filename>, or more locally
140 like <filename>/home/username/lib/ZendFramework</filename>, and creating a
141 symbolic link to the <filename>zf.sh</filename>.
142 </para>
144 <para>
145 Assuming you want to put the link inside <filename>/usr/local/bin</filename>
146 (this could also work for placing the link inside
147 <filename>/home/username/bin/</filename> for example) you would issue a
148 command similar to this:
149 </para>
151 <programlisting language="sh"><![CDATA[
152 ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf
154 # OR (for example)
155 ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
156 ]]></programlisting>
158 <para>
159 This will create a link which you should be able to access globally
160 on the command line.
161 </para>
162 </sect2>
164 <sect2 id="zend.tool.framework.clitool.setup-windows">
165 <title>Setting up the CLI tool on Windows</title>
167 <para>
168 The most common setup in the Windows Win32 environment, is to copy
169 the <filename>zf.bat</filename> and <filename>zf.php</filename> into the same
170 directory as your <acronym>PHP</acronym> binary. This can generally be found in one of
171 the following places:
172 </para>
174 <programlisting language="text"><![CDATA[
175 C:\PHP
176 C:\Program Files\ZendServer\bin\
177 C:\WAMP\PHP\bin
178 ]]></programlisting>
180 <para>
181 You should be able to run <filename>php.exe</filename> on the command line.
182 If you are not able to, first check the documentation that came with
183 your <acronym>PHP</acronym> distribution, or ensure that the path to
184 <filename>php.exe</filename> is in your
185 Windows <constant>PATH</constant> environment variable.
186 </para>
188 <para>
189 The next order of business is to ensure that Zend Framework
190 library is set up correctly inside of the system <acronym>PHP</acronym>
191 <property>include_path</property>. To find out where your
192 <property>include_path</property> is located, you can type <command>php -i</command> and
193 look for the <property>include_path</property> variable, or more succinctly
194 execute <command>php -i | grep include_path</command> if you have Cygwin setup with
195 grep available. Once you have found where your
196 <property>include_path</property> is located (this will generally be
197 something like <filename>C:\PHP\pear</filename>, <filename>C:\PHP\share</filename>,
198 <filename>C:\Program%20Files\ZendServer\share</filename> or similar), ensure
199 that the contents of the library/ directory are put inside your
200 <property>include_path</property> specified directory.
201 </para>
203 <para>
204 Once you have done those two things, you should be able to issue a
205 command and get back the proper response like this:
206 </para>
208 <para>
209 <inlinegraphic scale="100" align="center" valign="middle"
210 fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG" />
211 </para>
213 <para>
214 If you do not see this type of output, go back and check your setup
215 to ensure you have all of the necessary pieces in the proper place.
216 </para>
218 <para>
219 There are a couple of alternative setups you might want to employ
220 depending on your server's configuration, your level of access, or
221 for other reasons.
222 </para>
224 <para>
225 <emphasis>Alternative Setup</emphasis> involves keeping the Zend
226 Framework download together as is, and altering both your system
227 <constant>PATH</constant> as well as the <filename>php.ini</filename> file.
228 In your user's environment, make sure to add
229 <filename>C:\Path\To\ZendFramework\bin</filename>, so that your
230 <filename>zf.bat</filename> file is executable. Also, alter the
231 <filename>php.ini</filename> file to ensure that
232 <filename>C:\Path\To\ZendFramework\library</filename> is in your
233 <property>include_path</property>.
234 </para>
235 </sect2>
237 <sect2 id="zend.tool.framework.clitool.setup-othernotes">
238 <title>Other Setup Considerations</title>
240 <para>
241 If for some reason you do not want Zend Framework library inside
242 your <property>include_path</property>, there is another option. There are
243 two special environment variables that <filename>zf.php</filename> will
244 utilize to determine the location of your Zend Framework
245 installation.
246 </para>
248 <para>
249 The first is <constant>ZEND_TOOL_INCLUDE_PATH_PREPEND</constant>, which will
250 prepend the value of this environment variable to the system
251 (<filename>php.ini</filename>) <property>include_path</property> before loading the
252 client.
253 </para>
255 <para>
256 Alternatively, you might want to use
257 <constant>ZEND_TOOL_INCLUDE_PATH</constant> to completely
258 <emphasis>replace</emphasis> the system <property>include_path</property>
259 for one that makes sense specifically for the <command>zf</command>
260 command line tool.
261 </para>
262 </sect2>
264 <sect2 id="zend.tool.framework.clitool.continuing">
265 <title>Where To Go Next?</title>
267 <para>
268 At this point, you should be set up to start initiating some more
269 "interesting" commands. To get going, you can issue the
270 <command>zf --help</command> command to see what is available to you.
271 </para>
273 <para>
274 <inlinegraphic scale="100" align="center" valign="middle"
275 fileref="figures/zend.tool.framework.clihelp.png" format="PNG" />
276 </para>
278 <para>
279 Continue on to the <classname>Zend_Tool_Project</classname> "Create Project"
280 section to understand how to use the <command>zf</command> script for
281 project creation.
282 </para>
283 </sect2>
284 </sect1>