The Zend_Controller system was built with extensibility in mind, either by subclassing the existing classes or writing new classes that implement the various interfaces and abstract classes that form the foundation of the controller family of classes.

Zend_Controller is built to support modern websites with clean URIs (few or no query parameters). As such, the suggested configuration requires support from the webserver in the form of URI rewriting to redirect all requests to a single file, here called "index.php", which will simply bootstrap Zend_Controller_Front. On Apache webservers, this is handled by an optional module called mod_rewrite.

The first step in configuring the server is to sucessfully install and enable mod_rewrite. The next step is to put two files in the document root: .htaccess and index.php. The .htaccess file is used by Apache and must contain a mod_rewrite rule to redirect all requests to index.php. For development purposes, it is often simplest to write a mod_rewrite rule that will redirect all requests to index.php except for certain file extensions. Here is an example of such a file:

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

In the example above, all requests not containing one of the above file extensions will be passed to index.php. This is useful for development, however in production the rewrite rules should be written to exclude directories instead.

That said, the basic functionality of Zend_Controller also supports URLs using query parameters -- as an example, index.php?controller=foo&action=bar. Additionally, another shipped router, Zend_Controller_RewriteRouter, works in a variety of environments, including many without mod_rewrite-like capabilities. If you cannot use mod_rewrite or an equivalent, you'll still be able to use Zend_Controller for your site.

After setting up the .htaccess file, create a new file called index.php. This is a bootstrap file. The purpose of the index.php file is only to bootstrap Zend_Controller_Front, which should ideally be located outside of the document root.

For security purposes, Zend very strongly recommends not storing any PHP files in directories that are accessible by the webserver (those that are beneath the document root). While this is not possible in every scenario, such as shared hosting, this should be considered a best practice and observed whenever possible.

Create the bootstrap file, index.php, in the document root to bootstrap Zend_Controller_Front:

<?php

require_once 'Zend/Controller/Front.php';

Zend_Controller_Front::run('/path/to/your/controllers');

?>

See the next section regarding the /path/to/your/controllers. As instructed in README.txt, the directory of the Zend Framework library must be in the include_path. If this is not set in php.ini, set_include_path() can be called in this file before the require_once().

It is recommended that websites built with the Zend Framework share a common directory structure. While this is not possible in every case, it is for many or perhaps most. Choosing to conform to this structure will make your code more easily understandable by someone familiar with the conventions of the Zend Framework.

The suggested directory structure consists of both library directories (from Zend and elsewhere) and application directories.

/application
  /models
  /views
  /controllers
/document_root
  /images
  /styles
  .htaccess
  index.php
/library
  /Zend

Every site must define a default controller. This is the controller that is reached when no controller is specified in the URI, such as in this URI:

http://framework.zend.com/

In the shipped configuration, the default controller should be named IndexController, and defined in a file named IndexController.php. Internally, it will be referenced as the controller 'index'.

You may change the default controller prior to dispatching the front controller by calling the setDefaultController() method on either the front controller or dispatcher object. When doing so, use the internal naming conventions. Thus, the class HomeController (in the HomeController.php file) would be referred to as home.

Controllers should extend the Zend_Controller_Action class and be placed in the controllers directory.

<?php

require_once 'Zend/Controller/Action.php';

class IndexController extends Zend_Controller_Action
{
    public function indexAction()
    {
        echo 'Hello from IndexController';
    }

    public function noRouteAction()
    {
        $this->_redirect('/');
    }
}

?>

More detail on the default controller and action, as well as writing action controller classes, will be presented in later chapters.