Official ZF QuickStart

Under Construction

This QuickStart is currently under construction and community review. You may find the content helpful, but the examples may not work as described. We should have a final draft completed in the next few days. Please leave any feedback as a comment on this document.

Thanks, and happy ZF'in!

Zend Framework QuickStart

Co-authored by Aldemar Bernal & Bradley Holt

Zend Framework is an open source, object oriented, web application framework with a flexible architecture. ZF is often referred to as a 'component library' because it has many loosely coupled components that you can use more or less independently. However, Zend Framework also provides a core model-view-controller (MVC) implementation that you can use to provide basic 'best practices' structure to your web applications. This QuickStart will introduce you to the MVC pattern and Zend Framework's implementation of this pattern, along with the Zend_Controller, Zend_View, Zend_Layout, Zend_Form, and Zend_Db components.

Within minutes, we will have built a very simple blog application with a common page layout using these components. You will find the complete source code for this application in this archive.

MVC and Why You Should Care

So what exactly is this MVC pattern everyone keeps talking about, and why should you care? MVC is much more than just a three-letter acronym (TLA) that you can whip out anytime you want to sound smart; it has become something of a standard in the design of modern web applications- and for good reason. Let's take a look at what this pattern can do for your applications.
There are a few things the relatively young web development community has figured out over the years:

Mixing code with the complex markup required for today's pretty applications makes for an ungodly mess.
Most interface designers aren't very good at modeling backend business logic, and there is little evidence that the average backend developer is any better at creating decent user interfaces.
All non-trivial applications have a fundamental set of behaviors that define what the application should ultimately do for its users. These behaviors can usually be described independently of what is presented to the user.

For these reasons and many others, separating your code along the lines of separate roles in your organization or application responsibilities is a very good thing. And the model-view-controller pattern can help you do exactly this.
Let's break down the pattern and take a look at the individual pieces:

Model — This is the part of your application that defines its basic functionality behind a set of abstractions. The data access layer and some business logic is defined in the model.
View — Views define exactly what is presented to the user. Usually controllers pass data to each view to render in some format. This is where you'll find the html markup in your MVC applications.
Controller — Controllers bind the whole pattern together. They may manipulate models, decide which view to display based on the user's request and other factors, pass along the data that each view will need, or hand off control to another controller entirely.

Of course there is more to be said about this indispensable pattern, but this should give you enough background to understand the application we'll be building in this QuickStart.

Use-at-Will MVC

Zend Framework provides a very simple- yet powerful- MVC implementation which most ZF developers use in their applications. But, as is the case for all ZF components, our MVC components are use-at-will. You can still take advantage of ZF's database, forms, web services, etc. components without necessarily using its MVC implementation.

Building an Application

Application Structure on the File System

Let's first create this basic MVC project structure for our application under the directory QuickStart:

QuickStart/
   application/
      controllers/
      views/
         scripts/
   library/
   public/

Since the public directory will contain all files that are made directly accessible by our web server, you must set your web server's document root to this directory. Please check your web server's documentation on how to do this.

Just for argument's sake. . .
We will assume that your web server is running on your local machine and that your public directory is accessible via the web at http://localhost.

You can use the project structure that best suits your needs!

You will soon discover that Zend Framework is very flexible and its project file structure is no exception. There is nothing special about this particular project structure except some MVC components will work out of the box with no configuration if you structure your project this way. See the Zend Framework Reference Guide for more information.

Download and Install Zend Framework 1.5

Download Zend Framework 1.5 and extract the contents of the library folder to your project's library directory. Your library directory should now contain the top-level Zend directory which contains all of the Zend Framework components.
That's it! Zend Framework is now installed and ready to use.

Create a Rewrite Rule

Zend Framework's MVC implementation makes use of the Front Controller pattern. You must therefore rewrite all incoming requests (except those for static resources, which your application need not handle) to a single script that will initialize the FrontController and appropriately route the request. More about the FrontController and request routing later.
For the Apache web server, create the file QuickStart/public/.htaccess with the following content:

RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php

This rewrite rule will dispatch all requests for URLs that do not end in .js, .ico, .gif, .jpg, .png, or .css using index.php. This is because files with these extensions are static resources; requests for URL's that don't end with these extensions will be served dynamic content and must be handled by our PHP scripts. The index.php file therefore serves as the entry point to our application.

Make sure your web server is configured to read .htaccess files!

Some web servers may ignore .htaccess files unless otherwise configured. Make sure that your web server is configured to read the .htaccess file in the QuickStart/public directory.

Checkpoint

