<ac:macro ac:name="info"><ac:default-parameter>Not exactly "Completed"</ac:default-parameter><ac:rich-text-body>
<p>This Quick Start is not exactly "completed" but it is as close as I was able to get it by the deadline. I hope it has some material that is useful in creating the final Quick Start.</p></ac:rich-text-body></ac:macro>
<h1>Zend Framework QuickStart</h1>
<h2>Introduction</h2>
<p>Zend Framework is a "leading open-source PHP framework that has a flexible architecture that lets you easily build modern web applications and web services." Zend Framework is often referred to as a "glue" framework because it has many components that can be used to help build your web application. However, Zend Framework also provides an MVC "stack" that you may choose to use. This quick start guide assumes you are using Zend Framework MVC and will also cover the Zend_Controller, Zend_View, Zend_Layout, Zend_Form, and Zend_Db components.</p>
<h2>Quick Start</h2>
<h3>Create the file system structure</h3>
<p>For this quick start we will use <code>QuickStart</code> as our top-level project directory. Create the basic file system structure:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
QuickStart/
application/
controllers/
views/
scripts/
library/
public/
css/
images/
js/
]]></ac:plain-text-body></ac:macro>
<p>Note that this file system structure is based on the <a href="http://framework.zend.com/wiki/x/6KM">default project structure proposal</a>. The file system structure above only includes the directories we will use for the rest of this Quick Start section. In the Next Steps section we will be adding additional directories as needed. One of the things you will discover about Zend Framework is that it is very flexible and extensible. There is nothing special about this particular file system structure other than the fact that it is considered a Zend Framework best practice and that various Zend Framework components will assume this structure unless otherwise configured.</p>
<h3>Install Zend Framework</h3>
<p>Install Zend Framework to the <code>library</code> directory. Your <code>library</code> directory should now contain the top-level <code>Zend</code> directory which contains all of the Zend Framework components. You may also want to install other vendor libraries in the <code>library</code> directory and/or your own library that you re-use from project to project. For more information on installing Zend Framework see the <a href="http://framework.zend.com/manual/en/introduction.installation.html">Installation</a> section of the Reference Guide.</p>
<h3>Set your document root</h3>
<p>In your web server configuration, set your document root to <code>QuickStart/public/</code>. For this quick start we will assume this is the document root for <code><a class="external-link" href="http://www.example.com">http://www.example.com</a></code>. You may have noticed that in the file system structure we talked about earlier we created <code>css</code>, <code>js</code>, and <code>images</code> directories. These are there simply to organize your static website files and it is up to you if you need them or not.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Note</ac:parameter><ac:rich-text-body>
<p>Talk more about, or provide links to resources about, configuring document root.</p></ac:rich-text-body></ac:macro>
<h3>Create your rewrite rules</h3>
<p>Zend Framework MVC uses the Front Controller pattern. This means we need to rewrite all incoming requests (except those for static resources) to a single PHP script which will then appropriately route the request. Assuming you are using the Apache web server, create the file <code>QuickStart/public/.htaccess</code> with the following content:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php
]]></ac:plain-text-body></ac:macro>
<p>This rewrite rule will rewrite all requests for files that do <em>not</em> end in <code>.js</code>, <code>.ico</code>, <code>.gif</code>, <code>.jpg</code>, <code>.png</code>, or <code>.css</code> to <code>index.php</code>.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Notes</ac:parameter><ac:rich-text-body>
<ul>
<li>Provide more information about how the Front Controller pattern works in Zend Framework.</li>
<li>Talk about alternatives for non-Apache web servers.</li>
</ul>
</ac:rich-text-body></ac:macro>
<h3>Create your index and bootstrap files</h3>
<p>Create the file <code>QuickStart/public/index.php</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php
require '../application/bootstrap.php';
]]></ac:plain-text-body></ac:macro>
<p>Note that we have left out the closing <code>?></code> PHP tag. This is intentional and is a good practice to avoid accidental output of whitespace. Now we need to create our bootstrap file, <code>QuickStart/application/boootstrap.php</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php
set_include_path(get_include_path() . PATH_SEPARATOR . '../library');
/** @see Zend_Controller_Front */
require_once 'Zend/Controller/Front.php';
Zend_Controller_Front::run('../application/controllers');
]]></ac:plain-text-body></ac:macro>
<p>The bootsrap file does exactly what it says, bootstraps your web application. First we add our <code>QuickStart/library/</code> directory to the include path. Next we run Zend_Controller telling it where to find our action controllers. Remember that <code>QuickStart/public/index.php</code> is the main script that is running so relative paths are relative to it, thus the <code>'../library'</code> and <code>'../application/controllers'</code> paths above.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Note</ac:parameter><ac:rich-text-body>
<p>Provide more information about action controllers.</p></ac:rich-text-body></ac:macro>
<h3>Create your index controller</h3>
<p>In Zend Framework MVC the default action controller is <code>index</code> and the default action is <code>index</code>. Create <code>QuickStart/application/controllers/IndexController.php</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php
/** @see Zend_Controller_Action */
require_once 'Zend/Controller/Action.php';
class IndexController extends Zend_Controller_Action
{
public function indexAction()
{
}
}
]]></ac:plain-text-body></ac:macro>
<p>Requests for <code><a class="external-link" href="http://www.example.com">http://www.example.com</a></code> will be routed to <code>indexAction</code> in this action controller. Requests to <code><a class="external-link" href="http://www.example.com/index">http://www.example.com/index</a></code> and <code><a class="external-link" href="http://www.example.com/index/index">http://www.example.com/index/index</a></code> will also be routed to the same place. Note the camel case naming convention and that action controller names should end with <code>Controller</code> and action names should end with <code>Action</code>. Later we may want to add some functionality to <code>indexAction</code> but for now we will leave it empty.</p>
<h3>Create your index view script</h3>
<p>By default Zend Framework uses PHP for templating view scripts but it is possible to use other templating engines. It is recommended you use the <code>.phtml</code> extension so that you can distinguish view scripts from other PHP files. Zend Framework looks in <code>QuickStart/application/views/scripts/</code> for a directory by the same name as the action controller and then within that directory for a file by the same name as the action with a <code>.phtml</code> extension. This behavior, like most everything in Zend Framework, is completely configurable. Since we want to create a view script for the index action within the index action controller we need to create the <code>QuickStart/application/views/scripts/index/</code> directory (matching the name of the action controller) and then the <code>QuickStart/application/views/scripts/index/index.phtml</code> file (matching the name of the action) with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Zend Framework Quick Start</title>
</head>
<body>
<h1>Zend Framework Quick Start</h1>
<p>Hello, World!</p>
</body>
</html>
]]></ac:plain-text-body></ac:macro>
<p>Note that we have to repeat all of the HTML in each of our view scripts. This is not optimal and we will talk about a solution to this using Zend_Layout in the Next Steps section.</p>
<h3>Create your error controller</h3>
<p>The default behavior of Zend Framework is to look for an ErrorController with an errorAction to handle application errors. Create <code>QuickStart/application/controllers/ErrorController.php</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php
/** @see Zend_Controller_Action */
require_once 'Zend/Controller/Action.php';
class ErrorController extends Zend_Controller_Action
{
public function errorAction()
{
}
}
]]></ac:plain-text-body></ac:macro>
<h3>Create your error view script</h3>
<p>Create the directory <code>QuickStart/application/views/scripts/error/</code> and then the file <code>QuickStart/application/views/scripts/error/error.phtml</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Error</title>
</head>
<body>
<h1>Error</h1>
<p>An error has occurred.</p>
</body>
</html>
]]></ac:plain-text-body></ac:macro>
<h3>Summary</h3>
<p>You should now have the following file system structure:</p>
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
QuickStart/
application/
controllers/
ErrorController.php
IndexController.php
views/
scripts/
error/
error.phtml
index/
index.phtml
bootstrap.php
library/
Zend/
<Zend Framework components>
public/
css/
images/
js/
.htaccess
index.php
]]></ac:plain-text-body></ac:macro>
<p>Visiting any of the following URLs will execute <code>IndexController::indexAction()</code> and display the contents of the <code>index/index.phtml</code> view script:</p>
<ul>
<li><a class="external-link" href="http://www.example.com">http://www.example.com</a></li>
<li><a class="external-link" href="http://www.example.com/index">http://www.example.com/index</a></li>
<li><a class="external-link" href="http://www.example.com/index/index">http://www.example.com/index/index</a></li>
</ul>
<p>If you visit a URL that does not have a controller and action mapped to it (any other URL at this point) will execute <code>ErrorController::errorAction()</code> and display the contents of the <code>error/error.phtml</code> view script.</p>
<p>Download <a href="http://burlington-vt-php-example.googlecode.com/files/QuickStart.zip">QuickStart.zip</a>. This file includes all of the code created up to this point but does not include Zend Framework itself.</p>
<h2>Next Steps</h2>
<h3>Using layouts</h3>
<p>Zend_Layout gives us an implementation of the Two Step View pattern. Practically speaking, this allows us to create one site template, or layout, that all of our pages will use. This can give us a consistent look-and-feel between pages as well as allow us to follow the DRY (Don't Repeat Yourself) design principle. See the <a href="http://framework.zend.com/manual/en/zend.layout.quickstart.html">Zend_Layout Quick Start</a> for more advanced usage.</p>
<h4>Create your layout view script</h4>
<p>Create the directory <code>QuickStart/application/layouts/</code> and the file <code>QuickStart/application/layouts/layout.phtml</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Zend Framework Quick Start</title>
</head>
<body>
<?= $this->layout()->content ?>
</body>
</html>
]]></ac:plain-text-body></ac:macro>
<p>This will serve as our main website template. The PHP code <code>$this->layout()->content</code> is using the layout view helper to output the value of the <code>content</code> variable. Zend_Layout automatically assigns the value of the <code>default</code> segment to the <code>content</code> variable.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Notes</ac:parameter><ac:rich-text-body>
<ul>
<li>Explain what view helpers are.</li>
<li>Explain named segments.</li>
</ul>
</ac:rich-text-body></ac:macro>
<h4>Modify index and error view script</h4>
<p>Since we will be using <code>QuickStart/application/layouts/layout.phtml</code> as our website template we need to strip out all but the actual content from our index and error view scripts. Modify <code>QuickStart/application/views/scripts/index/index.phtml</code>, stripping out all but the actual content so it looks like this:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<h1>Zend Framework Quick Start</h1>
<p>Hello, World!</p>
]]></ac:plain-text-body></ac:macro>
<p>Modify <code>QuickStart/application/views/scripts/error/error.phtml</code>, stripping out all but the actual content so it looks like this:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<h1>Error</h1>
<p>An error has occurred.</p>
]]></ac:plain-text-body></ac:macro>
<h4>Modify bootstrap file</h4>
<p>Now we need to modify our bootstrap file to start Zend_Layout MVC. Update <code>QuickStart/application/bootstrap.php</code>:</p>
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php
set_include_path(get_include_path() . PATH_SEPARATOR . '../library');
/** @see Zend_Controller_Front */
require_once 'Zend/Controller/Front.php';
/** @see Zend_Layout */
require_once 'Zend/Layout.php';
Zend_Layout::startMvc(array('layoutPath' => '../application/layouts'));
Zend_Controller_Front::run('../application/controllers');
]]></ac:plain-text-body></ac:macro>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Note</ac:parameter><ac:rich-text-body>
<p>By default Zend_Layout looks in <code>QuickStart/application/views/scripts/</code> for layouts. The default project structure proposal puts layouts in <code>QuickStart/application/layouts/</code>. For this reason, we need to pass the <code>layoutPath</code> configuration parameter to <code>Zend_Layout::startMvc()</code>. This conflict between the default project structure proposal and Zend_Layout should be resolved and this quick start updated.</p></ac:rich-text-body></ac:macro>
<h4>Create a header and footer</h4>
<p>Lets create two more layout view scripts. First create the file <code>QuickStart/application/layouts/header.phtml</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<ul>
<li><a href="/">Home</a></li>
</ul>
]]></ac:plain-text-body></ac:macro>
<p>This will act as our navigation bar giving us one file to update when we add new items. Now create the file <code>QuickStart/application/layouts/footer.phtml</code> with the following content:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<div>
<a href="http://framework.zend.com/">
<img src="/images/PoweredBy_ZF_4LightBG.png" alt="Powered By Zend Framework" />
</a>
</div>
]]></ac:plain-text-body></ac:macro>
<p>Grab a copy of the <a href="http://framework.zend.com/community/logo">Powered By Zend Framework Logo</a> and put it in <code>QuickStart/public/images/</code>. Update <code>QuickStart/layouts/layout.phtml</code>:</p>
<ac:macro ac:name="code"><ac:default-parameter>html</ac:default-parameter><ac:plain-text-body><![CDATA[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Zend Framework Quick Start</title>
</head>
<body>
<?= $this->render('header.phtml') ?>
<?= $this->layout()->content ?>
<?= $this->render('footer.phtml') ?>
</body>
</html>
]]></ac:plain-text-body></ac:macro>
<p>Download <a href="http://burlington-vt-php-example.googlecode.com/files/QuickStartLayout.zip">QuickStartLayout.zip</a>. This file includes all of the code created up to this point but does not include Zend Framework itself.</p>
<h3>Using Zend_Form</h3>
<p>See the <a href="http://framework.zend.com/manual/en/zend.form.quickstart.html">Zend_Form Quick Start</a>.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Note</ac:parameter><ac:rich-text-body>
<p>This should be filled in with an example of using Zend_Form within a Zend Framework MVC application.</p></ac:rich-text-body></ac:macro>
<h3>Using Zend_Db</h3>
<p>See <a href="http://framework.zend.com/manual/en/zend.db.html">Zend_Db</a>.</p>
<ac:macro ac:name="info"><ac:parameter ac:name="title">Note</ac:parameter><ac:rich-text-body>
<p>This should be filled in with an example of using Zend_Db_Table, Zend_Db_Table_Row, and Zend_Db_Table_Rowset within a Zend Framework MVC application.</p></ac:rich-text-body></ac:macro>