documentation/manual/en/tutorials/quickstart-create-project.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.quickstart.create-project">
   4     <title>Create Your Project</title>
   5
   6     <para>
   7         In order to create your project, you must first download and extract Zend Framework.
   8     </para>
   9
  10     <sect2 id="learning.quickstart.create-project.install-zf">
  11         <title>Install Zend Framework</title>
  12
  13         <para>
  14             The easiest way to get Zend Framework along with a complete <acronym>PHP</acronym> stack
  15             is by installing <ulink url="http://www.zend.com/en/products/server-ce/downloads">Zend
  16                 Server</ulink>. Zend Server has native installers for Mac OSX, Windows, Fedora Core,
  17             and Ubuntu, as well as a universal installation package compatible with most Linux
  18             distributions.
  19         </para>
  20
  21         <para>
  22             After you have installed Zend Server, the Framework files may be found
  23             under <filename>/usr/local/zend/share/ZendFramework</filename> on Mac OSX and Linux,
  24             and <filename>C:\Program Files\Zend\ZendServer\share\ZendFramework</filename> on
  25             Windows. The <constant>include_path</constant> will already be configured to include
  26             Zend Framework.
  27         </para>
  28
  29         <para>
  30             Alternately, you can <ulink url="http://framework.zend.com/download/latest">Download the
  31             latest version of Zend Framework</ulink> and extract the contents; make a note of where
  32             you have done so.
  33         </para>
  34
  35         <para>
  36             Optionally, you can add the path to the <filename>library/</filename> subdirectory of
  37             the archive to your <filename>php.ini</filename>'s <constant>include_path</constant>
  38             setting.
  39         </para>
  40
  41         <para>
  42             That's it! Zend Framework is now installed and ready to use.
  43         </para>
  44     </sect2>
  45
  46     <sect2 id="learning.quickstart.create-project.create-project">
  47         <title>Create Your Project</title>
  48
  49         <note>
  50             <title>zf Command Line Tool</title>
  51
  52             <para>
  53                 In your Zend Framework installation is a <filename>bin/</filename> subdirectory,
  54                 containing the scripts <filename>zf.sh</filename> and <filename>zf.bat</filename>
  55                 for Unix-based and Windows-based users, respectively. Make a note of the absolute
  56                 path to this script.
  57             </para>
  58
  59             <para>
  60                 Wherever you see references to the command <command>zf</command>, please substitute
  61                 the absolute path to the script. On Unix-like systems, you may want to use your
  62                 shell's alias functionality: <command>alias
  63                     zf.sh=path/to/ZendFramework/bin/zf.sh</command>.
  64             </para>
  65
  66             <para>
  67                 If you have problems setting up the <command>zf</command> command-line tool, please
  68                 refer to <link linkend="zend.tool.framework.clitool">the
  69                     manual</link>.
  70             </para>
  71         </note>
  72
  73         <para>
  74             Open a terminal (in Windows, <command>Start -> Run</command>, and then use
  75             <command>cmd</command>). Navigate to a directory where you would like to start a
  76             project. Then, use the path to the appropriate script, and execute one of the following:
  77         </para>
  78
  79         <programlisting language="shell"><![CDATA[
  80 % zf create project quickstart
  81 ]]></programlisting>
  82
  83         <para>
  84             Running this command will create your basic site structure, including your initial
  85             controllers and views. The tree looks like the following:
  86         </para>
  87
  88         <programlisting language="text"><![CDATA[
  89 quickstart
  90 |-- application
  91 |   |-- Bootstrap.php
  92 |   |-- configs
  93 |   |   `-- application.ini
  94 |   |-- controllers
  95 |   |   |-- ErrorController.php
  96 |   |   `-- IndexController.php
  97 |   |-- models
  98 |   `-- views
  99 |       |-- helpers
 100 |       `-- scripts
 101 |           |-- error
 102 |           |   `-- error.phtml
 103 |           `-- index
 104 |               `-- index.phtml
 105 |-- library
 106 |-- public
 107 |   |-- .htaccess
 108 |   `-- index.php
 109 `-- tests
 110     |-- application
 111     |   `-- bootstrap.php
 112     |-- library
 113     |   `-- bootstrap.php
 114     `-- phpunit.xml
 115 ]]></programlisting>
 116
 117         <para>
 118             At this point, if you haven't added Zend Framework to your
 119             <constant>include_path</constant>, we recommend either copying or symlinking it into
 120             your <filename>library/</filename> directory. In either case, you'll want to either
 121             recursively copy or symlink the <filename>library/Zend/</filename> directory of your
 122             Zend Framework installation into the <filename>library/</filename> directory of your
 123             project. On unix-like systems, that would look like one of the following:
 124         </para>
 125
 126         <programlisting language="shell"><![CDATA[
 127 # Symlink:
 128 % cd library; ln -s path/to/ZendFramework/library/Zend .
 129
 130 # Copy:
 131 % cd library; cp -r path/to/ZendFramework/library/Zend .
 132 ]]></programlisting>
 133
 134         <para>
 135             On Windows systems, it may be easiest to do this from the Explorer.
 136         </para>
 137
 138         <para>
 139             Now that the project is created, the main artifacts to begin understanding are the
 140             bootstrap, configuration, action controllers, and views.
 141         </para>
 142     </sect2>
 143
 144     <sect2 id="learning.quickstart.create-project.bootstrap">
 145         <title>The Bootstrap</title>
 146
 147         <para>
 148             Your <classname>Bootstrap</classname> class defines what resources and components to
 149             initialize. By default, Zend Framework's <link linkend="zend.controller.front">Front
 150                 Controller</link> is initialized, and it uses the
 151             <filename>application/controllers/</filename> as the default directory in which to look
 152             for action controllers (more on that later). The class looks like the following:
 153         </para>
 154
 155         <programlisting language="php"><![CDATA[
 156 // application/Bootstrap.php
 157
 158 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 159 {
 160 }
 161 ]]></programlisting>
 162
 163         <para>
 164             As you can see, not much is necessary to begin with.
 165         </para>
 166     </sect2>
 167
 168     <sect2 id="learning.quickstart.create-project.configuration">
 169         <title>Configuration</title>
 170
 171         <para>
 172             While Zend Framework is itself configurationless, you often need to configure your
 173             application. The default configuration is placed in
 174             <filename>application/configs/application.ini</filename>, and contains some basic
 175             directives for setting your <acronym>PHP</acronym> environment (for instance, turning
 176             error reporting on and off), indicating the path to your bootstrap class (as well as its
 177             class name), and the path to your action controllers. It looks as follows:
 178         </para>
 179
 180         <programlisting language="ini"><![CDATA[
 181 ; application/configs/application.ini
 182
 183 [production]
 184 phpSettings.display_startup_errors = 0
 185 phpSettings.display_errors = 0
 186 includePaths.library = APPLICATION_PATH "/../library"
 187 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
 188 bootstrap.class = "Bootstrap"
 189 appnamespace = "Application"
 190 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
 191 resources.frontController.params.displayExceptions = 0
 192
 193 [staging : production]
 194
 195 [testing : production]
 196 phpSettings.display_startup_errors = 1
 197 phpSettings.display_errors = 1
 198
 199 [development : production]
 200 phpSettings.display_startup_errors = 1
 201 phpSettings.display_errors = 1
 202 ]]></programlisting>
 203
 204         <para>
 205             Several things about this file should be noted. First, when using
 206             <acronym>INI</acronym>-style configuration, you can reference constants directly and
 207             expand them; <constant>APPLICATION_PATH</constant> is actually a constant. Additionally
 208             note that there are several sections defined: production, staging, testing, and
 209             development. The latter three inherit settings from the "production" environment. This
 210             is a useful way to organize configuration to ensure that appropriate settings are
 211             available in each stage of application development.
 212         </para>
 213     </sect2>
 214
 215     <sect2 id="learning.quickstart.create-project.action-controllers">
 216         <title>Action Controllers</title>
 217
 218         <para>
 219             Your application's <emphasis>action controllers</emphasis> contain your application
 220             workflow, and do the work of mapping your requests to the appropriate models and views.
 221         </para>
 222
 223         <para>
 224             An action controller should have one or more methods ending in "Action"; these methods
 225             may then be requested via the web. By default, Zend Framework URLs follow the schema
 226             <constant>/controller/action</constant>, where "controller" maps to the action
 227             controller name (minus the "Controller" suffix) and "action" maps to an action method
 228             (minus the "Action" suffix).
 229         </para>
 230
 231         <para>
 232             Typically, you always need an <classname>IndexController</classname>, which is a
 233             fallback controller and which also serves the home page of the site, and an
 234             <classname>ErrorController</classname>, which is used to indicate things such as
 235             <acronym>HTTP</acronym> 404 errors (controller or action not found) and
 236             <acronym>HTTP</acronym> 500 errors (application errors).
 237         </para>
 238
 239         <para>
 240             The default <classname>IndexController</classname> is as follows:
 241         </para>
 242
 243         <programlisting language="php"><![CDATA[
 244 // application/controllers/IndexController.php
 245
 246 class IndexController extends Zend_Controller_Action
 247 {
 248
 249     public function init()
 250     {
 251         /* Initialize action controller here */
 252     }
 253
 254     public function indexAction()
 255     {
 256         // action body
 257     }
 258 }
 259 ]]></programlisting>
 260
 261         <para>
 262             And the default <classname>ErrorController</classname> is as follows:
 263         </para>
 264
 265         <programlisting language="php"><![CDATA[
 266 // application/controllers/ErrorController.php
 267
 268 class ErrorController extends Zend_Controller_Action
 269 {
 270
 271     public function errorAction()
 272     {
 273         $errors = $this->_getParam('error_handler');
 274
 275         switch ($errors->type) {
 276             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
 277             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
 278             case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
 279
 280                 // 404 error -- controller or action not found
 281                 $this->getResponse()->setHttpResponseCode(404);
 282                 $this->view->message = 'Page not found';
 283                 break;
 284             default:
 285                 // application error
 286                 $this->getResponse()->setHttpResponseCode(500);
 287                 $this->view->message = 'Application error';
 288                 break;
 289         }
 290
 291         $this->view->exception = $errors->exception;
 292         $this->view->request   = $errors->request;
 293     }
 294 }
 295 ]]></programlisting>
 296
 297         <para>
 298             You'll note that (1) the <classname>IndexController</classname> contains no real code,
 299             and (2) the <classname>ErrorController</classname> makes reference to a "view" property.
 300             That leads nicely into our next subject.
 301         </para>
 302     </sect2>
 303
 304     <sect2 id="learning.quickstart.create-project.views">
 305         <title>Views</title>
 306
 307         <para>
 308             Views in Zend Framework are written in plain old <acronym>PHP</acronym>. View scripts
 309             are placed in <filename>application/views/scripts/</filename>, where they are further
 310             categorized using the controller names. In our case, we have an
 311             <classname>IndexController</classname> and an <classname>ErrorController</classname>,
 312             and thus we have corresponding <filename>index/</filename> and
 313             <filename>error/</filename> subdirectories within our view scripts directory. Within
 314             these subdirectories, you will then find and create view scripts that correspond to each
 315             controller action exposed; in the default case, we thus have the view scripts
 316             <filename>index/index.phtml</filename> and <filename>error/error.phtml</filename>.
 317         </para>
 318
 319         <para>
 320             View scripts may contain any markup you want, and use the <emphasis>&lt;?php</emphasis>
 321             opening tag and <emphasis>?&gt;</emphasis> closing tag to insert <acronym>PHP</acronym>
 322             directives.
 323         </para>
 324
 325         <para>
 326             The following is what we install by default for the
 327             <filename>index/index.phtml</filename> view script:
 328         </para>
 329
 330         <programlisting language="php"><![CDATA[
 331 <!-- application/views/scripts/index/index.phtml -->
 332 <style>
 333
 334     a:link,
 335     a:visited
 336     {
 337         color: #0398CA;
 338     }
 339
 340     span#zf-name
 341     {
 342         color: #91BE3F;
 343     }
 344
 345     div#welcome
 346     {
 347         color: #FFFFFF;
 348         background-image: url(http://framework.zend.com/images/bkg_header.jpg);
 349         width:  600px;
 350         height: 400px;
 351         border: 2px solid #444444;
 352         overflow: hidden;
 353         text-align: center;
 354     }
 355
 356     div#more-information
 357     {
 358         background-image: url(http://framework.zend.com/images/bkg_body-bottom.gif);
 359         height: 100%;
 360     }
 361
 362 </style>
 363 <div id="welcome">
 364     <h1>Welcome to the <span id="zf-name">Zend Framework!</span><h1 />
 365     <h3>This is your project's main page<h3 />
 366     <div id="more-information">
 367         <p>
 368             <img src="http://framework.zend.com/images/PoweredBy_ZF_4LightBG.png" />
 369         </p>
 370
 371         <p>
 372             Helpful Links: <br />
 373             <a href="http://framework.zend.com/">Zend Framework Website</a> |
 374             <a href="http://framework.zend.com/manual/en/">Zend Framework
 375                 Manual</a>
 376         </p>
 377     </div>
 378 </div>
 379 ]]></programlisting>
 380
 381         <para>
 382             The <filename>error/error.phtml</filename> view script is slightly more interesting as
 383             it uses some <acronym>PHP</acronym> conditionals:
 384         </para>
 385
 386         <programlisting language="php"><![CDATA[
 387 <!-- application/views/scripts/error/error.phtml -->
 388 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN";
 389     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd>
 390 <html xmlns="http://www.w3.org/1999/xhtml">
 391 <head>
 392   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 393   <title>Zend Framework Default Application</title>
 394 </head>
 395 <body>
 396   <h1>An error occurred</h1>
 397   <h2><?php echo $this->message ?></h2>
 398
 399   <?php if ('development' == $this->env): ?>
 400
 401   <h3>Exception information:</h3>
 402   <p>
 403       <b>Message:</b> <?php echo $this->exception->getMessage() ?>
 404   </p>
 405
 406   <h3>Stack trace:</h3>
 407   <pre><?php echo $this->exception->getTraceAsString() ?>
 408   </pre>
 409
 410   <h3>Request Parameters:</h3>
 411   <pre><?php echo var_export($this->request->getParams(), 1) ?>
 412   </pre>
 413   <?php endif ?>
 414
 415 </body>
 416 </html>
 417 ]]></programlisting>
 418     </sect2>
 419
 420     <sect2 id="learning.quickstart.create-project.vhost">
 421         <title>Create a virtual host</title>
 422
 423         <para>
 424             For purposes of this quick start, we will assume you are using the <ulink
 425                 url="http://httpd.apache.org/">Apache web server</ulink>. Zend Framework works
 426             perfectly well with other web servers -- including Microsoft Internet Information
 427             Server, lighttpd, nginx, and more -- but most developers should be famililar with Apache
 428             at the minimum, and it provides an easy introduction to Zend Framework's directory
 429             structure and rewrite capabilities.
 430         </para>
 431
 432         <para>
 433             To create your vhost, you need to know the location of your
 434             <filename>httpd.conf</filename> file, and potentially where other configuration files
 435             are located. Some common locations:
 436         </para>
 437
 438         <itemizedlist>
 439             <listitem>
 440                 <para>
 441                     <filename>/etc/httpd/httpd.conf</filename> (Fedora, RHEL, and others)
 442                 </para>
 443             </listitem>
 444
 445             <listitem>
 446                 <para>
 447                     <filename>/etc/apache2/httpd.conf</filename> (Debian, Ubuntu, and others)
 448                 </para>
 449             </listitem>
 450
 451             <listitem>
 452                 <para>
 453                     <filename>/usr/local/zend/etc/httpd.conf</filename> (Zend Server on *nix
 454                     machines)
 455                 </para>
 456             </listitem>
 457
 458             <listitem>
 459                 <para>
 460                     <filename>C:\Program Files\Zend\Apache2\conf</filename> (Zend Server on Windows
 461                     machines)
 462                 </para>
 463             </listitem>
 464         </itemizedlist>
 465
 466         <para>
 467             Within your <filename>httpd.conf</filename> (or <filename>httpd-vhosts.conf</filename>
 468             on some systems), you will need to do two things. First, ensure that the
 469             <varname>NameVirtualHost</varname> is defined; typically, you will set it to a value of
 470             "*:80". Second, define a virtual host:
 471         </para>
 472
 473         <programlisting language="apache"><![CDATA[
 474 <VirtualHost *:80>
 475     ServerName quickstart.local
 476     DocumentRoot /path/to/quickstart/public
 477
 478     SetEnv APPLICATION_ENV "development"
 479
 480     <Directory /path/to/quickstart/public>
 481         DirectoryIndex index.php
 482         AllowOverride All
 483         Order allow,deny
 484         Allow from all
 485     </Directory>
 486 </VirtualHost>
 487 ]]></programlisting>
 488
 489         <para>
 490             There are several things to note. First, note that the <varname>DocumentRoot</varname>
 491             setting specifies the <filename>public</filename> subdirectory of our project; this
 492             means that only files under that directory can ever be served directly by the server.
 493             Second, note the <varname>AllowOverride</varname>, <varname>Order</varname>, and
 494             <varname>Allow</varname> directives; these are to allow us to use
 495             <filename>htacess</filename> files within our project. During development, this is a
 496             good practice, as it prevents the need to constantly restart the web server as you make
 497             changes to your site directives; however, in production, you should likely push the
 498             content of your <filename>htaccess</filename> file into your server configuration and
 499             disable this. Third, note the <varname>SetEnv</varname> directive. What we are doing
 500             here is setting an environment variable for your virtual host; this variable will be
 501             picked up in the <filename>index.php</filename> and used to set the
 502             <constant>APPLICATION_ENV</constant> constant for our Zend Framework application. In
 503             production, you can omit this directive (in which case it will default to the value
 504             "production") or set it explicitly to "production".
 505         </para>
 506
 507         <para>
 508             Finally, you will need to add an entry in your <filename>hosts</filename> file
 509             corresponding to the value you place in your <varname>ServerName</varname> directive. On
 510             *nix-like systems, this is usually <filename>/etc/hosts</filename>; on Windows, you'll
 511             typically find it in <filename>C:\WINDOWS\system32\drivers\etc</filename>. Regardless of
 512             the system, the entry will look like the following:
 513         </para>
 514
 515         <programlisting language="text"><![CDATA[
 516 127.0.0.1 quickstart.local
 517 ]]></programlisting>
 518
 519         <para>
 520             Start your webserver (or restart it), and you should be ready to go.
 521         </para>
 522     </sect2>
 523
 524     <sect2 id="learning.quickstart.create-project.checkpoint">
 525         <title>Checkpoint</title>
 526
 527         <para>
 528             At this point, you should be able to fire up your initial Zend Framework application.
 529             Point your browser to the server name you configured in the previous section; you should
 530             be able to see a welcome page at this point.
 531         </para>
 532     </sect2>
 533 </sect1>