Zend Framework: Zend_Controller_Action_Helper_ResourceLoader Component Proposal

Proposed Component Name	Zend_Controller_Action_Helper_ResourceLoader
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Controller_Action_Helper_ResourceLoader
Proposers	Graham Anderson
Zend Liaison	Matthew Weier O'Phinney
Revision	1.2 - 9th Sept 2008: Initial Draft. (wiki revision: 12)

The goal of this helper class is provide a standard way to load and share resource classes between Zend Framework modules where the application developer wishes to store such classes inside the module directory. This will help application developers create re-usable modules containing discreet functionality which in turn will benefit the Zend Framework community through greater code sharing.

Currently to share model and form classes among ZF MVC modules, a developer must typically use one of two strategies.

1. Develop his/her own loader class, perhaps extending or using Zend_Loader and using path spec functionality or maybe using the PluginLoader, or do some other thing like manipulate include paths via a dispatch loop plugin.

2. Store models, forms and other classes outside of a module directory, this allows quite easy sharing of resource type classes between modules, but increases the complexity of using re-using modules.

While these strategies work they are many and varied and there is no current official helper that performs loading functionality.

This class will provide a ZF standard way to load models, forms and other resource classes that are stored inside the module directory.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

This component will extend Zend_Controller_Action_Helper_Abstract
This component will use Zend_Loader_PluginLoader / Zend_Loader_PluginLoader_Interface
This component will load model, form and other class files and definitions into the current php execution cycle
This component will provide a mechanism for custom resource types and related plugin loaders.
This component will return class names of loaded resource classes
This component will not instantiate or return objects

Useful Information

To fully satisfy some of the requirements from comments, it may be necessary to implement the plugin loader interface and consume a loader class with functionality more suited to the scope of this proposal.

4. Dependencies on Other Framework Components

Zend_Loader_PluginLoader / Zend_Loader_PluginLoader_Interface

5. Theory of Operation

Consider an MVC application with the following 'users' module. Instead of storing the models and forms in a more general location e.g. application/models, application/forms or My/Forms/MyForm.php, storing the resource classes under the module reduces complexity for re-using and sharing modules.

It should be noted that this directory structure need not be used but is provided for the sake of example, though it is intended for a default module directory to be used for model and form resources.

application/
    modules/
        default
        users/
            controllers
            forms/
                LoginForm.php
                AccountDetailsForm.php
                RegisterForm.php
            models/
                UserModel.php
                GroupModel.php
            db/
                UserTable.php
                UserTableRow.php
            views

Resource class naming

Example class naming using resources from the above example. Classes are named to provide information as to which module and resource type they belong to e.g. Modulename_Resourcetype_* this also reflects the function of the resource class and the general location within the module.

This allows us to use data containing details of known application modules and this helpers internal list of known resource types to assemble prefixes for each plugin loader.

<?php
/**
 * Login form
 * Module: users
 * Resource type: form (pre-configured resource type)
 */
class Users_Form_Login extends Zend_Form{}

/**
 * Account details form
 * Module: users
 * Resource type: form (pre-configured resource type)
 */
class User_Form_AccountDetails extends Zend_Form{}

/** 
 * User table
 * Module: users
 * Resource type: db / dbtable / table (custom resource type)
 * @uses Users_Table_Row_User
 */
class Users_Table_User extends Zend_Db_Table_Abstract{}

/**
 * User table row
 * Module: users
 * Resourse type: db / dbtable / table (customresource type)
 */
class User_Table_Row_User extends Zend_Db_Table_Row_Abstract

/**
 * User model
 * Module: users
 * Resource type: model (pre-configured resource type)
 * @uses Users_Table_User
 */
class Users_Model_User extends My_Model_Abstract{}

/**
 * Groups model
 * Module: users
 * Resource type: model (pre-configured resource type)
 * @uses Users_Model_User
 * @uses Users_Table_User
 */
class Users_Model_Group extends My_Model_Abstract{}

