documentation/manual/en/module_specs/Zend_Application-QuickStart.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.application.quick-start">
   4     <title>Zend_Application Quick Start</title>
   5
   6     <para>
   7         There are two paths to getting started with
   8         <classname>Zend_Application</classname>, and they depend on how you start your
   9         project. In each case, you always start with creating a
  10         <classname>Bootstrap</classname> class, and a related configuration file.
  11     </para>
  12
  13     <para>
  14         If you plan on using <classname>Zend_Tool</classname> to create your project,
  15         continue reading below. If you will be adding
  16         <classname>Zend_Application</classname> to an existing project, you'll want to
  17         <link linkend="zend.application.quick-start.manual">skip ahead</link>.
  18     </para>
  19
  20     <sect2 id="zend.application.quick-start.zend-tool">
  21         <title>Using Zend_Tool</title>
  22
  23         <para>
  24             The quickest way to start using <classname>Zend_Application</classname> is to use
  25             <classname>Zend_Tool</classname> to generate your project. This will also create
  26             your <classname>Bootstrap</classname> class and file.
  27         </para>
  28
  29         <para>
  30             To create a project, execute the <command>zf</command> command (on *nix systems):
  31         </para>
  32
  33         <programlisting language="sh"><![CDATA[
  34 % zf create project newproject
  35 ]]></programlisting>
  36
  37         <para>
  38             Or the Windows <filename>zf.bat</filename> command:
  39         </para>
  40
  41         <programlisting language="dos"><![CDATA[
  42 C:> zf.bat create project newproject
  43 ]]></programlisting>
  44
  45         <para>
  46             Both will create a project structure that looks like the following:
  47         </para>
  48
  49         <programlisting language="text"><![CDATA[
  50 newproject
  51 |-- application
  52 |   |-- Bootstrap.php
  53 |   |-- configs
  54 |   |   `-- application.ini
  55 |   |-- controllers
  56 |   |   |-- ErrorController.php
  57 |   |   `-- IndexController.php
  58 |   |-- models
  59 |   `-- views
  60 |       |-- helpers
  61 |       `-- scripts
  62 |           |-- error
  63 |           |   `-- error.phtml
  64 |           `-- index
  65 |               `-- index.phtml
  66 |-- library
  67 |-- public
  68 |   `-- index.php
  69 `-- tests
  70     |-- application
  71     |   `-- bootstrap.php
  72     |-- library
  73     |   `-- bootstrap.php
  74     `-- phpunit.xml
  75 ]]></programlisting>
  76
  77         <para>
  78             In the above diagram, your bootstrap is in
  79             <filename>newproject/application/Bootstrap.php</filename>, and looks like
  80             the following at first:
  81         </para>
  82
  83         <programlisting language="php"><![CDATA[
  84 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
  85 {
  86 }
  87 ]]></programlisting>
  88
  89         <para>
  90             You'll also note that a configuration file,
  91             <filename>newproject/application/configs/application.ini</filename>, is
  92             created. It has the following contents:
  93         </para>
  94
  95         <programlisting language="dosini"><![CDATA[
  96 [production]
  97 phpSettings.display_startup_errors = 0
  98 phpSettings.display_errors = 0
  99 includePaths.library = APPLICATION_PATH "/../library"
 100 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
 101 bootstrap.class = "Bootstrap"
 102 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
 103
 104 [staging : production]
 105
 106 [testing : production]
 107 phpSettings.display_startup_errors = 1
 108 phpSettings.display_errors = 1
 109
 110 [development : production]
 111 phpSettings.display_startup_errors = 1
 112 phpSettings.display_errors = 1
 113 ]]></programlisting>
 114
 115         <para>
 116             All settings in this configuration file are for use with
 117             <classname>Zend_Application</classname> and your bootstrap.
 118         </para>
 119
 120         <para>
 121             Another file of interest is the
 122             <filename>newproject/public/index.php</filename> file, which invokes
 123             <classname>Zend_Application</classname> and dispatches it.
 124         </para>
 125
 126         <programlisting language="php"><![CDATA[
 127 // Define path to application directory
 128 defined('APPLICATION_PATH')
 129     || define('APPLICATION_PATH',
 130               realpath(dirname(__FILE__) . '/../application'));
 131
 132 // Define application environment
 133 defined('APPLICATION_ENV')
 134     || define('APPLICATION_ENV',
 135               (getenv('APPLICATION_ENV') ? getenv('APPLICATION_ENV')
 136                                          : 'production'));
 137
 138 /** Zend_Application */
 139 require_once 'Zend/Application.php';
 140
 141 // Create application, bootstrap, and run
 142 $application = new Zend_Application(
 143     APPLICATION_ENV,
 144     APPLICATION_PATH . '/configs/application.ini'
 145 );
 146 $application->bootstrap()
 147             ->run();
 148 ]]></programlisting>
 149
 150         <para>
 151             To continue the quick start, please <link
 152             linkend="zend.application.quick-start.resources">skip to the
 153             Resources section</link>.
 154         </para>
 155     </sect2>
 156
 157     <sect2 id="zend.application.quick-start.manual">
 158         <title>Adding Zend_Application to your application</title>
 159
 160         <para>
 161             The basics of <classname>Zend_Application</classname> are fairly simple:
 162         </para>
 163
 164         <itemizedlist>
 165             <listitem>
 166                 <para>
 167                     Create an <filename>application/Bootstrap.php</filename> file, with the
 168                     class <classname>Bootstrap</classname>.
 169                 </para>
 170             </listitem>
 171
 172             <listitem>
 173                 <para>
 174                     Create an <filename>application/configs/application.ini</filename>
 175                     configuration file with the base configuration necessary for
 176                     <classname>Zend_Application</classname>.
 177                 </para>
 178             </listitem>
 179
 180             <listitem>
 181                 <para>
 182                     Modify your <filename>public/index.php</filename> to utilize
 183                     <classname>Zend_Application</classname>.
 184                 </para>
 185             </listitem>
 186         </itemizedlist>
 187
 188         <para>
 189             First, create your <classname>Bootstrap</classname> class. Create a file,
 190             <filename>application/Bootstrap.php</filename>, with the following contents:
 191         </para>
 192
 193         <programlisting language="php"><![CDATA[
 194 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 195 {
 196 }
 197 ]]></programlisting>
 198
 199         <para>
 200             Now, create your configuration. For this tutorial, we will use an
 201             <acronym>INI</acronym> style configuration; you may, of course, use an
 202             <acronym>XML</acronym> or <acronym>PHP</acronym> configuration file as well. Create
 203             the file <filename>application/configs/application.ini</filename>, and provide the
 204             following contents:
 205         </para>
 206
 207         <programlisting language="dosini"><![CDATA[
 208 [production]
 209 phpSettings.display_startup_errors = 0
 210 phpSettings.display_errors = 0
 211 includePaths.library = APPLICATION_PATH "/../library"
 212 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
 213 bootstrap.class = "Bootstrap"
 214 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
 215
 216 [staging : production]
 217
 218 [testing : production]
 219 phpSettings.display_startup_errors = 1
 220 phpSettings.display_errors = 1
 221
 222 [development : production]
 223 phpSettings.display_startup_errors = 1
 224 phpSettings.display_errors = 1
 225 ]]></programlisting>
 226
 227         <para>
 228             Now, let's modify your gateway script,
 229             <filename>public/index.php</filename>. If the file does not exist, create
 230             it; otherwise, replace it with the following contents:
 231         </para>
 232
 233         <programlisting language="php"><![CDATA[
 234 // Define path to application directory
 235 defined('APPLICATION_PATH')
 236     || define('APPLICATION_PATH',
 237               realpath(dirname(__FILE__) . '/../application'));
 238
 239 // Define application environment
 240 defined('APPLICATION_ENV')
 241     || define('APPLICATION_ENV',
 242               (getenv('APPLICATION_ENV') ? getenv('APPLICATION_ENV')
 243                                          : 'production'));
 244
 245 // Typically, you will also want to add your library/ directory
 246 // to the include_path, particularly if it contains your ZF installed
 247 set_include_path(implode(PATH_SEPARATOR, array(
 248     dirname(dirname(__FILE__)) . '/library',
 249     get_include_path(),
 250 )));
 251
 252 /** Zend_Application */
 253 require_once 'Zend/Application.php';
 254
 255 // Create application, bootstrap, and run
 256 $application = new Zend_Application(
 257     APPLICATION_ENV,
 258     APPLICATION_PATH . '/configs/application.ini'
 259 );
 260 $application->bootstrap()
 261             ->run();
 262 ]]></programlisting>
 263
 264         <para>
 265             You may note that the application environment constant value looks
 266             for an environment variable "APPLICATION_ENV". We recommend setting
 267             this in your web server environment. In Apache, you can set this
 268             either in your vhost definition, or in your <filename>.htaccess</filename>
 269             file. We recommend the following contents for your
 270             <filename>public/.htaccess</filename> file:
 271         </para>
 272
 273         <programlisting language="conf"><![CDATA[
 274 SetEnv APPLICATION_ENV development
 275
 276 RewriteEngine On
 277 RewriteCond %{REQUEST_FILENAME} -s [OR]
 278 RewriteCond %{REQUEST_FILENAME} -l [OR]
 279 RewriteCond %{REQUEST_FILENAME} -d
 280 RewriteRule ^.*$ - [NC,L]
 281 RewriteRule ^.*$ index.php [NC,L]
 282 ]]></programlisting>
 283
 284         <note>
 285             <title>Learn about mod_rewrite</title>
 286
 287             <para>
 288                 The above rewrite rules allow access to any file under your
 289                 virtual host's document root. If there are files you do not want
 290                 exposed in this way, you may want to be more restrictive in your
 291                 rules. Go to the Apache website to <ulink
 292                     url="http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html">learn
 293                 more about mod_rewrite</ulink>.
 294             </para>
 295         </note>
 296
 297         <para>
 298             At this point, you're all set to start taking advantage of
 299             <classname>Zend_Application</classname>.
 300         </para>
 301     </sect2>
 302
 303     <sect2 id="zend.application.quick-start.resources">
 304         <title>Adding and creating resources</title>
 305
 306         <para>
 307             If you followed the directions above, then your bootstrap class
 308             will be utilizing a front controller, and when it is run, it will
 309             dispatch the front controller. However, in all likelihood, you'll
 310             need a little more configuration than this.
 311         </para>
 312
 313         <para>
 314             In this section, we'll look at adding two resources to your
 315             application. First, we'll set up your layouts, and then we'll
 316             customize your view object.
 317         </para>
 318
 319         <para>
 320             One of the standard resources provided with
 321             <classname>Zend_Application</classname> is the "layout" resource. This
 322             resource expects you to define configuration values which it will
 323             then use to configure your <classname>Zend_Layout</classname> instance.
 324         </para>
 325
 326         <para>
 327             To use it, all we need to do is update the configuration file.
 328         </para>
 329
 330         <programlisting language="dosini"><![CDATA[
 331 [production]
 332 phpSettings.display_startup_errors = 0
 333 phpSettings.display_errors = 0
 334 bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
 335 bootstrap.class = "Bootstrap"
 336 resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
 337 ; ADD THE FOLLOWING LINES
 338 resources.layout.layout = "layout"
 339 resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"
 340
 341 [staging : production]
 342
 343 [testing : production]
 344 phpSettings.display_startup_errors = 1
 345 phpSettings.display_errors = 1
 346
 347 [development : production]
 348 phpSettings.display_startup_errors = 1
 349 phpSettings.display_errors = 1
 350 ]]></programlisting>
 351
 352         <para>
 353             If you haven't already, create the directory
 354             <filename>application/layouts/scripts/</filename>, and the file
 355             <filename>layout.phtml</filename> within that directory. A good starting
 356             layout is as follows (and ties in with the view resource covered
 357             next):
 358         </para>
 359
 360         <programlisting language="php"><![CDATA[
 361 <?php echo $this->doctype() ?>
 362 <html>
 363 <head>
 364     <?php echo $this->headTitle() ?>
 365     <?php echo $this->headLink() ?>
 366     <?php echo $this->headStyle() ?>
 367     <?php echo $this->headScript() ?>
 368 </head>
 369 <body>
 370     <?php echo $this->layout()->content ?>
 371 </body>
 372 </html>
 373 ]]></programlisting>
 374
 375         <para>
 376             At this point, you will now have a working layout.
 377         </para>
 378
 379         <para>
 380             Now, we'll add a custom view resource. When initializing the view,
 381             we'll want to set the <acronym>HTML</acronym> DocType and a default value for the title
 382             to use in the <acronym>HTML</acronym> head. This can be accomplished by editing your
 383             <classname>Bootstrap</classname> class to add a method:
 384         </para>
 385
 386         <programlisting language="php"><![CDATA[
 387 class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
 388 {
 389     protected function _initView()
 390     {
 391         // Initialize view
 392         $view = new Zend_View();
 393         $view->doctype('XHTML1_STRICT');
 394         $view->headTitle('My First Zend Framework Application');
 395
 396         // Add it to the ViewRenderer
 397         $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper(
 398             'ViewRenderer'
 399         );
 400         $viewRenderer->setView($view);
 401
 402         // Return it, so that it can be stored by the bootstrap
 403         return $view;
 404     }
 405 }
 406 ]]></programlisting>
 407
 408         <para>
 409             This method will be automatically executed when you bootstrap the
 410             application, and will ensure your view is initialized according to
 411             your application needs.
 412         </para>
 413     </sect2>
 414
 415     <sect2 id="zend.application.quick-start.next-steps">
 416         <title>Next steps with Zend_Application</title>
 417
 418         <para>
 419             The above should get you started with <classname>Zend_Application</classname>
 420             and creating your application bootstrap. From here, you should start
 421             creating resource methods, or, for maximum re-usability, resource
 422             plugin classes. Continue reading to learn more!
 423         </para>
 424     </sect2>
 425 </sect1>