Official ZF QuickStart

Zend Framework QuickStart

Co-authored by Aldemar Bernal, Bradley Holt, & Wil Sinclair

Zend Framework is an open source, object oriented web application framework for PHP 5. ZF is often called a 'component library' because it has many loosely coupled components that you can use more or less independently, but it also provides an advanced model-view-controller (MVC) implementation that can provide the basic structure for ZF applications. A full list of Zend Framework components along with short descriptions may be found here . This QuickStart will introduce you to some of ZF's most commonly used components: Zend_Controller, Zend_View, Zend_Layout, Zend_Form, and Zend_Db.

Using these components, we will build a simple database-driven blog application within minutes. The complete source code for this application is available in the following archives:

zip | tar.gz

MVC

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. Most web application code falls under one of the following three categories: presentation, business logic, and data access. The MVC pattern models this separation of concerns well. The end result is that your presentation code can be consolidated in one part of the application with your business logic in another and your data access code in yet another. Many developers have found this well-defined separation indispensable for keeping their code organized- especially when more than one developer is working on the same application. More Info. . .

Use-at-Will MVC

Zend Framework provides a very simple, yet powerful, MVC implementation around which most ZF developers organize their applications. But- as is the case for all ZF components- our MVC components can be used at will. This means you can still take advantage of ZF's database, forms, web services- even view- components without necessarily consuming all of its MVC components.

Building an Application

Project Structure

Let's first create a 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 should be directly accessible via 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.

We will assume that your web server is running on your local machine and that your public directory is accessible 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 the project structure for ZF applications is no exception. There is nothing special about the project structure above, except some of the MVC components we'll be using work without overriding defaults in this structure. See the Zend Framework Reference Guide for more information.

Download and Install Zend Framework

Download the latest version of Zend Framework and extract the contents of the library folder to your project's library directory. You should now find the top-level Zend directory which contains all Zend Framework components under your library directory.
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 route the request.
If you're using mod_rewrite for the Apache web server, create the file QuickStart/public/.htaccess with the following contents:

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

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

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

Checkpoint

Let's 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.

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.

Create a Bootstrap File

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

<?php
// Step 1: Set a flag indicating setup is necessary
$bootstrap = true;

// Step 2: Setup PHP environment
// In this case, we will setup error reporting, but any ini_set or
// environment-related directives should go here. This way, you can create a
// separate PHP environment for running tests.
error_reporting(E_ALL | E_STRICT); 
ini_set('display_startup_errors', 1); 
ini_set('display_errors', 1);

// Step 3: Perform application-specific setup
// This allows you to setup the MVC environment to utilize. Later you can re-use this file for testing your applications
require '../application/bootstrap.php'; 

// Step 4:  Dispatch the request using the front controller.
// The front controller is a singleton, and should be setup by now. We will grab
// an instance and dispatch it, which dispatches your application.
Zend_Controller_Front::getInstance()->dispatch();

This 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 quickly hands over control to the bootstrap.php file, which resides in the more secure application directory.

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

<?php
// Step 1: Check to see if the applicaiton environment is already setup
if (isset($bootstrap) && $bootstrap) {
    // Step 1a: Add our {{library}} directory to the include path so that PHP can find the Zend Framework classes.
    set_include_path('../library' . PATH_SEPARATOR . get_include_path()); 

    // Step 1b: Set up autoload.
    // 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.
    require_once "Zend/Loader.php";
    Zend_Loader::registerAutoload();
}

// Step 2: Get the front controller.
// The Zend_Front_Controller class implements the Singleton pattern, which is a
// design pattern used to ensure there is only one instance of
// Zend_Front_Controller created on each request.
$frontController = Zend_Controller_Front::getInstance();

// Step 3: Point the front controller to your action controller directory.
$frontController->setControllerDirectory('../application/controllers');

// Step 4: Set the current environment
// Set a variable in the front controller indicating the current environment --
// commonly one of development, staging, testing, production, but wholly
// dependent on your organization and site's needs.
$frontController->setParam('env', 'development');

At this point you should start to see your application taking shape. The bootstrap.php script sets up the application environment. This script typically should not contain business logic for your application, however.

You may ask why the call to dispatch() is made outside the bootstrap.php file. The rationale is for later down the line when you start functional testing your applications; with the above strategy, you can re-use your bootstrap.php script to setup your application environment when testing. This topic will be covered in a later tutorial.

The action controllers under the directory mentioned in step 3 of bootstrap.php above 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 control to your action controller, but you don't necessarily need to know the details to write full featured applications. See the Reference Guide for details on how requests are dispatched. For now let's move on to creating the action controllers themselves.

Relative Paths

Remember that QuickStart/public/index.php 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 Zend Framework's MVC implementation, both the default action controller and the default action are named 'index'. You should therefore set up the default action controller by creating QuickStart/application/controllers/IndexController.php with the following contents:

<?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 standard 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

To work correctly with the standard router, action method names should follow the lowerCamelCase convention with the suffix 'Action'. Action controller classes, on the other hand, should follow the UpperCamelCase convention with the suffix 'Controller'. While the standard router should work for almost all applications, routing in Zend Framework is completely customizable. See the Reference Guide for details.

It may seem like indexAction() is doing nothing at all, but again Zend Framework is doing useful things for you 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 file extension for views is yet another best practice recommended for Zend Framework applications; since view templates look suspiciously like PHP scripts in ZF, it is easier to distinguish view templates from other PHP files if you use the .phtml extension instead of .php.

Checkpoint

Let's create the view script now with the following contents:

<!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 contents from above.

Template Engines