Now our loader helper class can use prefix paths and the Zend_Loader_PluginLoader class to load these resource classes.

<?php

/**
 * A sample controller from any other module ( not the above users module )
 */
class Foo_BarController extends Zend_Controller_Action
{
    public function init()
    {
        // load resource classes from an array (or Zend_Config object)
        // the index keys are resource type names, the values are array's of resources
        $resources = array('model' => array('user', 'group'),
                           'db'  => array('user'));

        $resourceClassesLoaded  = $this->_helper->resourceLoader($resources);
    }

    public function bazAction()
    {
      
      // check user auth
      if (!$user->isAuthed) {

          // Load the login resource class of resource type "form"
          // the helper will use the resource type that matches the second arguement, in this case "form"
          $formClass = $this->_helper->resourceLoader('login', 'form');
          $this->view->loginForm = new $formClass();

      }
      
    }

    public function foobarAction()
    {
        // Default is to load a model class when no second argument is passed
        $modelClass = $this->_helper->resourceLoader('group');
        $model = new $modelClass();
    }

}

6. Milestones / Tasks

Working prototype [DONE] http://andtech.googlecode.com/svn/trunk/
Draught initial proposal [DONE]
Collect initial feedback and refine proposal/prototype [DONE]
Submit proposal for review [DONE]
Pending review outcome - inclusion to laboratory/incubator
Docs & unit tests

7. Class Index

Zend_Controller_Action_Helper_ResourceLoader

8. Use Cases

UC-01

See theory of operation, further use cases to follow

9. Class Skeletons

Zend_Controller_Action_Helper_ResourceLoader

class Zend_Controller_Action_Helper_ResourceLoader extends Zend_Controller_Action_Helper_Abstract
{

    const MODEL_RESOURCE    = 'model';
    const FORM_RESOURCE     = 'form';
    
    /**
     * Array of plugin loaders
     *
     * @var array
     */
    protected $_pluginLoaders = array();
    
    /**
     * Array of known resource types
     *
     * @var array
     */
    protected $_resourceTypes = array();
    
    /**
     * Array of known module directories
     *
     * @var array
     */
    protected $_moduleDirs = array();
    
    /**
     * The default resource type to load
     *
     * @var string
     */
    protected $_defaultResourceType = null;
    
    /**
     * The default plugin loader class
     * 
     * @var string
     */
    protected $_defaultPluginLoader = 'Zend_Loader_PluginLoader';
    
    /**
     * Flag for disabling loading of resorources classes from external modules
     * 
     * @var bool
     */
    protected $_loadExternalResources = null;
    
    /**
     * Constructor discovers known module directories, adds default
     * resource types ( models, forms ) and the default plugin loader. Unless 
     * specified, the default resource type to load will be model classes. 
     *
     * @param string $defaultResourceType OPTIONAL
     * @param bool $loadExternalModules OPTIONAL
     * @return void
     * @throws Zend_Controller_exception if default resource type is not a string
     */
    public function __construct($defaultResourceType = self::MODEL_RESOURCE, $loadExternalResources = true)
    {
    }
    
    /**
     * Add a plugin loader for a specified resource type
     *
     * @uses Zend_Loader if cannot find existing plugin loader class
     * @param string $resourceType the resource type the loader belongs to
     * @return void
     * @throws Zend_Controller_Exception if resource type does not exist
     * @throws Zend_Controller_Exception if not instance of loader interface
     */
    protected function _addLoader($resourceType)
    {
    }
    
    /**
     * Set the plugin loader for the given resource type, loader must be either
     * the loader classname or instance of Zend_Loader_PluginLoader_Interface
     * 
     * @param string $resourceType the name of the resoruce type
     * @param mixed|string|Zend_Loader_PluginLoader_Interface the plugin loader
     * @return void
     * @throws Zend_Controller_Exception if $resourceType argument is invalid
     */
    public function setLoader($resourceType, $loader)
    {
    }
    
