Permalink
Browse files

Merge pull request #375 from robertbasic/fix/zend.mvc

Zend\Mvc docs
  • Loading branch information...
2 parents b3d5dfe + 84ff441 commit 8817c36d99e4793ed6c7ee54f388088ef106ff99 @Freeaqingme Freeaqingme committed Oct 13, 2012
@@ -98,27 +98,25 @@ EventManagerAware
Typically, it's nice to be able to tie into a controller's workflow without needing to extend it or hardcode
behavior into it. The solution for this at the framework level is to use the ``EventManager``.
-You can hint to the ``ServiceManager`` that you want an ``EventManager`` injected by implementing the interfaces
-``EventManagerAwareInterface`` and ``EventsCapableInterface``; the former tells the ``ServiceManager`` to inject an
-``EventManager``, the latter to other objects that this class has an accessible ``EventManager`` instance.
+You can hint to the ``ServiceManager`` that you want an ``EventManager`` injected by implementing the interface
+``EventManagerAwareInterface``, which tells the ``ServiceManager`` to inject an ``EventManager``.
-Combined, you define two methods. The first, a setter, should also set any ``EventManager`` identifiers you want to
-listen on, and the second, a getter, should simply return the composed ``EventManager`` instance
+You define two methods. The first, a setter, should also set any ``EventManager`` identifiers you want to
+listen on, and the second, a getter, should simply return the composed ``EventManager`` instance.
.. code-block:: php
:linenos:
use Zend\EventManager\EventManagerAwareInterface;
use Zend\EventManager\EventManagerInterface;
- use Zend\EventManager\EventsCapableInterface;
public function setEventManager(EventManagerInterface $events);
public function getEventManager();
.. _zend.mvc.controllers.interfaces.pluggable:
-Pluggable
-^^^^^^^^^
+Controller Plugins
+^^^^^^^^^^^^^^^^^^
Code re-use is a common goal for developers. Another common goal is convenience. However, this is often difficult
to achieve cleanly in abstract, general systems.
@@ -135,33 +133,35 @@ examples:
- Invoking and dispatching additional controllers
To facilitate these actions while also making them available to alternate controller implementations, we've created
-a ``PluginBroker`` implementation for the controller layer, ``Zend\Mvc\Controller\PluginBroker``, building on the
-``Zend\Loader\PluginBroker`` functionality. To utilize it, you simply need to implement the
-``Zend\Loader\Pluggable`` interface, and set up your code to use the controller-specific implementation by default:
+a ``PluginManager`` implementation for the controller layer, ``Zend\Mvc\Controller\PluginManager``, building on the
+``Zend\ServiceManager\AbstractPluginManager`` functionality. To utilize it, you simply need to implement the
+``setPluginManager(PluginManager $plugins)`` method, and set up your code to use the controller-specific implementation by default:
.. code-block:: php
:linenos:
- use Zend\Loader\Broker;
- use Zend\Mvc\Controller\PluginBroker;
+ use Zend\Mvc\Controller\PluginManager;
- public function setBroker(Broker $broker)
+ public function setPluginManager(PluginManager $plugins)
{
- $this->broker = $broker;
+ $this->plugins = $plugins;
+ $this->plugins->setController($this);
+
return $this;
}
- public function getBroker()
+ public function getPluginManager()
{
- if (!$this->broker instanceof Broker) {
- $this->setBroker(new PluginBroker);
+ if (!$this->plugins) {
+ $this->setPluginManager(new PluginManager());
}
- return $this->broker;
+
+ return $this->plugins;
}
- public function plugin($plugin, array $options = null)
+ public function plugin($name, array $options = null)
{
- return $this->getBroker()->load($plugin, $options);
+ return $this->getPluginManager()->get($name, $options);
}
.. _zend.mvc.controllers.action-controller:
@@ -181,7 +181,7 @@ interfaces, and uses the following assumptions:
- The "action" parameter is converted to a camelCased format and appended with the word "Action" to create a method
name. As examples: "foo" maps to "fooAction", "foo-bar" or "foo.bar" or "foo_bar" to "fooBarAction". The
controller then checks to see if that method exists. If not, the ``notFoundAction()`` method is invoked;
- otherwise, the discovered method.
+ otherwise, the discovered method is called.
- The results of executing the given action method are injected into the ``MvcEvent``'s "result" property (via
``setResult()``, and accesible via ``getResult()``).
@@ -220,16 +220,12 @@ Interfaces and Collaborators
- ``Zend\Stdlib\DispatchableInterface``
-- ``Zend\Loader\Pluggable``
-
- ``Zend\Mvc\InjectApplicationEventInterface``
- ``Zend\ServiceManager\ServiceLocatorAwareInterface``
- ``Zend\EventManager\EventManagerAwareInterface``
-- ``Zend\EventManager\EventsCapableInterface``
-
The composed ``EventManager`` will be configured to listen on the following contexts:
- ``Zend\Stdlib\DispatchableInterface``
@@ -279,16 +275,12 @@ Interfaces and Collaborators
- ``Zend\Stdlib\DispatchableInterface``
-- ``Zend\Loader\Pluggable``
-
- ``Zend\Mvc\InjectApplicationEventInterface``
- ``Zend\ServiceManager\ServiceLocatorAwareInterface``
- ``Zend\EventManager\EventManagerAwareInterface``
-- ``Zend\EventManager\EventsCapableInterface``
-
The composed ``EventManager`` will be configured to listen on the following contexts:
- ``Zend\Stdlib\DispatchableInterface``
@@ -60,6 +60,8 @@ and ``AbstractRestfulController`` do), you can access this object from the attac
Once you have the ``RouteMatch`` object, you can pull parameters from it.
+The same can be done using the :ref:`Params plugin<zend.mvc.controller-plugins.params>`.
+
.. _zend.mvc.examples.controllers.returning-early:
Returning early
@@ -16,7 +16,7 @@ The MVC layer is built on top of the following components:
from its initial bootstrapping of the application, to returning response and request calls,
to setting and retrieving routes and matched routes, as well as view rendering.
-- ``Zend\Http``, specifically the request and response objects, used within:
+- ``Zend\Http``, specifically the request and response objects, used within.
- ``Zend\Stdlib\DispatchableInterface``. All "controllers" are simply dispatchable objects.
@@ -40,7 +40,7 @@ Within the MVC layer, several sub-components are exposed:
workflow to provide features such as automated template name resolution, automated view model
creation and injection, and more.
-The gateway to the MVC is the `Zend\Mvc\Application`_ object (referred to as ``Application``
+The gateway to the MVC is the `Zend\\Mvc\\Application`_ object (referred to as ``Application``
henceforth). Its primary responsibilities are to **bootstrap** resources, **route** the request,
and to retrieve and **dispatch** the controller matched during routing. Once accomplished, it
will **render** the view, and **finish** the request, returning and sending the response.
@@ -57,7 +57,7 @@ The basic application structure follows:
application_root/
config/
- application.php
+ application.config.php
autoload/
global.php
local.php
@@ -68,13 +68,14 @@ The basic application structure follows:
public/
.htaccess
index.php
+ init_autoloader.php
The ``public/index.php`` marshalls all user requests to your website, retrieving an array of
configuration located in ``config/application.php``. On return, it ``run()``\ s the ``Application``,
processing the request and returning a response to the user.
The ``config`` directory as described above contains configuration used by the
-``Zend\Module\Manager`` to load modules and merge configuration (e.g., database configuration and
+``Zend\ModuleManager`` to load modules and merge configuration (e.g., database configuration and
credentials); we will detail this more later.
The ``vendor`` sub-directory should contain any third-party modules or libraries on which your
@@ -95,7 +96,7 @@ Basic Module Structure
A module may contain anything: PHP code, including MVC functionality; library code; view scripts;
and/or or public assets such as images, CSS, and JavaScript. The only requirement -- and even this
is optional -- is that a module acts as a PHP namespace and that it contains a ``Module.php`` class
-under that namespace. This class is eventually consumed by ``Zend\Module\Manager`` to perform a
+under that namespace. This class is eventually consumed by ``Zend\ModuleManager`` to perform a
number of tasks.
The recommended module structure follows:
@@ -142,7 +143,7 @@ The ``Module.php`` file directly under the module root directory will be in the
{
}
-When an ``init()`` method is defined, this method will be triggered by a ``Zend\Module\Manager`` listener
+When an ``init()`` method is defined, this method will be triggered by a ``Zend\ModuleManager`` listener
when it loads the module class, and passed an instance of the manager by default. This allows you to perform tasks such as
setting up module-specific event listeners. But be cautious, the ``init()`` method is called for **every** module on **every** page
request and should **only** be used for performing **lightweight** tasks such as registering event listeners.
@@ -155,13 +156,13 @@ The three ``autoload_*.php`` files are not required, but recommended. They provi
resolved via the ``__DIR__`` magic constant).
- ``autoload_function.php`` should return a PHP callback that can be passed to ``spl_autoload_register()``.
- Typically, this callback should utilize the map returned by ``autoload_filemap.php``.
+ Typically, this callback should utilize the map returned by ``autoload_classmap.php``.
- ``autoload_register.php`` should register a PHP callback (typically that returned by ``autoload_function.php``
with ``spl_autoload_register()``.
The point of these three files is to provide reasonable default mechanisms for autoloading the classes contained in
-the module, thus providing a trivial way to consume the module without requiring ``Zend\Module`` (e.g., for use
+the module, thus providing a trivial way to consume the module without requiring ``Zend\ModuleManager`` (e.g., for use
outside a ZF2 application).
The ``config`` directory should contain any module-specific configuration. These files may be in any format
@@ -188,7 +189,7 @@ Bootstrapping an Application
The ``Application`` has six basic dependencies.
-- **configuration**, usually an array or object implementing ``ArrayAccess``.
+- **configuration**, usually an array or object implementing ``Traversable``.
- **ServiceManager** instance.
@@ -213,7 +214,7 @@ These may be satisfied at instantiation:
use Zend\Mvc\Application;
use Zend\ServiceManager\ServiceManager;
- $config = include 'config/application.php';
+ $config = include 'config/application.config.php';
$serviceManager = new ServiceManager();
$serviceManager->setService('EventManager', new EventManager());
@@ -342,8 +343,8 @@ Each ``Module`` class that has configuration it wants the ``Application`` to kno
}
There are a number of other methods you can define for tasks ranging from providing autoloader configuration, to
-providing services to the ``ServiceManager``, to listening to the bootstrap event. The ModuleManager documentation
-goes into more detail on these.
+providing services to the ``ServiceManager``, to listening to the bootstrap event. The :ref:`ModuleManager documentation
+<zend.module-manager.intro>` goes into more detail on these.
.. _zend.mvc.intro.conclusion:
@@ -356,6 +357,6 @@ is a lightweight and simple approach to enforcing a modular architecture that en
concerns and code re-use.
-.. _`Zend\Mvc\Application`: https://github.com/zendframework/zf2/blob/master/library/Zend/Mvc/Application.php
+.. _`Zend\\Mvc\\Application`: https://github.com/zendframework/zf2/blob/master/library/Zend/Mvc/Application.php
.. _`PSR-0 compliant directory structure`: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
.. _`PHPUnit`: http://phpunit.de
@@ -54,6 +54,20 @@ The methods it defines are:
- ``getViewModel()``
+- ``isError()``
+
+- ``setError()``
+
+- ``getError()``
+
+- ``getController()``
+
+- ``setController($name)``
+
+- ``getControllerClass()``
+
+- ``setControllerClass($class)``
+
The ``Application``, ``Request``, ``Response``, ``Router``, and ``ViewModel`` are all injected during the
``bootstrap`` event. Following the ``route`` event, it will be injected also with the ``RouteMatch`` object
encapsulating the results of routing.
@@ -3,25 +3,28 @@
Controller Plugins
==================
-When using the ``AbstractActionController`` or ``AbstractRestfulController``, or if you compose the
-``Zend\Mvc\Controller\PluginBroker`` in your custom controllers, you have access to a number of pre-built plugins.
-Additionally, you can register your own custom plugins with the broker, just as you would with
-``Zend\Loader\PluginBroker``.
+When using the ``AbstractActionController`` or ``AbstractRestfulController``, or if you implement the
+``setPluginManager`` method in your custom controllers, you have access to a number of pre-built plugins.
+Additionally, you can register your own custom plugins with the manager.
The built-in plugins are:
- ``Zend\Mvc\Controller\Plugin\FlashMessenger``
- ``Zend\Mvc\Controller\Plugin\Forward``
+- ``Zend\Mvc\Controller\Plugin\Layout``
+
+- ``Zend\Mvc\Controller\Plugin\Params``
+
- ``Zend\Mvc\Controller\Plugin\PostRedirectGet``
- ``Zend\Mvc\Controller\Plugin\Redirect``
- ``Zend\Mvc\Controller\Plugin\Url``
-If your controller implements the ``Zend\Loader\Pluggable`` interface, you can access these using their shortname
-via the ``plugin()`` method:
+If your controller implements the ``setPluginManager``, ``getPluginManager`` and ``plugin`` methods, you can access
+these using their shortname via the ``plugin()`` method:
.. code-block:: php
:linenos:
@@ -132,6 +135,64 @@ As an example:
'foo' => $foo,
);
+.. _zend.mvc.controller-plugins.layout:
+
+The Layout Plugin
+-----------------
+
+The ``Layout`` plugin allows for changing layout templates from within controller actions.
+
+It exposes a single method, ``setTemplate()``, which takes one argument:
+
+- ``$template``, the name of the template to set.
+
+As an example:
+
+.. code-block:: php
+ :linenos:
+
+ $this->layout()->setTemplate('layout/newlayout');
+
+It also implements the ``__invoke`` magic method, which allows for even easier setting of the template:
+
+.. code-block:: php
+ :linenos:
+
+ $this->layout('layout/newlayout');
+
+.. _zend.mvc.controller-plugins.params:
+
+The Params Plugin
+-----------------
+
+The ``Params`` plugin allows for accessing parameters in actions from different sources.
+
+It exposes several methods, one for each parameter source:
+
+- ``fromFiles($name=null,$default=null)``, for retrieving all, or one single file. If ``$name`` is `null`, all files
+ will be returned.
+
+- ``fromHeader($header=null,$default=null)``, for retrieving all, or one single header parameter. If ``$header``
+ is `null`, all header parameters will be returned.
+
+- ``fromPost($param=null,$default=null)``, for retrieving all, or one single post parameter. If ``$param`` is
+ `null`, all post parameters will be returned.
+
+- ``fromQuery($param=null,$default=null)``, for retrieving all, or one single query parameter. If ``$param`` is
+ `null`, all query parameters will be returned.
+
+- ``fromRoute($param=null,$default=null)``, for retrieving all, or one single route parameter. If ``$param`` is
+ `null`, all route parameters will be returned.
+
+It also implements the ``__invoke`` magic method, which allows for short circuiting to the ``fromRoute`` method:
+
+.. code-block:: php
+ :linenos:
+
+ $this->params()->fromRoute('param', $default);
+ // or
+ $this->params('param', $default);
+
.. _zend.mvc.controller-plugins.postredirectget:
The Post/Redirect/Get Plugin
@@ -195,8 +256,10 @@ The ``Redirect`` plugin does this work for you. It offers two methods:
In each case, the ``Response`` object is returned. If you return this immediately, you can effectively
short-circuit execution of the request.
-One note: this plugin requires that the controller invoking it implements ``InjectApplicationEvent``, and thus has
-an ``MvcEvent`` composed, as it retrieves the router from the event object.
+.. note::
+
+ This plugin requires that the controller invoking it implements ``InjectApplicationEvent``, and thus has
+ an ``MvcEvent`` composed, as it retrieves the router from the event object.
As an example:
@@ -234,7 +297,8 @@ The ``fromRoute()`` method is the only public method defined, and has the follow
public function fromRoute($route, array $params = array(), array $options = array())
-One note: this plugin requires that the controller invoking it implements ``InjectApplicationEvent``, and thus has
-an ``MvcEvent`` composed, as it retrieves the router from the event object.
+.. note::
+ This plugin requires that the controller invoking it implements ``InjectApplicationEvent``, and thus has
+ an ``MvcEvent`` composed, as it retrieves the router from the event object.
Oops, something went wrong.

0 comments on commit 8817c36

Please sign in to comment.