documentation/manual/en/module_specs/Zend_Tool-Usage-CLI.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.tool.usage.cli">
   4     <title>Using Zend_Tool On The Command Line</title>
   5
   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 window", also commonly known as a "terminal" window. This
  11         environment is predominant in the *nix environment, but also has a common implementation
  12         in windows with the <filename>cmd.exe</filename>, console2 and also with the Cygwin project.
  13     </para>
  14
  15     <!--
  16     <sect2 id="zend.tool.usage.cli.introduction">
  17         <title>Introduction</title>
  18     </sect2>
  19     -->
  20
  21     <sect2 id="zend.tool.usage.cli.installation">
  22         <title>Installation</title>
  23
  24         <sect3 id="zend.tool.usage.cli.installation.download-and-go">
  25             <title>Download And Go</title>
  26
  27             <para>
  28                 First download Zend Framework. This can be done by going to framework.zend.com
  29                 and downloading the latest release. After you've downloaded the package and placed
  30                 it on your system. The next step is to make the zf command available to your
  31                 system. The easiest way to do this, is to copy the proper files from the bin/
  32                 directory of the download, and place these files within the
  33                 <emphasis>same</emphasis> directory as the location of the <acronym>PHP</acronym>
  34                 cli binary.
  35             </para>
  36         </sect3>
  37
  38         <sect3 id="zend.tool.usage.cli.installation.pear">
  39             <title>Installing Via Pear</title>
  40
  41             <para>
  42                 To install via PEAR, you must use the 3rd party zfcampus.org site to retrieve the
  43                 latest Zend Framework PEAR package. These packages are typically built within a day
  44                 of an official Zend Framework release. The benefit of installing via the PEAR
  45                 package manager is that during the install process, the ZF library will end up on
  46                 the include_path, and the zf.php and zf scripts will end up in a place on your
  47                 system that will allow you to run them without any additional setup.
  48             </para>
  49
  50             <programlisting language="text"><![CDATA[
  51 pear discover-channel pear.zfcampus.org
  52 pear install zfcampus/zf
  53 ]]></programlisting>
  54
  55             <para>
  56                 That is it. After the initial install, you should be able to continue on by
  57                 running the zf command. Go good way to check to see if it't there is to run
  58                 zf --help
  59             </para>
  60         </sect3>
  61
  62         <sect3 id="zend.tool.usage.cli.installation.install-by-hand">
  63             <title>Installing by Hand</title>
  64
  65             <para>
  66                 Installing by hand refers to the process of forcing the zf.php and Zend Framework
  67                 library to work together when they are placed in non-convential places, or at least,
  68                 in a place that your system cannot dispatch from easily (typical of programs in your
  69                 system PATH).
  70             </para>
  71
  72             <para>
  73                 If you are on a *nix or mac system, you can also create a link from somewhere in
  74                 your path to the zf.sh file. If you do this, you do not need to worry about having
  75                 Zend Framework's library on your include_path, as the zf.php and zf.sh files will
  76                 be able to access the library relative to where they are (meaning the ./bin/ files
  77                 are ../library/ relative to the Zend Framework library).
  78             </para>
  79
  80             <para>
  81                 There are a number of other options available for setting up the zf.php and library
  82                 on your system. These options revolve around setting specific environment
  83                 variables. These are described in the later section on "customizing the CLI
  84                 environement". The environment variables for setting the zf.php include_path,
  85                 ZF_INCLUDE_PATH and ZF_INCLUDE_PATH_PREPEND, are the ones of most interest.
  86             </para>
  87         </sect3>
  88     </sect2>
  89
  90     <sect2 id="zend.tool.usage.cli.general-purpose-commands">
  91         <title>General Purpose Commands</title>
  92
  93         <sect3 id="zend.tool.usage.cli.general-purpose-commands.version">
  94             <title>Version</title>
  95
  96             <para>
  97                 This will show the current version number of the copy of Zend Framework the zf.php
  98                 tool is using.
  99             </para>
 100
 101             <programlisting language="text"><![CDATA[
 102 zf show version
 103 ]]></programlisting>
 104         </sect3>
 105
 106         <sect3 id="zend.tool.usage.cli.general-purpose-commands.built-in-help">
 107             <title>Built-in Help</title>
 108
 109             <para>
 110                 The built-in help system is the primary place where you can get up-to-date
 111                 information on what your system is capable of doing. The help system is dynamic in
 112                 that as providers are added to your system, they are automatically dispatchable, and
 113                 as such, the parameters required to run them will be in the help screen. The
 114                 easiest way to retrieve the help screen is the following:
 115             </para>
 116
 117             <programlisting language="text"><![CDATA[
 118 zf --help
 119 ]]></programlisting>
 120
 121             <para>
 122                 This will give you an overview of the various capabilities of the system.
 123                 Sometimes, there are more finite commands than can be run, and to gain more
 124                 information about these, you might have to run a more specialized help command.
 125                 For specialized help, simply replace any of the elements of the command with a "?".
 126                 This will tell the help system that you want more information about what commands
 127                 can go in place of the question mark. For example:
 128             </para>
 129
 130             <programlisting language="text"><![CDATA[
 131 zf ? controller
 132 ]]></programlisting>
 133
 134             <para>
 135                 The above means "show me all 'actions' for the provider 'controller'"; while the
 136                 following:
 137             </para>
 138
 139             <programlisting language="text"><![CDATA[
 140 zf show ?
 141 ]]></programlisting>
 142
 143             <para>
 144                 means "show me all providers that support the 'show' action". This works for
 145                 drilling down into options as well as you can see in the following examples:
 146             </para>
 147
 148             <programlisting language="text"><![CDATA[
 149 zf show version.? (show any specialties)
 150 zf show version ? (show any options)
 151 ]]></programlisting>
 152         </sect3>
 153
 154         <sect3 id="zend.tool.usage.cli.general-purpose-commands.manifest">
 155             <title>Manifest</title>
 156
 157             <para>
 158                 This will show what information is in the tooling systems manifest. This is more
 159                 important for provider developers than casual users of the tooling system.
 160             </para>
 161
 162             <programlisting language="text"><![CDATA[
 163 zf show manifest
 164 ]]></programlisting>
 165         </sect3>
 166
 167         <!--
 168         <sect3 id="zend.tool.usage.cli.general-purpose-commands.tool-configuration">
 169             <title>Tool Configuration</title>
 170
 171             <para>Placeholder   need docs from @beberli </para>
 172
 173         </sect3>
 174         -->
 175     </sect2>
 176
 177     <sect2 id="zend.tool.usage.cli.project-specific-commands">
 178         <title>Project Specific Commands</title>
 179
 180         <sect3 id="zend.tool.usage.cli.project-specific-commands.project">
 181             <title>Project</title>
 182
 183             <para>
 184                 The project provider is the first command you might want to run. This will setup the
 185                 basic structure of your application. This is required before any of the other
 186                 providers can be executed.
 187             </para>
 188
 189             <programlisting language="text"><![CDATA[
 190 zf create project MyProjectName
 191 ]]></programlisting>
 192
 193             <para>
 194                 This will create a project in a directory called ./MyProjectName. From this point
 195                 on, it is important to note that any subsequent commands on the command line must be
 196                 issued from within the project directory you had just created. So, after creation,
 197                 changing into that directory is required.
 198             </para>
 199         </sect3>
 200
 201         <sect3 id="zend.tool.usage.cli.project-specific-commands.module">
 202             <title>Project</title>
 203
 204             <para>
 205                 The module provider allows for the easy creation of a Zend Framework module. A
 206                 module follows the hMVC pattern loosely. When creating modules, it will take the
 207                 same structure used at the application/ level, and duplicate it inside of the chosen
 208                 name for your module, inside of the "modules" directory of the application/
 209                 directory without duplicating the modules directory itself. For example:
 210             </para>
 211
 212             <programlisting language="text"><![CDATA[
 213 zf create module Blog
 214 ]]></programlisting>
 215
 216             <para>
 217                 This will create a module named Blog at application/modules/Blog, and all of the
 218                 artifacts that a module will need.
 219             </para>
 220         </sect3>
 221
 222         <sect3 id="zend.tool.usage.cli.project-specific-commands.controller">
 223             <title>Controller</title>
 224
 225             <para>
 226                 The controller provider is responsible for creating (mostly) empty controllers as
 227                 well as their corresponding view script directories and files. To utilize it to
 228                 create an 'Auth' controlller, for example, execute:
 229             </para>
 230
 231             <programlisting language="text"><![CDATA[
 232 zf create controller Auth
 233 ]]></programlisting>
 234
 235             <para>
 236                 This will create a controller named Auth, specifically it will create a file at
 237                 application/controllers/AuthController.php with the AuthController inside.
 238                 If you wish to create a controller for a module, use any of the following:
 239             </para>
 240
 241             <programlisting language="text"><![CDATA[
 242 zf create controller Post 1 Blog
 243 zf create controller Post -m Blog
 244 zf create controller Post --module=Blog
 245 ]]></programlisting>
 246
 247             <para>
 248                 Note: In the first command, 1 is the value for the "includeIndexAction" flag.
 249             </para>
 250         </sect3>
 251
 252         <sect3 id="zend.tool.usage.cli.project-specific-commands.action">
 253             <title>Action</title>
 254
 255             <para>
 256                 To create an action within an existing controller:
 257             </para>
 258
 259             <programlisting language="text"><![CDATA[
 260 zf create action login Auth
 261 zf create action login -c Auth
 262 zf create action login --controller-name=Auth
 263 ]]></programlisting>
 264         </sect3>
 265
 266         <sect3 id="zend.tool.usage.cli.project-specific-commands.view">
 267             <title>View</title>
 268
 269             <para>
 270                 To create a view outside of the normal controller/action creation, you would use
 271                 one of the following:
 272             </para>
 273
 274             <programlisting language="text"><![CDATA[
 275 zf create view Auth my-script-name
 276 zf create view -c Auth -a my-script-name
 277             ]]></programlisting>
 278
 279             <para>
 280                 This will create a view script in the controller folder of Auth.
 281             </para>
 282         </sect3>
 283
 284         <sect3 id="zend.tool.usage.cli.project-specific-commands.model">
 285             <title>Model</title>
 286
 287             <para>
 288                 The model provider is only responsible for creating the proper model files,
 289                 with the proper name inside the application folder. For example
 290             </para>
 291
 292             <programlisting language="text"><![CDATA[
 293 zf create model User
 294 ]]></programlisting>
 295
 296             <para>
 297                 If you wish to create a model within a specific module:
 298             </para>
 299
 300             <programlisting language="text"><![CDATA[
 301 zf create model Post -m Blog
 302 ]]></programlisting>
 303
 304             <para>
 305                 The above will create a 'Post' model inside of the 'Blog' module.
 306             </para>
 307         </sect3>
 308
 309         <sect3 id="zend.tool.usage.cli.project-specific-commands.form">
 310             <title>Form</title>
 311
 312             <para>
 313                 The form provider is only responsible for creating the proper form file and
 314                 init() method, with the proper name inside the application folder. For example:
 315             </para>
 316
 317             <programlisting language="text"><![CDATA[
 318 zf create form Auth
 319 ]]></programlisting>
 320
 321             <para>
 322                 If you wish to create a model within a specific module:
 323             </para>
 324
 325             <programlisting language="text"><![CDATA[
 326 zf create form Comment -m Blog
 327 ]]></programlisting>
 328
 329             <para>
 330                 The above will create a 'Comment' form inside of the 'Blog' module.
 331             </para>
 332         </sect3>
 333
 334         <sect3 id="zend.tool.usage.cli.project-specific-commands.database-adapter">
 335             <title>DbAdapter</title>
 336
 337             <para>
 338                 To configure a DbAdapter, you will need to provide the information as a url
 339                 encoded string. This string needs to be in quotes on the command line.
 340             </para>
 341
 342             <para>
 343                 For example, to enter the following information:
 344
 345                 <itemizedlist>
 346                     <listitem>
 347                         <para>adapter: Pdo_Mysql</para>
 348                     </listitem>
 349
 350                     <listitem>
 351                         <para>username: test</para>
 352                     </listitem>
 353
 354                     <listitem>
 355                         <para>password: test</para>
 356                     </listitem>
 357
 358                     <listitem>
 359                         <para>dbname: test </para>
 360                     </listitem>
 361                 </itemizedlist>
 362
 363                 The following will have to be run on the command line:
 364             </para>
 365
 366
 367             <programlisting language="text"><![CDATA[
 368 zf configure dbadapter "adapter=Pdo_Mysql&username=test&password=test&dbname=test"
 369 ]]></programlisting>
 370
 371             <para>
 372                 This assumes you wish to store this information inside of the
 373                 'production' space of the application configuration file. The following will
 374                 demonstrate an sqlite configuration, in the 'development' section of the
 375                 application config file.
 376             </para>
 377
 378             <programlisting language="text"><![CDATA[
 379 zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" development
 380 zf configure dbadapter "adapter=Pdo_Sqlite&dbname=../data/test.db" -s development
 381 ]]></programlisting>
 382         </sect3>
 383
 384         <sect3 id="zend.tool.usage.cli.project-specific-commands.db-table">
 385             <title>DbTable</title>
 386
 387             <para>
 388                 The DbTable provider is responsible for creating Zend_Db_Table
 389                 model/data access files for your application to consume, with the proper
 390                 class name, and in the proper location in the application. The two
 391                 important pieces of information are the <emphasis>DbTable name</emphasis>,
 392                 and the <emphasis>actual database table name</emphasis>. For example:
 393             </para>
 394
 395             <programlisting language="text"><![CDATA[
 396 zf create dbtable User user
 397 zf create dbtable User -a user
 398
 399 // also accepts a force option to overwrite existing files
 400 zf create dbtable User user -f
 401 zf create dbtable User user --force-override
 402 ]]></programlisting>
 403
 404             <para>
 405                 The DbTable provider is also capable of creating the proper files by
 406                 scanning the database configured with the above DbAdapter provider.
 407             </para>
 408
 409             <programlisting language="text"><![CDATA[
 410 zf create dbtable.from-database
 411 ]]></programlisting>
 412
 413             <para>
 414                 When executing the above, it might make sense to use the pretend / "-p"
 415                 flag first so that you can see what would be done, and what tables can
 416                 be found in the database.
 417             </para>
 418
 419             <programlisting language="text"><![CDATA[
 420 zf -p create dbtable.from-database
 421 ]]></programlisting>
 422         </sect3>
 423
 424         <sect3 id="zend.tool.usage.cli.project-specific-commands.layout">
 425             <title>Layout</title>
 426
 427             <para>
 428                 Currently, the only supported action for layouts is simply to enable them
 429                 will setup the proper keys in the application.ini file for the application
 430                 resource to work, and create the proper directories and layout.phtml file.
 431             </para>
 432
 433             <programlisting language="text"><![CDATA[
 434 zf enable layout
 435 ]]></programlisting>
 436         </sect3>
 437     </sect2>
 438
 439     <sect2 id="zend.tool.usage.cli.environment-customization">
 440         <title>Environment Customization</title>
 441
 442         <sect3 id="zend.tool.usage.cli.environment-customization.storage-directory">
 443             <title>The Storage Directory</title>
 444
 445             <para>
 446                 The storage directory is important so that providers may have a place to find
 447                 custom user generated logic that might change the way they behave. One example
 448                 can be found below is the placement of a custom project profile file.
 449             </para>
 450
 451             <programlisting language="text"><![CDATA[
 452 zf --setup storage-directory
 453 ]]></programlisting>
 454         </sect3>
 455
 456         <sect3 id="zend.tool.usage.cli.environment-customization.configuration-file">
 457             <title>The Configuration File</title>
 458
 459             <para>
 460                 This will create the proper zf.ini file. This <emphasis>should</emphasis>
 461                 be run after <code>zf --setup storage-directory</code>. If it is not, it will
 462                 be located inside the users home directory. If it is, it will be located inside
 463                 the users storage directory.
 464             </para>
 465
 466             <programlisting language="text"><![CDATA[
 467 zf --setup config-file
 468 ]]></programlisting>
 469         </sect3>
 470
 471         <sect3 id="zend.tool.usage.cli.environment-customization.environment-locations">
 472             <title>Environment Locations</title>
 473
 474             <para>
 475                 These should be set if you wish to override the default places where zf will
 476                 attempt to read their values.
 477             </para>
 478
 479             <itemizedlist>
 480                 <listitem>
 481                     <para>ZF_HOME</para>
 482
 483                     <itemizedlist>
 484                         <listitem>
 485                             <para>the directory this tool will look for a home directory</para>
 486                         </listitem>
 487
 488                         <listitem><para>directory must exist</para></listitem>
 489
 490                         <listitem>
 491                             <para>search order:</para>
 492
 493                             <itemizedlist>
 494                                 <listitem><para>ZF_HOME environment variable</para></listitem>
 495                                 <listitem><para>HOME environment variable</para></listitem>
 496                                 <listitem><para>then HOMEPATH environment variable</para></listitem>
 497                             </itemizedlist>
 498                         </listitem>
 499                     </itemizedlist>
 500                 </listitem>
 501
 502                 <listitem>
 503                     <para>ZF_STORAGE_DIRECTORY</para>
 504
 505                     <itemizedlist>
 506                         <listitem>
 507                             <para>where this tool will look for a storage directory</para>
 508                         </listitem>
 509
 510                         <listitem><para>directory must exist</para></listitem>
 511
 512                         <listitem>
 513                             <para>search order:</para>
 514
 515                             <itemizedlist>
 516                                 <listitem>
 517                                     <para>ZF_STORAGE_DIRECTORY environment variable</para>
 518                                 </listitem>
 519
 520                                 <listitem><para>$homeDirectory/.zf/ directory</para></listitem>
 521                             </itemizedlist>
 522                         </listitem>
 523                     </itemizedlist>
 524                 </listitem>
 525
 526                 <listitem>
 527                     <para>ZF_CONFIG_FILE</para>
 528
 529                     <itemizedlist>
 530                         <listitem>
 531                             <para>where this tool will look for a configuration file</para>
 532                         </listitem>
 533
 534                         <listitem>
 535                             <para>search order:</para>
 536
 537                             <itemizedlist>
 538                                 <listitem>
 539                                     <para>ZF_CONFIG_FILE environment variable</para>
 540                                 </listitem>
 541
 542                                 <listitem>
 543                                     <para>$homeDirectory/.zf.ini file if it exists</para>
 544                                 </listitem>
 545
 546                                 <listitem>
 547                                     <para>$storageDirectory/zf.ini file if it exists</para>
 548                                 </listitem>
 549                             </itemizedlist>
 550                         </listitem>
 551                     </itemizedlist>
 552                 </listitem>
 553
 554                 <listitem>
 555                     <para>ZF_INCLUDE_PATH</para>
 556
 557                     <itemizedlist>
 558                         <listitem>
 559                             <para>set the include_path for this tool to use this value</para>
 560                         </listitem>
 561
 562                         <listitem>
 563                             <para>original behavior:</para>
 564
 565                             <itemizedlist>
 566                                 <listitem>
 567                                     <para>
 568                                         use <acronym>PHP</acronym>'s include_path to find ZF
 569                                     </para>
 570                                 </listitem>
 571
 572                                 <listitem>
 573                                     <para>use the ZF_INCLUDE_PATH environment variable</para>
 574                                 </listitem>
 575
 576                                 <listitem>
 577                                     <para>
 578                                         use the path ../library (relative to zf.php) to find ZF
 579                                     </para>
 580                                 </listitem>
 581                             </itemizedlist>
 582                         </listitem>
 583                     </itemizedlist>
 584                 </listitem>
 585
 586                 <listitem>
 587                     <para>ZF_INCLUDE_PATH_PREPEND</para>
 588
 589                     <itemizedlist>
 590                         <listitem>
 591                             <para>prepend the current php.ini include_path with this value</para>
 592                         </listitem>
 593                     </itemizedlist>
 594                 </listitem>
 595             </itemizedlist>
 596         </sect3>
 597     </sect2>
 598 </sect1>