    /**
     * Return a plugin loader for a specified resource type, the array of loaders
     * if argument is null, return null if resoruce type does not exist.
     *
     * @param string $resourceType
     * @return mixed|Zend_Loader_Plugin_Loader_Interface|array|null
     */
    public function getLoader($resourceType = null)
    {
    }
    
    /**
     * Add a resource type by name, $values argument is expected to be an array
     * of key/value pairs with at least 'path' set to a string representing the
     * path to the resources (relative to module root dir). Pass third argument 
     * as true if it is meant to overwrite an existing resourece type.
     *
     * e.g.
     * $resourceType = 'dbtable';
     * $values = array ( 'path'      => 'db/table',
     *                   'loader     => 'My_Loader_DbTableLoader',
     *                   'overwrite' => true );
     * 
     * @param string $resourceType
     * @param string $values
     * @return mixed|Zend_Controller_Action_Helper_ResourceLoader|null
     */
    public function addResourceType($resourceType, $values, $overwrite = false)
    {
    }
    
    /**
     * Add an array of resource types. 
     * 
     * e.g.
     * $resourceTypes = array(
     *                     'dbtable' => array(
     *                                      'path'      => 'db/table',
     *                                      'loader     => 'My_Loader_DbTableLoader',
     *                                      'overwrite' => true
     *                                  ));
     * 
     *
     * @param array $resourceTypes
     * @return Zend_Controller_Action_Helper_ResourceLoader
     */
    public function addResourceTypes($resourceTypes)
    {
    }
    
    /**
     * Return a known resource type
     * 
     * @param string $resourceType The name of the resource type
     * @return mixed|array|null resource type array or null if not known
     */
    public function getResourceType($resourceType)
    {
    }
    
    /**
     * Return the default resource type
     * 
     * @return string
     */
    public function getDefaultResourceType()
    {
    }
    
    /**
     * Is the resource type known?
     *
     * @param string $resourceType
     * @return bool
     */
    public function resourceTypeExists($resourceType)
    {
    }
    
    /**
     * Is the loader type instantiated?
     *
     * @param string $resourceType
     * @return bool
     */
    public function loaderExists($resourceType)
    {
    }
    
    /**
     * return whether externals are loadable 
     */
    public function canLoadExternalResources()
    {
    }
    
    /**
     * Load a resource and return the classname or null
     *
     * @param string $resourceName
     * @param string $type
     * @return mixed|string|null classname or false if not loaded
     */
    public function loadResource($resourceName = null, $resourceType = self::MODEL_RESOURCE)
    {
    }
    
    /**
     * Load a list of resources and return their class names
     *
     * @param array $resources
     */
    protected function _loadResourcesFromArray(array $resources)
    {
    }
    
    /**
     * Split the resource name if it's a more verbose substring of the resource
     * classname, if it is, return the last token/chunk as the resource name and
     * the second last chunk as the resource type. If this is a longer 
     * substring of the resource classname, then we assume the second paramter 
     * passed into the helper is a module name.
     * 
     * @var string $name
     * @return string the resource name
     */
    protected function _getloadParams($name, $type)
    {
    }
    
    /**
     * Load a model, proxies to loadResource()
     *
     * @return mixed|string|false
     */
    public function loadModel($modelName)
    {
    }
    
    /**
     * Load a form, proxies to loadResource()
     *
     * @param string $formName
     */
    public function loadForm($formName)
    {
    }
    
    /**
     * Hook method for helper broker, if no params passed, return $this. Will
     * try to load a model object by default of no resource type specified.
     *
     * @param mixed|string|Zend_Config|array $resource OPTIONAL
     * @param string $resourceType OPTIONAL
     * @return mixed|Zend_Controller_Action_Helper_ResourceLoader|array|string
     */
    public function direct($resource = null, $resourceType = self::MODEL_RESOURCE)
    {
    }
}

Page Operations

Browse Space

Zend_Controller_Action_Helper_ResourceLoader - Graham Anderson

Labels