Let's just make sure everything is working so far. Create the file index.php and add the following contents:

<?php
echo 'Hello, Zend Framework!';

Now open your favorite browser and enter the URL http://localhost to see a simple page that says "Hello, Zend Framework!" If this does not work, check your web server logs and make sure you have rewrite enabled with the correct rewrite rules for your web server.

Create Index and Bootstrap Files

Let's take a quick look at that index.php file now. Replace the contents of QuickStart/public/index.php with the following:

<?php
require '../application/bootstrap.php';

The index.php script doesn't do much, but it is interesting in that it illustrates another best practice for Zend Framework applications. For security reasons, it is advisable to keep your application's scripts in a directory that your web server does not make publicly accessible. In this case, index.php immediately hands over control to the bootstrap.php file, which resides in the more secure QuickStart/application directory.

Best practices and closing tags. . .

We didn't forget the closing (?>) PHP tag! We intentionally omit it to avoid unintentional output of whitespace in the response in certain cases. In fact, this is one of the best practices recommended in the Zend Framework coding standards.

Now we need to create our bootstrap.php file, so called because it 'bootstraps' the application on each user request. Create the QuickStart/application/boootstrap.php file with the following contents:

<?php

/* Report all errors directly to the screen for simple diagnostics in the dev environment */ 
error_reporting(E_ALL | E_STRICT); 
ini_set('display_startup_errors', 1); 
ini_set('display_errors', 1);

/* Add the Zend Framework library to the include path so that we can access the ZF classes */
set_include_path('../library' . PATH_SEPARATOR . get_include_path()); 

/* Set up autoload so we don't have to explicitely require each Zend Framework class */
require_once "Zend/Loader.php";
Zend_Loader::registerAutoload();

/* Set the singleton instance of the front controller */
$frontController = Zend_Controller_Front::getInstance();
/* Disable error handler so it doesn't intercept all those errors we enabled above */
$frontController->throwExceptions(true);
/* Point the front controller to your action controller directory */
$frontController->setControllerDirectory('../application/controllers');
/* OK, do your stuff, front controller */
$frontController->dispatch();

At this point you should start to see your application taking shape. Let's take a look at the steps we take in the bootstrap script one by one:

Enable all errors so we can see when something goes wrong.
Add our QuickStart/library/ directory to the include path so the Zend Framework classes are accessible to the PHP runtime.
Register the autoloader. This is a nifty trick that allows ZF to load classes automatically so that you don't have to litter your code with 'include' or 'require' statements.
Get the front controller. The Zend_Front_Controller class implements the Singleton pattern, which is just a best practice for ensuring there is only one instance of Zend_Front_Controller created for each request.
Error handlers allow you to display whatever message you want in whichever format you want if an error is detected in your application. This is very useful in production applications, but for our purposes it is not necessary and will obscure the root cause of the error. Since the error handler is enabled by default, we should disable it.
Point the front controller to the action controller directory.
Dispatch the request using the front controller.

The action controllers under the directory mentioned in step 6 comprise the part of your application that will process the user request next. Action controllers, also called page controllers, represent the 'controller' part of the model-view-controller pattern. There is obviously a lot that the happens after the dispatch() method takes over and before it hands over controller to your action controller, but you don't necessarily need to know the details to write feature-full applications. See the Reference Guide for more information. For now let's move on to creating the action controllers themselves.

Relative Paths

Remember that the QuickStart/public/index.php script is the first script to which all requests are rewritten, so we must build our relative paths with respect to this file. That's how we came up with the '../library' and '../application/controllers' paths above.

Create an Action Controller

In the Zend Framework MVC implementation, the default action controller is index and the default action is also index. You should therefore set up the default action controller by creating QuickStart/application/controllers/IndexController.php with the following content:

<?php
/** @see Zend_Controller_Action */
require_once 'Zend/Controller/Action.php';

class IndexController extends Zend_Controller_Action
{
    public function indexAction()
    {
    }
}

Because we're using the default request router, requests for http://localhost will be routed to the indexAction method on the IndexController action controller, as will requests to http://localhost/index and http://localhost/index/index.

Controller and Action Name Conventions

With the default configuration, the action method names should use the lowerCamelCase convention with the suffix 'Action'. Action controller classes, on the other hand, should use the UpperCamelCase convention with the suffix 'Controller'.