Although ZF has its own template engine that renders templates 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 details.

Create an Error Controller

The last things you want to display to an end-user of your site are either a blank page or exceptions. Zend Framework's MVC recognizes this, and provides an ErrorHandler plugin that will detect exceptions and dispatch an ErrorController so that you can display alternate content.

Additionally, you need some way to handle 404 situations – i.e., situations when the action or controller are not found.

In development, you do want to see exceptions. Fortunately, we can accomodate both.

The ErrorHandler plugin by default will dispatch the errorAction() of the ErrorController. Let's build our controller.

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

class ErrorController extends Zend_Controller_Action
{
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:

                // 404 error -- controller or action not found
                $this->getResponse()->setHttpResponseCode(404);
                $this->view->message = 'Page not found';
                break;
            default:
                // application error
                $this->getResponse()->setHttpResponseCode(500);
                $this->view->message = 'Application error';
                break;
        }

        $this->view->env       = $this->getInvokeArg('env');
        $this->view->exception = $errors->exception;
        $this->view->request   = $errors->request;
    }
}

The above may seem a bit esoteric. First, the ErrorHandler plugin stores error information, including the error type, exception caught, and the request that produced it, within a token that is passed in the request. We grab that first.

Second, we do some switching based on the exception type. There are two types of exceptions that represent 404 situations – controller not found and action not found. For these, we change the HTTP response code to 404 to indicate this. All other exceptions are considered application exceptions, and we'll return the appropriate HTTP response code for these – 500.

Third, remember the env variable we pushed into the front controller in the bootstrap file? We're going to pull that and push it into the view. More on this later.

Finally, we pass some information to the view – the exception and request.

Let's look at the related view script, which we'll place in views/scripts/error/error.phtml.

<!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>An error occurred</h1>
  <h2><?= $this->message ?></h2>

  <? if ('development' == $this->env): ?>
  <h3>Exception information:</h3>
  <p>
      <b>Message:</b> <?= $this->exception->getMessage() ?>
  </p>

  <h3>Stack trace:</h3>
  <pre>
  <?= $this->exception->getTraceAsString() ?>
  </pre>

  <h3>Request Parameters:</h3>
  <pre>
  <?= $this->request->getParams() ?>
  </pre>
  <? endif ?>
</body>
</html>

Note the use of the env flag. We're now using it in the view script to determine whether or not to display exception information. In development, you'll get full information; changing the value in your bootstrap.php file will then disable this sensitive information from being displayed, while still providing a reasonable error message to your end users.

You can take a look at what it does by going to a bogus URL in your application. Try one of the following: /bogus or /index/bogus.

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 processing basic HTML forms using Zend_Form. Replace the contents of the IndexController.php file with the following:

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

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

    /**
     * This function returns a simple form for adding a comment
     */ 
    protected function _getCommentForm() 
    { 
        $form = new Zend_Form(array( 
            'method'   => 'post', 
            'elements' => array( 
                'comment' => array('textarea', array( 
                    'required' => true, 
                    'label' => 'Please Comment:' 
                )), 
                'submit' => array('submit', array( 

                    'label' => 'Add Comment' 
                )) 
            ), 
        )); 
 
        return $form; 
    }
}

Since this form has been built using the Zend_Form component, form handling should be a cinch. Validation, filtering, rendering, displaying errors, and a lot more form-related functionality are dramatically simplified with Zend_Form. By looking closely at the _getCommentForm() method above, you should notice that it returns a form with a required text area for the comment and a button to submit that comment. Let's display this form in our index controller through a new action called 'contact' and view to see how it looks after rendering. Create a new action method in the index controller IndexController.php called commentAction() method in your file with the following:

public function commentAction() 
    {
        $form = $this->_getCommentForm(); 
 
        if ($this->getRequest()->isPost()) {  
            if ($form->isValid($_POST)) {  
                $comment = $form->getValue('comment');  
                $this->view->comment = $comment; 
            }  
        }
      
        $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 loading a blank form- in which case we would expect an HTTP GET request. If the user is submitting a comment, 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.
You must now 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(isset($this->comment)): ?> 
        <p>
            You just submitted the following comment:
            <?= $this->escape($this->comment); ?>
        </p>
     <?php endif; ?>
     <?= $this->form; ?>
  </body>  
</html>

Now your view is checking if there are any values to display and, if so, listing them. Regardless of whether values are displayed or not, the form is rendered near the end of the view.

Always keep security in mind!

To build secure applications, you must always keep an eye out for vulnerabilities in your code and apply security best practices where appropriate.
For example, in this view we escape user input like so: $this->escape($value);. Neglecting to escape user input before outputting it could create a big vulnerability in your application. Malicious or uninformed users could affect the appearance or behavior of your application's pages. In particular, the user input might invoke scripts that could compromise the security of your application. Always escaping user input before adding it to a response is an important security best practice.

Now, when you go to http://localhost/index/comment you should see something like this:

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

And if you do not enter a comment and hit the 'Add Comment' button, you'll see something like this:

This last example should give you a taste of the power that Zend_Form can bring to your applications. Simply by setting the 'required' attribute on your 'comment' form element to true, you have built a validated form that will display an error if the comment text area is empty. The error message itself can be specified during form creation.

Better Looking Forms

No one will be waxing poetic about the beauty of this form anytime soon. No matter- form appearance is fully customizable! See the decorators section in the reference guide for details.

Access a Database

Under Construction!

Congratulations!

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 and your 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 while 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 other Zend Framework components. We hope you find Zend Framework useful and- more importantly- fun!

Page Operations

Browse Space