Core Functionality

Zend_Application

Zend_Application provides the base functionality of the component, and the entry point to your Zend Framework application. It's purpose is two-fold: to setup the PHP environment (including autoloading), and to execute your application bootstrap.

Typically, you will pass all configuration to the Zend_Application constructor, but you can also configure the object entirely using its own methods. This reference is intended to illustrate both use cases.

表 2. Zend_Application options

Option	Description
phpSettings	Array of `php.ini` settings to use. Keys should be the `php.ini` keys.
includePaths	Additional paths to prepend to the include_path. Should be an array of paths.
autoloaderNamespaces	Array of additional namespaces to register with the `Zend_Loader_Autoloader` instance.
bootstrap	Either the string path to the bootstrap class, or an array with elements for the 'path' and 'class' for the application bootstrap.

Option names

Please note that option names are case insensitive.

表 3. Zend_Application Methods

Method	Return Value	Parameters	Description
`__construct($environment, $options = null)`	Void	`$environment`: required,. String representing the current application environment. Typical strings might include "development", "testing", "qa", or "production", but will be defined by your organizational requirements. `$options`: optional. Argument may be one of the following values: String: path to a `Zend_Config` file to load as configuration for your application. `$environment` will be used to determine what section of the configuration to pull. As of 1.10, you may also pass multiple paths containing config files to be merged into a single configuration. This assists in reducing config duplication across many contexts which share common settings (e.g. configs for HTTP, or CLI, each sharing some characteristics but with their own conflicting values for others) or merely splitting a long configuration across many smaller categorised files. The parameter in this case is an array with a single key "config" whose value is an array of the files to merge. Note: this means you either pass a literal path, or array("config"=>array("/path1","/path2"[,...]));. Array: associative array of configuration data for your application. `Zend_Config`: configuration object instance.	Constructor. Arguments are as described, and will be used to set initial object state. An instance of `Zend_Loader_Autoloader` is registered during instantiation. Options passed to the constructor are passed to `setOptions()`.
`getEnvironment()`	String	N/A	Retrieve the environment string passed to the constructor.
`getAutoloader()`	`Zend_Loader_Autoloader`	N/A	Retrieve the `Zend_Loader_Autoloader` instance registered during instantiation.
`setOptions(array $options)`	`Zend_Application`	`$options`: required. An array of application options.	All options are stored internally, and calling the method multiple times will merge options. Options matching the various setter methods will be passed to those methods. As an example, the option "phpSettings" will then be passed to `setPhpSettings()`. (Option names are case insensitive.)
`getOptions()`	Array	N/A	Retrieve all options used to initialize the object; could be used to cache `Zend_Config` options to a serialized format between requests.
`hasOption($key)`	Boolean	`$key`: String option key to lookup	Determine whether or not an option with the specified key has been registered. Keys are case insensitive.
`getOption($key)`	Mixed	`$key`: String option key to lookup	Retrieve the option value of a given key. Returns `NULL` if the key does not exist.
`setPhpSettings(array $settings, $prefix = '')`	`Zend_Application`	`$settings`: required. Associative array of PHP INI settings. `$prefix`: optional. String prefix with which to prepend option keys. Used internally to allow mapping nested arrays to dot-separated `php.ini` keys. In normal usage, this argument should never be passed by a user.	Set run-time `php.ini` settings. Dot-separated settings may be nested hierarchically (which may occur with INI `Zend_Config` files) via an array-of-arrays, and will still resolve correctly.
`setAutoloaderNamespaces(array $namespaces)`	`Zend_Application`	`$namespaces`: required. Array of strings representing the namespaces to register with the `Zend_Loader_Autoloader` instance.	Register namespaces with the `Zend_Loader_Autoloader` instance.
`setBootstrap($path, $class = null)`	`Zend_Application`	`$path`: required. May be either a `Zend_Application_Bootstrap_Bootstrapper` instance, a string path to the bootstrap class, an associative array of classname => filename, or an associative array with the keys 'class' and 'path'. `$class`: optional. If `$path` is a string, `$class` may be specified, and should be a string class name of the class contained in the file represented by path.
`getBootstrap()`	`NULL` \| `Zend_Application_Bootstrap_Bootstrapper`	N/A	Retrieve the registered bootstrap instance.
`bootstrap()`	Void	N/A	Call the bootstrap's `bootstrap()` method to bootstrap the application.
`run()`	Void	N/A	Call the bootstrap's `run()` method to dispatch the application.

