documentation/manual/es/module_specs/Zend_Tool_Framework-CliTool.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2     <!-- EN-Revision: 16656 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.tool.framework.clitool">
   5     <title>Usando la herramienta CLI</title>
   6     <para>
   7         The
   8         <acronym>CLI</acronym>
   9         , or command line tool (internally known as the console tool),
  10         is currently the primary
  11         interface for dispatching
  12         <classname>Zend_Tool</classname>
  13         requests. With the
  14         <acronym>CLI</acronym>
  15         tool, developers can issue tooling requests
  16         inside the "command line windows", also commonly
  17         known as a "terminal"
  18         window. This environment is predominant in the *nix environment, but
  19         also has a common implementation in windows with the
  20         <filename>cmd.exe</filename>
  21         , console2 and also with the Cygwin project.
  22     </para>
  23
  24     <sect2 id="zend.tool.framework.clitool.setup-general">
  25         <title>Setting up the CLI tool</title>
  26
  27         <para>
  28             To issue tooling requests via the command line client, you first
  29             need to set up the
  30             client so that your system can handle the "zf"
  31             command. The command line client, for all
  32             intents and purposes, is
  33             the
  34             <filename>.sh</filename>
  35             or
  36             <filename>.bat</filename>
  37             file that is provided with
  38             your Zend Framework distribution. In trunk, it can be found
  39             here:
  40             <ulink url="http://framework.zend.com/svn/framework/standard/trunk/bin/">
  41             http://framework.zend.com/svn/framework/standard/trunk/bin/
  42             </ulink>
  43             .
  44         </para>
  45
  46         <para>
  47             As you can see, there are 3 files in the
  48             <filename>/bin/</filename>
  49             directory: a
  50             <filename>zf.php</filename>
  51             ,
  52             <filename>zf.sh</filename>
  53             , and
  54             <filename>zf.bat</filename>
  55             . The
  56             <filename>zf.sh</filename>
  57             and the
  58             <filename>zf.bat</filename>
  59             are the operating system specific client
  60             wrappers:
  61             <filename>zf.sh</filename>
  62             for the *nix environment, and
  63             <filename>zf.bat</filename>
  64             for the Win32 environment. These client wrappers are
  65             responsible for finding the proper
  66             <filename>php.exe</filename>
  67             , finding the
  68             <filename>zf.php</filename>
  69             , and passing on the client request. The
  70             <filename>zf.php</filename>
  71             is the responsible for handling understanding
  72             your environment, constructing the proper
  73             include_path, and passing
  74             what is provided on the command line to the proper library
  75             component
  76             for dispatching.
  77         </para>
  78
  79         <para>
  80             Ultimately, you want to ensure two things to make everything work
  81             regardless of the
  82             operating system you are on:
  83        </para>
  84
  85         <orderedlist>
  86             <listitem>
  87                 <para>
  88                     <filename>zf.sh/zf.bat</filename>
  89                     is reachable from your system
  90                     path. This is the ability to call
  91                     <command>zf</command>
  92                     from
  93                     anywhere on your command line, regardless of what your
  94                     current working
  95                     directory is.
  96                 </para>
  97             </listitem>
  98             <listitem>
  99                 <para>
 100                     <filename>ZendFramework/library</filename>
 101                     is in your
 102                     <property>include_path</property>
 103                     .
 104                 </para>
 105             </listitem>
 106         </orderedlist>
 107
 108         <note>
 109             <para>
 110                 Note: while the above are the most ideal
 111                 requirements, you can simply download Zend
 112                 Framework and expect it
 113                 to work as
 114                 <filename>./path/to/zf.php</filename>
 115                 some command.
 116             </para>
 117         </note>
 118
 119     </sect2>
 120
 121     <sect2 id="zend.tool.framework.clitool.setup-starnix">
 122         <title>Setting up the CLI tool on Unix-like Systems</title>
 123
 124         <para>
 125             The most common setup in the *nix environment, is to copy the
 126             <filename>zf.sh</filename>
 127             and
 128             <filename>zf.php</filename>
 129             into the same directory
 130             as your
 131             <acronym>PHP</acronym>
 132             binary. This can generally be found in one of the
 133             following places:
 134         </para>
 135
 136         <programlisting language="text"><![CDATA[
 137 /usr/bin
 138 /usr/local/bin
 139 /usr/local/ZendServer/bin/
 140 /Applications/ZendServer/bin/
 141 ]]></programlisting>
 142
 143         <para>
 144             To find out the location of your
 145             <acronym>PHP</acronym>
 146             binary, you can execute 'which
 147             php' on the command line. This will return the location of
 148             the
 149             <acronym>PHP</acronym>
 150             binary you will be using to run
 151             <acronym>PHP</acronym>
 152             scripts in this environment.
 153         </para>
 154
 155         <para>
 156             The next order of business is to ensure that Zend Framework
 157             library is set up correctly
 158             inside of the system
 159             <acronym>PHP</acronym>
 160             <property>include_path</property>
 161             . To find out where your
 162             <property>include_path</property>
 163             is located, you can execute
 164             <command>php -i</command>
 165             and look for the
 166             <property>include_path</property>
 167             variable, or more succinctly,
 168             execute
 169             <command>php -i | grep include_path</command>
 170             . Once you have found where
 171             your
 172             <property>include_path</property>
 173             is located (this will generally be
 174             something like
 175             <filename>/usr/lib/php</filename>
 176             ,
 177             <filename>/usr/share/php</filename>
 178             ,
 179             <filename>/usr/local/lib/php</filename>
 180             , or similar), ensure that the contents of the
 181             <filename>/library/</filename>
 182             directory are put
 183             inside your
 184             <property>include_path</property>
 185             specified directory.
 186         </para>
 187
 188         <para>
 189             Once you have done those two things, you should be able to issue a
 190             command and get back
 191             the proper response like this:
 192        </para>
 193
 194         <para>
 195             <inlinegraphic scale="100" align="center" valign="middle"
 196                 fileref="figures/zend.tool.framework.cliversionunix.png" format="PNG"/>
 197         </para>
 198
 199         <para>
 200             If you do not see this type of output, go back and check your setup
 201             to ensure you have
 202             all of the necessary pieces in the proper place.
 203        </para>
 204
 205         <para>
 206             There are a couple of alternative setups you might want to employ
 207             depending on your
 208             servers configuration, your level of access, or
 209             for other reasons.
 210        </para>
 211
 212         <para>
 213             <emphasis>Alternative Setup</emphasis>
 214             involves keeping the Zend
 215             Framework download together as is, and creating a link from a
 216             <constant>PATH</constant>
 217             location to the
 218             <filename>zf.sh</filename>
 219             . What this means is you can
 220             place the contents of the ZendFramework download into a
 221             location
 222             such as
 223             <filename>/usr/local/share/ZendFramework</filename>
 224             , or more locally
 225             like
 226             <filename>/home/username/lib/ZendFramework</filename>
 227             , and creating a
 228             symbolic link to the
 229             <filename>zf.sh</filename>
 230             .
 231         </para>
 232
 233         <para>
 234             Assuming you want to put the link inside
 235             <filename>/usr/local/bin</filename>
 236             (this could also work for placing the link inside
 237             <filename>/home/username/bin/</filename>
 238             for example) you would issue a
 239             command similar to this:
 240         </para>
 241
 242         <programlisting language="sh"><![CDATA[
 243 ln -s /usr/local/share/ZendFramework/bin/zf.sh /usr/local/bin/zf
 244
 245 # OR (for example)
 246 ln -s /home/username/lib/ZendFramework/bin/zf.sh /home/username/bin/zf
 247 ]]></programlisting>
 248
 249         <para>
 250             This will create a link which you should be able to access globally
 251             on the command
 252             line.
 253        </para>
 254
 255     </sect2>
 256
 257     <sect2 id="zend.tool.framework.clitool.setup-windows">
 258         <title>Setting up the CLI tool on Windows</title>
 259
 260         <para>
 261             The most common setup in the Windows Win32 environment, is to copy
 262             the
 263             <filename>zf.bat</filename>
 264             and
 265             <filename>zf.php</filename>
 266             into the same
 267             directory as your
 268             <acronym>PHP</acronym>
 269             binary. This can generally be found in one of
 270             the following places:
 271         </para>
 272
 273         <programlisting language="text"><![CDATA[
 274 C:\PHP
 275 C:\Program Files\ZendServer\bin\
 276 C:\WAMP\PHP\bin
 277 ]]></programlisting>
 278
 279         <para>
 280             You should be able to run
 281             <filename>php.exe</filename>
 282             on the command line.
 283             If you are not able to, first check the documentation that came with
 284             your
 285             <acronym>PHP</acronym>
 286             distribution, or ensure that the path to
 287             <filename>php.exe</filename>
 288             is in your
 289             Windows
 290             <constant>PATH</constant>
 291             environment variable.
 292         </para>
 293
 294         <para>
 295             The next order of business is to ensure that Zend Framework
 296             library is set up correctly
 297             inside of the system
 298             <acronym>PHP</acronym>
 299             <property>include_path</property>
 300             . To find out where your
 301             <property>include_path</property>
 302             is located, you can type
 303             <command>php -i</command>
 304             and
 305             look for the
 306             <property>include_path</property>
 307             variable, or more succinctly
 308             execute
 309             <command>php -i | grep include_path</command>
 310             if you have Cygwin setup with
 311             grep available. Once you have found where your
 312             <property>include_path</property>
 313             is located (this will generally be
 314             something like
 315             <filename>C:\PHP\pear</filename>
 316             ,
 317             <filename>C:\PHP\share</filename>
 318             ,
 319             <filename>C:\Program%20Files\ZendServer\share</filename>
 320             or similar), ensure
 321             that the contents of the library/ directory are put inside your
 322             <property>include_path</property>
 323             specified directory.
 324         </para>
 325
 326         <para>
 327             Once you have done those two things, you should be able to issue a
 328             command and get back
 329             the proper response like this:
 330        </para>
 331
 332         <para>
 333             <inlinegraphic scale="100" align="center" valign="middle"
 334                 fileref="figures/zend.tool.framework.cliversionwin32.png" format="PNG"/>
 335         </para>
 336
 337         <para>
 338             If you do not see this type of output, go back and check your setup
 339             to ensure you have
 340             all of the necessary pieces in the proper place.
 341        </para>
 342
 343         <para>
 344             There are a couple of alternative setups you might want to employ
 345             depending on your
 346             server's configuration, your level of access, or
 347             for other reasons.
 348        </para>
 349
 350         <para>
 351             <emphasis>Alternative Setup</emphasis>
 352             involves keeping the Zend
 353             Framework download together as is, and altering both your
 354             system
 355             <constant>PATH</constant>
 356             as well as the
 357             <filename>php.ini</filename>
 358             file.
 359             In your user's environment, make sure to add
 360             <filename>C:\Path\To\ZendFramework\bin</filename>
 361             , so that your
 362             <filename>zf.bat</filename>
 363             file is executable. Also, alter the
 364             <filename>php.ini</filename>
 365             file to ensure that
 366             <filename>C:\Path\To\ZendFramework\library</filename>
 367             is in your
 368             <property>include_path</property>
 369             .
 370         </para>
 371
 372     </sect2>
 373
 374     <sect2 id="zend.tool.framework.clitool.setup-othernotes">
 375         <title>Other Setup Considerations</title>
 376
 377         <para>
 378             If for some reason you do not want Zend Framework library inside
 379             your
 380             <property>include_path</property>
 381             , there is another option. There are
 382             two special environment variables that
 383             <filename>zf.php</filename>
 384             will
 385             utilize to determine the location of your Zend Framework
 386             installation.
 387         </para>
 388
 389         <para>
 390             The first is
 391             <constant>ZEND_TOOL_INCLUDE_PATH_PREPEND</constant>
 392             , which will
 393             prepend the value of this environment variable to the system
 394             (
 395             <filename>php.ini</filename>
 396             )
 397             <property>include_path</property>
 398             before loading the
 399             client.
 400         </para>
 401
 402         <para>
 403             Alternatively, you might want to use
 404             <constant>ZEND_TOOL_INCLUDE_PATH</constant>
 405             to completely
 406             <emphasis>replace</emphasis>
 407             the system
 408             <property>include_path</property>
 409             for one that makes sense specifically for the
 410             <command>zf</command>
 411             command line tool.
 412         </para>
 413     </sect2>
 414
 415     <sect2 id="zend.tool.framework.clitool.continuing">
 416         <title>Where To Go Next?</title>
 417
 418         <para>
 419             At this point, you should be set up to start initiating some more
 420             "interesting" commands.
 421             To get going, you can issue the
 422             <command>zf --help</command>
 423             command to see what is available to you.
 424         </para>
 425
 426         <para>
 427             <inlinegraphic scale="100" align="center" valign="middle"
 428                 fileref="figures/zend.tool.framework.clihelp.png" format="PNG"/>
 429         </para>
 430
 431         <para>
 432             Continue on to the
 433             <classname>Zend_Tool_Project</classname>
 434             "Create Project"
 435             section to understand how to use the
 436             <command>zf</command>
 437             script for
 438             project creation.
 439         </para>
 440     </sect2>
 441 </sect1>