Zend Framework: Zend_Application Component Proposal

Proposed Component Name	Zend_Application
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Application
Proposers	Ben Scholzen
Zend Liaison	Matthew Weier O'Phinney
Revision	1.0 - 16 September 2008: Initial Draft. 1.1 - 30 September 2008: Renamed to Zend_Application. 1.1 - 30 November 2008: Continued work (wiki revision: 13)

Zend_Application is a component to simplify and normalise the entire bootstrapping procedure into an easy and extensible system. This proposal uses ideas from other proposals like Zend_Application, which was archived yet. It is intended to take care of the entire ZF enviroment setup like database, view, layout and controller.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

This component MUST be configuration driven. Configuration may take the form of any combination of the following
- MUST allow programmatic configuration (i.e., via method calls)
- MUST allow passing configuration to the constructor via an array, Zend_Config object, or path to configuration file
- SHOULD allow passing configuration to one or more mutators via an array, Zend_Config object, or path to configuration file
This component MUST provide bootstrapping of the PHP environment (i.e., any ini_set-configurable keys)
- This component MUST allow setting the application include_path (aka library)
- This component MUST allow autoload initialization
  - It SHOULD allow specifying the alternate autoloading classes
- PHP environment bootstrapping MUST occur at instantiation, prior to application bootstrapping
This component MUST allow specification of environments
- Common default environments MUST be supported (development, testing, production)
This component MUST provide a plugin architecture for common application events/resources
- This component MUST provide common resources
  - configuration
  - route setup
  - controller/module directory setup
  - view and layout setup
  - DB initialization
  - cache initialization
  - i18n setup
  - etc
- This component MUST allow specification and utilization of arbitrary resources
- Resources SHOULD
  - run independently
  - run in groups or all at once
  - allow for dependencies
  - use naming conventions for initialization
This component MUST account for initialization of independent modules
- It SHOULD allow configuration of a standard bootstrap script location per module
- Module bootstrapping MUST run independently
- Module bootstrapping MUST be triggered by the application bootstrap

4. Dependencies on Other Framework Components

Zend_Exception
Zend_Loader
Zend_Loader_Autoload (TBA)
Zend_Loader_Autoload_Resource (TBA)
Zend_Loader_PluginLoader

5. Theory of Operation

Getting an MVC application configured and ready to dispatch has required an increasing amount of code as more features become available: setting up the database, configuring your view and view helpers, configuring your layouts, registering plugins, registering action helpers, and more.

Additionally, you will often want to re-use the same code to bootstrap your tests, a cronjob, or a service script. While it's possible to simply include your bootstrap script, oftentimes there are initializations that are environment specific – you may not need the MVC for a cronjob, or just the DB layer for a service script.

Zend_Application aims to make this easier and to promote reuse by encapsulating bootstrapping into OOP paradigms.

Zend_Application is broken into three realms:

Zend_Application: loads the PHP environment, including include_paths and autoloading, and instantiates the requested bootstrap class
Zend_Application_Bootstrap: provides an interface for bootstrap classes. Zend_Application_Bootstrap_Base provides common functionality for most bootstrapping needs, including dependency checking algorithms and the ability to load bootstrap resources on demand.
Zend_Application_Bootstrap_Resource provides an interface for standard bootstrapping resources that can be loaded on demand by a bootstrap instance.

Developers will create a bootstrap class for their application, extending Zend_Application_Bootstrap_Base or implementing Zend_Application_Bootstrap. The entry point (e.g., public/index.php) will load Zend_Application, and instantiate it by passing:

The current environment
Options for bootstrapping

Bootstrap options will include:

Optionally, any extra include_paths to set
Optionally, any additional autoloader namespaces to register
Optionally, any php.ini settings to initialize
Path to the file containing the bootstrap class
Optionally, the class name for the bootstrap class (if not "Bootstrap")
Optionally, resource prefix/path pairs to use
Optionally, any resources to use (by class name or short name)
Optionally, additional configuration options

To simplify setup, a path to a configuration file may be provided.

The Bootstrap class itself will typically be fairly minimal; often, it could consist of solely the following:

class Bootstrap extends Zend_Application_Bootstrap_Base
{
}

However, should custom initialization be necessary, the developer has two choices. First, they can write methods prefixed with "_init" to specify discrete code to bootstrap. These methods will be called by bootstrap(), and can also be called as if they were public methods: init<resource>(). They should accept an optional array of options.