It may seem like indexAction() is doing nothing at all, but again Zend Framework is doing useful things behind the scenes. In this case it is routing the request to the appropriate view to return the correct response. Unless otherwise configured, the view it will look for is views/scripts/index/index.phtml, where the views directory is contained in the same folder as the controllers directory you passed to Zend_Controller_Front::run(). The extension for views is yet another best practice recommended for Zend Framework applications; since view templates in ZF are simply PHP files by default, it is easier to distinguish view templates from other PHP files if you use the .phtml extension instead of .php.

Checkpoint

Let's create this view now with the following content:

<!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 align="center"><?php echo 'Hello, Zend Framework MVC!' ?></h1> 
</body> 
</html>

Now go to http://localhost; you should see 'Hello, Zend Framework MVC!' with very basic formatting.
If you do not see this message, check your server logs and make sure you've created the specified files with the exact content from above.

Template Engines

Although ZF has its own template engine that renders templates which are very similar to standard PHP, you can easily configure Zend Framework to use other template engines, such as Smarty or PHPTAL. See the reference guide for more information.

Build a Form

Admittedly, our application at this point isn't very interesting. Adding some interactive content would certainly help, so let's start rendering and process basic HTML forms using Zend_Form. Replace the contents of the IndexController.php file with the following:

/** @see Zend_Controller_Action */
require_once 'Zend/Controller/Action.php';

class IndexController extends Zend_Controller_Action
{
    public function indexAction()
    {
    }

    /**
     * This function returns the form used for
     * adding comments in blog application
     */
    public function getCommentForm()
    {
        $form = new Zend_Form(array(
            'method'   => 'post',
            'elements' => array(
                'comments' => array('textarea', array(
                    'required' => true,
                    'label' => 'Write your comments'
                )),
                'submit' => array('submit', array(
                    'label' => 'Add Comment'
                ))
            ),
        ));

        return $form;
    }
}

Since this form has been built using the Zend_Form component, even the trickiest parts of form handling should be easy to implement. Validation, filtering, rendering, displaying errors, and a lot more form-related functionality are made available by Zend_Form using its simple and intuitive API. By looking through the getCommentForm() method, you should notice that there is a required text area for the comment and a button to submit that comment in the form that is returned. Let's display this form in our index view to see how it appears when it is rendered. Replace the indexAction() method in your IndexController.php file with the following:

public function indexAction()
{
    $form = $this->getCommentForm();

    if ($this->getRequest()->isPost()) { 
        if ($form->isValid($_POST)) { 
            $values = $form->getValues(); 
            $this->view->values = $values;
        } 
    } 
 
    $this->view->form = $form;
}

A few things are happening here. First, we create the form to use in the rest of the method. Next, we check whether the user is submitting the form data- in which case we would expect an HTTP POST request- or viewing a page with a blank form- in which case we would expect an HTTP GET request. If the user is submitting data, we pass this data in the $_POST variable to the form for validation. If all goes well during validation, we get the filtered values from the form (in this case no filters have been set). We can pass these values to the view by setting the $values on the view object.
Now you must alter your view so that it knows what to do with the form and any values that are passed to it. Replace the contents of the scripts/index/index.phtml file with the following:

<!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>Basic Blog</h1>
    <?php if($this->values) { ?>
    <h3>You just submitted the following values:</h3>
    <ul>
      <?php foreach ($this->values as $value) :?>
      <li>
        <?= $this->escape($value); ?>
      </li>
      <?php endforeach; ?>
    </ul>
    <?= $this->form; ?> 
  </body> 
</html>

Now your view is checking if there are any values to display and, if so, listing them. Regardless of whether there are values to display or not, the form is rendered near the end of the view. Now, when you go to http://localhost you should see something like this:

And if you enter a comment and hit the Send button, you should now see something like this:

Escape user generated data before outputting it!

Note that before we output comments to the response, we first escape them like so: $this->escape($value);. If we didn't escape this output, malicious or simply uninformed users could do all kinds of nasty things that might affect the appearance or behavior of this page. In particular, scripts could be invoked that might compromise the security of your application. Always escape data that has been entered or edited by a user before adding it to the response!

My sincere apologies. I have not been able to get back to the QuickStart since the 1.5 release. All the things we put off until after the release have been catching up with me.

I will finish this QuickStart as soon as I can. Thanks for your patience!

Conclusion

You have now built a very simple application using some of the most commonly used Zend Framework components. Zend Framework makes many more components available to you for you applications, including web services, search, PDF reading and writing, authentication, authorization, and much more. You'll find that there are components that address most requirements you are likely to encounter when building a web application. The Reference Guide is a great place to find out more about the components you've used in this QuickStart as well as all of the other Zend Framework components. We hope you find Zend Framework useful and- more importantly- fun!

Page Operations

Browse Space