4.2. Getting Started

4.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 interfaces Zend_Controller_Router_Interface and Zend_Controller_Dispatcher_Interface.

4.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.

4.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] Note
The bootstrap file should be the only PHP file stored in the document root.

For security purposes, Zend very strong 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().

[Note] Note
At this time, we are presently investigating solutions will not require mod_rewrite installation. We intend to suggest a configuration for systems both with and without mod_rewrite capabilities. Also, please note this system is not bound to Apache or mod_rewrite specifically, any webserver with similar redirection capabilities should be sufficient.

4.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] Note
This section is not yet complete. It is under heavy construction and is subject to change.

4.2.5. IndexController

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

http://framework.zend.com/

The IndexController class must be stored in a file named IndexController.php, and this must be stored in the controllers directory. The IndexController must subclass Zend_Controller_Action. Here is a sample IndexController:

<?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('/');
	}
}

?>

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