7.2. Getting Started
Prev | Chapter 7. Zend_Controller | Next

## 7.2. Getting Started

### 7.2.1. Introduction

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.

### 7.2.2. Server Configuration

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.

| Location of the bootstrap file
The bootstrap file should be the only PHP file stored in the document root.

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.

### 7.2.3. Bootstrap File

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.

| Note
The bootstrap file should be the only PHP file stored in 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()`.

### 7.2.4. Directory Structure

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

| Note
This section is not yet complete. It is under heavy construction and is subject to change.

### 7.2.5. Default Controller

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.

| Note
This section is not yet complete. It is under heavy construction and is subject to change.

Prev | Up | Next
Chapter 7. Zend_Controller | Home | 7.3. Subclassing