class Bootstrap extends Zend_Application_Bootstrap_Base
{
    protected function _initRequest(array $options = array())
    {
        // ensure front controller instance is present
        $this->initFrontController();
        $this->request = new Zend_Controller_Request_Http();
        $this->front->setRequest($this->request);
    }
}

Note in this example the call to "initFrontController"; this ensures that the front controller has been initialized prior to calling this method. That call may trigger either a resource or another method in the class.

The other option is to use bootstrap resources. Bootstrap resources are objects that perform specific initializations, and may be specified:

when instantiating the Zend_Application object
during initialization of the bootstrap object
by explicitly enabling them via method calls to the bootstrap object

Resources implement Zend_Application_Bootstrap_Resource, which defines simply that they allow injection of the caller and options, and that they have an init() method. As an example, a custom "View" bootstrap resource might look like the following:

class My_Bootstrap_Resource_View extends Zend_Application_Bootstrap_Resource_Base
{
    public function init(array $options = array())
    {
        $view = new Zend_View($options);
        Zend_Dojo::enableView($view);
        $view->doctype('XHTML1_STRICT');
        $view->headTitle()->setSeparator(' - ')->append('My Site');
        $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=utf-8');
        $view->dojo()->setDjConfigOption('parseOnLoad', true)
                     ->setLocalPath('/js/dojo/dojo.js')
                     ->registerModulePath('../spindle', 'spindle')
                     ->addStylesheetModule('spindle.themes.spindle')
                     ->requireModule('spindle.main')
                     ->disable();
        $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer');
        $viewRenderer->setView($view);
        Zend_Registry::set('view', $view);
    }
}

To tell the bootstrap to use this, you would need to provide either the class name of the resource, or a combination of a plugin loader prefix path and the short name of the resource (e.g, "view"):

$application = new Zend_Application(
    APPLICATION_ENV,
    array(
        'resources' => array(
            'My_Bootstrap_Resource_View', // full class name; OR
            'view',                       // short name
        ),

        // For short names, define resource paths:
        'resourcePaths = array(
            'My_Bootstrap_Resource' => 'My/Bootstrap/Resource',
        )
    )
);

Resources can call on other resources and initializers by accessing the parent object:

class My_Bootstrap_Resource_Layout extends Zend_Application_Bootstrap_Resource_Base
{
    public function init(array $options = array())
    {
        // ensure view is initialized...
        $this->getParent()->initView();

        // ...
    }
}

In normal usage, you would instantiate the application, bootstrap it, and run it:

$application = new Zend_Application(...);
$application->bootstrap();
$application->run();

For a custom script, you might need to simply initialize specific resources:

$application = new Zend_Application(...);
$application->initDb();

$service = new Zend_XmlRpc_Server();
$service->setClass('Foo');  // uses database...
echo $service->handle();

6. Milestones / Tasks

Milestone 1: Requirement specifications
Milestone 2: Creating working prototype
Milestone 3: Unit tests exist
Milestone 4: Documentation exists

7. Class Index

Zend_Application
Zend_Application_Exception
Zend_Application_Bootstrap
Zend_Application_Bootstrap_Base
Zend_Application_Bootstrap_Module
Zend_Application_Bootstrap_Resource
Zend_Application_Bootstrap_Resource_Base
Zend_Application_Bootstrap_Resource_Exception
Zend_Application_Bootstrap_Resource_Db
Zend_Application_Bootstrap_Resource_Front
Zend_Application_Bootstrap_Resource_Layout
Zend_Application_Bootstrap_Resource_Session
Zend_Application_Bootstrap_Resource_View

8. Use Cases

Example showing convention-driven bootstrap (using initializer methods).

Dependencies are handled by the base bootstrap class, via __call(). Calls to ->init(Resourcename) will go through there, and call the appropriate protected method, passing in any configuration that matches that particular resource key in the config object. If the resource has been called already, it will return early.

class Bootstrap extends Zend_Application_Bootstrap_Base
{
    public $front;

    public function init()
    {
        $this->front = Zend_Controller_Front::getInstance();
    }

    public function run()
    {
        $this->front->dispatch();
    }

    protected function _initControllers()
    {
        $this->front->setControllerDirectory(APPLICATION_PATH . '/controllers', 'default');
        $this->front->addModuleDirectory(APPLICATION_PATH . '/modules');
        return $this;
    }

    protected function _initRequest()
    {
        $this->request = new Zend_Controller_Request_Http;
        $this->front->setRequest($this->request);
        return $this;
    }

