Controller Plugins

When using any of the abstract controller implementations shipped with zend-mvc, 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:

If your controller implements the setPluginManager(), getPluginManager() and plugin() methods, you can access these using their shortname via the plugin() method:

$plugin = $this->plugin('url');

For an extra layer of convenience, this shipped abstract controller implementations have __call() methods defined that allow you to retrieve plugins via method calls:

$plugin = $this->url();

AcceptableViewModelSelector Plugin

The AcceptableViewModelSelector is a helper that can be used to select an appropriate view model based on user defined criteria will be tested against the Accept header in the request.

As an example:

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\JsonModel;

class SomeController extends AbstractActionController
{
   protected $acceptCriteria = [
      'Zend\View\Model\JsonModel' => [
         'application/json',
      ],
      'Zend\View\Model\FeedModel' => [
         'application/rss+xml',
      ],
   ];

   public function apiAction()
   {
      $viewModel = $this->acceptableViewModelSelector($this->acceptCriteria);

      // Potentially vary execution based on model returned
      if ($viewModel instanceof JsonModel) {
         // ...
      }
   }
}

The above would return a standard Zend\View\Model\ViewModel instance if the criteria is not met, and the specified view model types if the specific criteria is met. Rules are matched in order, with the first match "winning."

Forward Plugin

Occasionally, you may want to dispatch additional controllers from within the matched controller. For example, you might use this approach to build up "widgetized" content. The Forward plugin helps enable this.

For the Forward plugin to work, the controller calling it must be ServiceLocatorAware; otherwise, the plugin will be unable to retrieve a configured and injected instance of the requested controller.

The plugin exposes a single method, dispatch(), which takes two arguments:

Forward returns the results of dispatching the requested controller; it is up to the developer to determine what, if anything, to do with those results. One recommendation is to aggregate them in any return value from the invoking controller.

As an example:

$foo = $this->forward()->dispatch('foo', ['action' => 'process']);
return [
    'somekey' => $somevalue,
    'foo'     => $foo,
];

Layout Plugin

The Layout plugin allows 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:

$this->layout()->setTemplate('layout/newlayout');

It also implements the __invoke magic method, which allows calling the plugin as a method call:

$this->layout('layout/newlayout');

Params Plugin

The Params plugin allows accessing parameters in actions from different sources.

It exposes several methods, one for each parameter source:

The plugin also implements the __invoke magic method, providing a shortcut for invoking the fromRoute method:

$this->params()->fromRoute('param', $default);
// or
$this->params('param', $default);

Redirect Plugin

Redirections are quite common operations within applications. If done manually, you will need to do the following steps:

The Redirect plugin does this work for you. It offers three methods:

In each case, the Response object is returned. If you return this immediately, you can effectively short-circuit execution of the request.

Requires MvcEvent

This plugin requires that the controller invoking it implements InjectApplicationEventInterface, and thus has an MvcEvent composed, as it retrieves the router from the event object.

As an example:

return $this->redirect()->toRoute('login-success');

Url Plugin

You may need to generate URLs from route definitions within your controllers; for example, to seed the view, generate headers, etc. While the MvcEvent object composes the router, doing so manually would require this workflow:

$router = $this->getEvent()->getRouter();
$url    = $router->assemble($params, ['name' => 'route-name']);

The Url helper makes this slightly more convenient:

$url = $this->url()->fromRoute('route-name', $params);

The fromRoute() method is the only public method defined, and is used to generate a URL string from the provided parameters. It has the following signature:

Requires MvcEvent

This plugin requires that the controller invoking it implements InjectApplicationEventInterface, and thus has an MvcEvent composed, as it retrieves the router from the event object.