Zend_Application_Bootstrap_Bootstrapper

Zend_Application_Bootstrap_Bootstrapper is the base interface all bootstrap classes must implement. The base functionality is aimed at configuration, identifying resources, bootstrapping (either individual resources or the entire application), and dispatching the application.

The following methods make up the definition of the interface.

表 4. Zend_Application_Bootstrap_Bootstrapper Interface

Method	Return Value	Parameters	Description
`__construct($application)`	Void	`$application`: required. Should accept a `Zend_Application` or a `Zend_Application_Bootstrap_Bootstrapper` object as the sole argument.	Constructor. Accepts a single argument, which should be a `Zend_Application` object, or another bootstrap object.
`setOptions(array $options)`	`Zend_Application_Bootstrap_Bootstrapper`	`$options`: required. Array of options to set.	Typically, any option that has a matching setter will invoke that setter; otherwise, the option will simply be stored for later retrieval.
`getApplication()`	`Zend_Application` \| `Zend_Application_Bootstrap_Bootstrapper`	N/A	Retrieve the application or bootstrap object passed via the constructor.
`getEnvironment()`	String	N/A	Retrieve the environment string registered with the parent application or bootstrap object.
`getClassResources()`	Array	N/A	Retrieve a list of available resource initializer names as defined in the class. This may be implementation specific.
`bootstrap($resource = null)`	Mixed	`$resource`: optional.	If `$resource` is empty, execute all bootstrap resources. If a string, execute that single resource; if an array, execute each resource in the array.
`run()`	Void	N/A	Defines what application logic to run after bootstrapping.

Zend_Application_Bootstrap_ResourceBootstrapper

Zend_Application_Bootstrap_ResourceBootstrapper is an interface to use when a bootstrap class will be loading external resources -- i.e., one or more resources will not be defined directly in the class, but rather via plugins. It should be used in conjunction with Zend_Application_Bootstrap_Bootstrapper; Zend_Application_Bootstrap_BootstrapAbstract implements this functionality.

The following methods make up the definition of the interface.

表 5. Zend_Application_Bootstrap_ResourceBootstrapper Interface

Method	Return Value	Parameters	Description
`registerPluginResource($resource, $options = null)`	`Zend_Application_Bootstrap_ResourceBootstrapper`	`$resource`: required. A resource name or `Zend_Application_Resource_Resource` object. `$options`: optional. An array or `Zend_Config` object to pass to the resource on instantiation.	Register a resource with the class, providing optional configuration to pass to the resource.
`unregisterPluginResource($resource)`	`Zend_Application_Bootstrap_ResourceBootstrapper`	`$resource`: required. Name of a resource to unregister from the class.	Remove a plugin resource from the class.
`hasPluginResource($resource)`	Boolean	`$resource`: required. Name of the resource.	Determine if a specific resource has been registered with the class.
`getPluginResource($resource)`	`Zend_Application_Resource_Resource`	`$resource`: required. Name of a resource to retrieve (string).	Retrieve a plugin resource instance by name.
`getPluginResourceNames()`	Array	N/A	Retrieve a list of all registered plugin resource names.
`setPluginLoader(Zend_Loader_PluginLoader_Interface $loader)`	`Zend_Application_Bootstrap_ResourceBootstrapper`	`$loader`: required. Plugin loader instance to use when resolving plugin names to classes.	Register a plugin loader instance to use when resolving plugin class names.
`getPluginLoader()`	`Zend_Loader_PluginLoader_Interface`	N/A	Retrieve the registered plugin loader.

Zend_Application_Bootstrap_BootstrapAbstract

Zend_Application_Bootstrap_BootstrapAbstract is an abstract class which provides the base functionality of a common bootstrap. It implements both Zend_Application_Bootstrap_Bootstrapper and Zend_Application_Bootstrap_ResourceBootstrapper.

表 6. Zend_Application_Bootstrap_BootstrapAbstract Methods