    protected function _initHelpers(array $options = array())
    {
        $options[] = 'My_Controller_Helper';
        foreach ($options as $prefix) {
            Zend_Controller_Action_HelperBroker::addPrefix($prefix);
        }
        Zend_Controller_Action_HelperBroker::getStaticHelper('ResourceLoader');
        return $this;
    }

    protected function _initDb(array $options = array())
    {
        $config   = new Zend_Config($options);
        $profiler = new Zend_Db_Profiler_Firebug('All DB Queries');
        $db       = Zend_Db::factory($config);

        $profiler->setEnabled($config->profiler->enabled);
        $db->setProfiler($profiler);
        Zend_Db_Table_Abstract::setDefaultAdapter($db);
        return $this;
    }

    protected function _initModules()
    {
        $this->initControllers();
        $modules = $this->front->getControllerDirectory();

        foreach ($modules as $module => $dir) {
            if ('default' == $module) {
                continue;
            }
            $bootstrapFile = dirname($dir) . '/Bootstrap.php';
            $class         = ucfirst($module) . '_Bootstrap';
            if (Zend_Loader::loadFile('Bootstrap.php', dirname($dir))
                && class_exists($class)
            ) {
                $bootstrap = new $class($this);
                $bootstrap->bootstrap();
            }
        }
        return $this;
    }
}

Example showing convention-driven module bootstrap (using initializer methods). Note the calls to getParent(), which retrieves the parent bootstrap.

class Spindle_Bootstrap extends Zend_Application_Bootstrap_Module
{
    public function init()
    {
        $this->moduleDir = realpath(dirname(__FILE__));
    }

    public function getResourceLoader()
    {
        if (null === $this->_resourceLoader) {
            $resourceLoader = new Zend_Loader_Autoload_Resource(array(
                'prefix'   => 'Spindle',
                'basePath' => $this->moduleDir,
            ));
            $this->setResourceLoader($resourceLoader);
        }
        return $this->_resourceLoader;
    }

    protected function _initAutoloader()
    {
        $autoloader = $this->getResourceLoader();
        return $this;
    }

    protected function _initConfig()
    {
        $appBootstrap = $this->getParent();
        $configMaster = $appBootstrap->config;
        $config       = new Zend_Config_Ini(
            $this->moduleDir . '/config/spindle.ini', 
            $appBootstrap->getEnvironment()
        );
        $configMaster->merge($config);
        return $this;
    }

    protected function _initPlugins()
    {
        $loader = $this->getResourceLoader();

        $front  = $this->getParent()->front;
        $front->registerPlugin(new Spindle_Plugin_Auth);
        return $this;
    }

    protected function _initJsEnabled()
    {
        $appBootstrap = $this->getParent();
        $request      = $appBootstrap->request;
        if ($request->getParam('jsEnabled', false)) {
            setcookie('spindleJsEnabled', 1, strtotime('+30 days'));
            $request->setParam('jsEnabled', true);
        } elseif ($request->getCookie('spindleJsEnabled', false)) {
            $request->setParam('jsEnabled', true);
        } else {
            $request->setParam('jsEnabled', false);
        }
        return $this;
    }
}

Sample resource; initializes view and configures several view helpers.

class My_Bootstrap_Resource_View extends Zend_Application_Bootstrap_Resource_Base
{
    public function init(array $options = array())
    {
        $view = new Zend_View($options);
        Zend_Dojo::enableView($view);
        $view->doctype('XHTML1_STRICT');
        $view->headTitle()->setSeparator(' - ')->append('My Site');
        $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=utf-8');
        $view->dojo()->setDjConfigOption('parseOnLoad', true)
                     ->setLocalPath('/js/dojo/dojo.js')
                     ->registerModulePath('../spindle', 'spindle')
                     ->addStylesheetModule('spindle.themes.spindle')
                     ->requireModule('spindle.main')
                     ->disable();
        $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer');
        $viewRenderer->setView($view);
        Zend_Registry::set('view', $view);
    }
}

9. Class Skeletons

class Zend_Application_Exception extends Zend_Exception {}

class Zend_Application {
...

Page Operations

Browse Space

Zend_Application - Ben Scholzen

Labels

Zend Framework: Zend_Application Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

4. Dependencies on Other Framework Components

5. Theory of Operation

6. Milestones / Tasks

7. Class Index

8. Use Cases

9. Class Skeletons

Introduction and how it relates to Zym_App

What should the component do?

Resources / bootstrap modules

Relation to other components

Conclusion (for now)