Zend Framework: Zend_Controller_Directory Component Proposal

Table of Contents

1. Overview

The Zend_Controller_Directory component allows users to define directory names and paths.

Goals

This proposal attempts to solve the following problems:

1. Zend_Controller_Front violates the single responsibility principle, each responsibility should be a separate class.
2. Zend_Controller_Front is not polymorphic and therefore makes the system less tolerant to change in requirements.
3. Zend_Controller_Front provides data to the Zend_Controller_Dispatcher_Standard object creating control coupling.
4. Extending Zend_Controller_Dispatcher_Abstract violates the DRY principle.
5. Zend_Controller_Dispatcher_Standard allows components not only to retrieve directory names and paths, but also to dispatch controllers. This includes Action Controllers and Action Helpers.

Example

The Front Controller needs one or more paths to directories containing action controllers in order to dispatch the request:

To add additional directory names and paths, the user has to create a class that extends Zend_Controller_Dispatcher_Abstract and implements Zend_Controller_Dispatcher_Interface:

Extending the Zend_Controller_Dispatcher_Abstract class leads to the following problems:

1. Code Duplication

In order to add additional methods, the user has to duplicate the behaviour and internal structure of the Zend_Controller_Dispatcher_Standard class. This approach violates the DRY principle:

2. API Inconsistency

Because the Front Controller is a singleton and cannot be subclassed, the user is unable to add additional accessor methods to the Front Controller, therefore there's no consistency in the way the data is provided and retrieved from the Dispatcher:

2. References

• Refactoring the Front Controller
• Refactoring the Front Controller - Unofficial Proposal

3. Component Requirements, Constraints, and Acceptance Criteria

• This component will provide abstracts that facilitate the extension of the base functionality.

4. Dependencies on Other Framework Components

• Zend_Exception

5. Theory of Operation

Zend Framework organizes code in a project structure and puts the project files into different directory structures:

1. MVC directory structure
2. Modular directory structure

The goal of this component is to move this responsibility away from the Front Controller, avoid code duplication, reduce control coupling and improve the consistency of the API.

6. Milestones / Tasks

• Write proposal
• Gather feedback
• Review by the Zend team
• Develop full implementation and unit tests
• Documentation

7. Class Index

• Zend_Controller_Directory_Abstract
• Zend_Controller_Directory_Exception
• Zend_Controller_Directory_Standard

8. Use Cases

UC-01 Bootstrapper example

9. Class Skeletons

• Zend_Controller_Directory_Abstract
  abstract class Zend_Controller_Directory_Abstract { /** * Directory|ies where controllers are stored * @var null|array */ protected $_controllerDir = null; /** * Directory|ies where models are stored * @var null|array */ protected $_modelDir = null; /** * Directory|ies where views are stored * @var null|array */ protected $_viewDir = null; /** * Subdirectory containing controllers; defaults to 'controllers' * @var string */ protected $_controllerDirectoryName = 'controllers'; /** * Subdirectory containing models; defaults to 'models' * @var string */ protected $_modelDirectoryName = 'models'; /** * Subdirectory containing views; defaults to 'views' * @var string */ protected $_viewDirectoryName = 'views'; /** * Default module * @var string */ protected $_defaultModule = 'default'; /** * Set controller directory * * @param string|array $directory Path to Zend_Controller_Action controller * classes or array of such paths * @param string $module Optional module name to use with string $directory * @return Zend_Controller_Directory_Abstract */ public function setControllerDirectory($directory, $module = null) /** * Return the currently set directories for Zend_Controller_Action class * lookup * * If a module is specified, returns just that directory. * * @param string $module Module name * @return array|string Returns array of all directories by default, single * module directory if module argument provided */ public function getControllerDirectory($module = null) /** * Add a controller directory to the controller directory stack * * @param string $path * @param string|null $module Module with which to associate directory. * @return Zend_Controller_Directory_Abstract */ public function addControllerDirectory($path, $module = null) /** * Remove a controller directory by module name * * @param string $module * @return bool */ public function removeControllerDirectory($module) /** * Set the directory name containing controllers * * @param string $name * @return Zend_Controller_Directory_Abstract */ public function setControllerDirectoryName($name = 'controllers') /** * Return the directory name containing controllers * * @return string */ public function getControllerDirectoryName() /** * Set the directory name containing models * * @param string $name * @return Zend_Controller_Directory_Abstract */ public function setModelDirectoryName($name = 'models') /** * Return the directory name containing models * * @return string */ public function getModelDirectoryName() /** * Set the directory name containing views * * @param string $name * @return Zend_Controller_Directory_Abstract */ public function setViewDirectoryName($name = 'views') /** * Return the directory name containing views * * @return string */ public function getViewDirectoryName() /** * Set the default module * * @param string $module * @return Zend_Controller_Directory_Abstract */ public function setDefaultModule($module) /** * Retrieve the default module * * @return string */ public function getDefaultModule() }