Method	Return Value	Parameters	Description
`__construct($application)`	Void	`$application`: required. Accepts either a `Zend_Application` or a `Zend_Application_Bootstrap_Bootstrapper` object as the sole argument.	Constructor. Accepts a single argument, which should be a `Zend_Application` object, or another bootstrap object.
`setOptions(array $options)`	`Zend_Application_Bootstrap_Bootstrapper`	`$options`: required. Array of options to set.	Any option that has a matching setter will invoke that setter; otherwise, the option will simply be stored for later retrieval. As an example, if your extending class defined a `setFoo()` method, the option 'foo' would pass the value to that method. Two additional, special options keys may also be used. pluginPaths may be used to specify prefix paths to plugin resources; it should be an array of class prefix to filesystem path pairs. resources may be used to specify plugin resources to use, and should consist of plugin resource to instantiation options pairs.
`getOptions()`	Array	N/A	Returns all options registered via `setOptions()`.
`hasOption($key)`	Boolean	`$key`: required. Option key to test.	Determine if an option key is present.
`getOption($key)`	Mixed	`$key`: required. Option key to retrieve.	Retrieve the value associated with an option key; returns `NULL` if no option is registered with that key.
`setApplication(Zend_Application \| Zend_Application_Bootstrap_Bootstrapper $application)`	`Zend_Application_Bootstrap_BootstrapAbstract`	`$application`: required.	Register the parent application or bootstrap object.
`getApplication()`	`Zend_Application` \| `Zend_Application_Bootstrap_Bootstrapper`	N/A	Retrieve the application or bootstrap object passed via the constructor.
`getEnvironment()`	String	N/A	Retrieve the environment string registered with the parent application or bootstrap object.
`getClassResources()`	Array	N/A	Retrieve a list of available resource initializer names as defined in the class. This may be implementation specific.
`getContainer()`	Object	N/A	Retrieves the container that stores resources. If no container is currently registered, it registers a Zend_Registry instance before returning it.
`setContainer($container)`	`Zend_Application_Bootstrap_BootstrapAbstract`	`$container`, required. An object in which to store resources.	Provide a container in which to store resources. When a resource method or plugin returns a value, it will be stored in this container for later retrieval.
`hasResource($name)`	Boolean	`$name`, required. Name of a resource to check.	When a resource method or plugin returns a value, it will be stored in the resource container (see `getContainer()` and `setContainer()`. This method will indicate whether or not a value for that resource has been set.
`getResource($name)`	Mixed	`$name`, required. Name of a resource to fetch.	When a resource method or plugin returns a value, it will be stored in the resource container (see `getContainer()` and `setContainer()`. This method will retrieve a resources from the container.
`bootstrap($resource = null)`	Mixed	`$resource`: optional.	If `$resource` is empty, execute all bootstrap resources. If a string, execute that single resource; if an array, execute each resource in the array. This method can be used to run individual bootstraps either defined in the class itself or via resource plugin classes. A resource defined in the class will be run in preference over a resource plugin in the case of naming conflicts.
`run()`	Void	N/A	Defines what application logic to run after bootstrapping.
`__call($method, $args)`	Mixed	`$method`: required. The method name to call. `$args`: required. Array of arguments to use in the method call.	Provides convenience to bootstrapping individual resources by allowing you to call 'bootstrap<ResourceName>()' instead of using the `bootstrap()` method.

Zend_Application_Bootstrap_Bootstrap

Zend_Application_Bootstrap_Bootstrap is a concrete implementation of Zend_Application_Bootstrap_BootstrapAbstract. It's primary feature are that it registers the Front Controller resource, and that the run() method first checks that a default module is defined and then dispatches the front controller.

In most cases, you will want to extend this class for your bootstrapping needs, or simply use this class and provide a list of resource plugins to utilize.

Enabling Application Autoloading

Additionally, this bootstrap implementation provides the ability to specify the "namespace" or class prefix for resources located in its tree, which will enable autoloading of various application resources; essentially, it instantiates a Zend_Application_Module_Autoloader object, providing the requested namespace and the bootstrap's directory as arguments. You may enable this functionality by providing a namespace to the "appnamespace" configuration option. As an INI example:

appnamespace = "Application"

Or in XML:

<appnamespace>Application</appnamespace>

By default, Zend_Tool will enable this option with the value "Application".

Alternately, you can simply define the $_appNamespace property of your bootstrap class with the appropriate value:

class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{
    protected $_appNamespace = 'Application';
}

Zend_Application_Resource_Resource

Zend_Application_Resource_Resource is an interface for plugin resources used with bootstrap classes implementing Zend_Application_Bootstrap_ResourceBootstrapper. Resource plugins are expected to allow configuration, be bootstrap aware, and implement a strategy pattern for initializing the resource.

表 7. Zend_Application_Resource_Resource Interface

Method	Return Value	Parameters	Description
`__construct($options = null)`	Void	`$options`: optional. Options with which to set resource state.	The constructor should allow passing options with which to initialize state.
`setBootstrap(Zend_Application_Bootstrap_Bootstrapper $bootstrap)`	`Zend_Application_Resource_Resource`	`$bootstrap`: required. Parent bootstrap initializing this resource.	Should allow registering the parent bootstrap object.
`getBootstrap()`	`Zend_Application_Bootstrap_Bootstrapper`	N/A	Retrieve the registered bootstrap instance.
`setOptions(array $options)`	`Zend_Application_Resource_Resource`	`$options`: required. Options with which to set state.	Set resource state.
`getOptions()`	Array	N/A	Retrieve registered options.
`init()`	Mixed	N/A	Strategy pattern: run initialization of the resource.

Zend_Application_Resource_ResourceAbstract

Zend_Application_Resource_ResourceAbstract is an abstract class implementing Zend_Application_Resource_Resource, and is a good starting point for creating your own custom plugin resources.

Note: this abstract class does not implement the init() method; this is left for definition in concrete extensions of the class.

表 8. Zend_Application_Resource_ResourceAbstract Methods

Method	Return Value	Parameters	Description
`__construct($options = null)`	Void	`$options`: optional. Options with which to set resource state.	The constructor should allow passing options with which to initialize state.
`setBootstrap(Zend_Application_Bootstrap_Bootstrapper $bootstrap)`	`Zend_Application_Resource_ResourceAbstract`	`$bootstrap`: required. Parent bootstrap initializing this resource.	Should allow registering the parent bootstrap object.
`getBootstrap()`	`Zend_Application_Bootstrap_Bootstrapper`	N/A	Retrieve the registered bootstrap instance.
`setOptions(array $options)`	`Zend_Application_Resource_ResourceAbstract`	`$options`: required. Options with which to set state.	Set resource state.
`getOptions()`	Array	N/A	Retrieve registered options.

Resource Names

When registering plugin resources, one issue that arises is how you should refer to them from the parent bootstrap class. There are three different mechanisms that may be used, depending on how you have configured the bootstrap and its plugin resources.

First, if your plugins are defined within a defined prefix path, you may refer to them simply by their "short name" -- i.e., the portion of the class name following the class prefix. As an example, the class "Zend_Application_Resource_View" may be referenced as simply "View", as the prefix path "Zend_Application_Resource" is already registered. You may register them using the full class name or the short name:

$app = new Zend_Application(APPLICATION_ENV, array(
    'pluginPaths' => array(
        'My_Resource' => 'My/Resource/',
    ),
    'resources' => array(
        // if the following class exists:
        'My_Resource_View' => array(),

        // then this is equivalent:
        'View' => array(),
    ),
));

In each case, you can then bootstrap the resource and retrieve it later using the short name:

$bootstrap->bootstrap('view');
$view = $bootstrap->getResource('view');

Second, if no matching plugin path is defined, you may still pass a resource by the full class name. In this case, you can reference it using the resource's full class name:

$app = new Zend_Application(APPLICATION_ENV, array(
    'resources' => array(
        // This will load the standard 'View' resource:
        'View' => array(),

        // While this loads a resource with a specific class name:
        'My_Resource_View' => array(),
    ),
));

Obviously, this makes referencing the resource much more verbose:

$bootstrap->bootstrap('My_Resource_View');
$view = $bootstrap->getResource('My_Resource_View');

This brings us to the third option. You can specify an explicit name that a given resource class will register as. This can be done by adding a public $_explicitType property to the resource plugin class, with a string value; that value will then be used whenever you wish to reference the plugin resource via the bootstrap. As an example, let's define our own view class:

class My_Resource_View extends Zend_Application_Resource_ResourceAbstract
{
    public $_explicitType = 'My_View';

    public function init()
    {
        // do some initialization...
    }
}

We can then bootstrap that resource or retrieve it by the name "My_View":

$bootstrap->bootstrap('My_View');
$view = $bootstrap->getResource('My_View');

Using these various naming approaches, you can override existing resources, add your own, mix multiple resources to achieve complex initialization, and more.