• Zend_Controller_Directory_Standard
  class Zend_Controller_Directory_Standard extends Zend_Controller_Directory_Abstract { /** * Specify a directory as containing controllers * * @param string $path * @param string|null $module Module with which to associate directory. * @return Zend_Controller_Directory_Standard */ public function addApplicationDirectory($path, $module = null) /** * Specify a directory as containing modules * * Iterates through the directory, adding any subdirectories as modules; * the subdirectory within each module named after {@link $_moduleControllerDirectoryName} * will be used as the controller directory path. * * @param string $path * @return Zend_Controller_Directory_Standard */ public function addModuleDirectory($path) }

• Zend_Controller_Front
  class Zend_Controller_Front { /* remove: public function getControllerDirectory() */ /* remove: public function setControllerDirectory() */ /* remove: public function removeControllerDirectory() */ /* remove: public function addControllerDirectory() */ /* remove: public function addModuleDirectory() */ /* remove: public function setModuleControllerDirectoryName() */ /* remove: public function getModuleControllerDirectoryName() */ protected $_directory = null; /** * Resets all object properties of the singleton instance * * Primarily used for testing; could be used to chain front controllers. * * @return void */ public function resetInstance() { $reflection = new ReflectionObject($this); foreach ($reflection->getProperties() as $property) { $name = $property->getName(); switch ($name) { case '_instance': break; case '_invokeParams': $this->{$name} = array(); break; case '_plugins': $this->{$name} = new Zend_Controller_Plugin_Broker(); break; case '_throwExceptions': case '_returnResponse': $this->{$name} = false; break; case '_directory': $this->{$name} = null; break; default: $this->{$name} = null; break; } } } /** * Convenience feature, calls setControllerDirectory()->setRouter()->dispatch() * * In PHP 5.1.x, a call to a static method never populates $this -- so run() * may actually be called after setting up your front controller. * * @param string|array $controllerDirectory Path to Zend_Controller_Action * controller classes or array of such paths * @return void * @throws Zend_Controller_Exception if called from an object instance */ public static function run($controllerDirectory) { $frontController = self::getInstance(); $frontController->getDirectory()->setControllerDirectory($controllerDirectory); $frontController->dispatch(); } /** * Return the directory object * * @return Zend_Controller_Directory_Abstract */ public function getDirectory() { if (!$this->_directory instanceof Zend_Controller_Directory_Abstract) { require_once 'Zend/Controller/Directory/Standard.php'; $this->_directory = new Zend_Controller_Directory_Standard(); } return $this->_directory; } /** * Set the directory object * * @param Zend_Controller_Directory_Abstract $directory * @return Zend_Controller_Front */ public function setDirectory(Zend_Controller_Directory_Abstract $directory) { $this->_directory = $directory; return $this; } }

• Zend_Controller_Dispatcher_Abstract
  abstract class Zend_Controller_Dispatcher_Abstract implements Zend_Controller_Dispatcher_Interface { /* remove: public function setDefaultModule() */ /* remove: public function getDefaultModule() */ /** * Return the directory object * * @return Zend_Controller_Directory_Abstract */ public function getDirectory() { return $this->getFrontController()->getDirectory(); } /** * Set the directory object * * @param Zend_Controller_Directory_Abstract $directory * @return Zend_Controller_Front */ public function setDirectory(Zend_Controller_Directory_Abstract $directory) { $this->getFrontController()->setDirectory($directory); return $this; } }

• Zend_Controller_Dispatcher_Standard
  class Zend_Controller_Dispatcher_Standard extends Zend_Controller_Dispatcher_Abstract { /* remove: public function getControllerDirectory() */ /* remove: public function setControllerDirectory() */ /* remove: public function addControllerDirectory() */ /* remove: public function removeControllerDirectory() */ /* refactor: $this->getControllerDirectory() becomes $this->getDirectory()->getControllerDirectory() */ /* refactor: $this->getDefaultModule() becomes $this->getDirectory()->getDefaultModule() */ /* refactor: $this->setDefaultModule() becomes $this->getDirectory()->setDefaultModule() */ /* refactor: $this->_defaultModule becomes $this->getDirectory()->getDefaultModule() */ }

• Zend_Controller_Action_Helper_ViewRenderer
  class Zend_Controller_Action_Helper_ViewRenderer extends Zend_Controller_Action_Helper_Abstract { /** * Get module directory * * @throws Zend_Controller_Action_Exception * @return string */ public function getModuleDirectory() { $module = $this->getModule(); $directory = $this->getFrontController()->getDirectory(); $moduleDir = $directory->getControllerDirectory($module); if ((null === $moduleDir) || is_array($moduleDir)) { /*** @see Zend_Controller_Action_Exception */ throw new Zend_Controller_Action_Exception('ViewRenderer cannot locate module directory'); } $this->_moduleDir = dirname($moduleDir); return $this->_moduleDir; } }