Download the PHP package aura/dispatcher without Composer

Aura.Dispatcher

Provides tools to map arbitrary names to dispatchable objects, then to dispatch to those objects using named parameters. This is useful for invoking controller and command objects based on path-info parameters or command line arguments, for dispatching to closure-based controllers, and for building dispatchable objects from factories.

Foreword

Installation

This library requires PHP 5.4 or later; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies.

It is installable and autoloadable via Composer as aura/dispatcher.

Alternatively, download a release or clone this repository, then require or include its autoload.php file.

Quality

To run the unit tests at the command line, issue phpunit at the package root. (This requires PHPUnit to be available as phpunit.)

This library attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Community

To ask questions, provide feedback, or otherwise communicate with the Aura community, please join our Google Group, follow @auraphp on Twitter, or chat with us on #auraphp on Freenode.

Getting Started

Overview

First, an external routing mechanism such as Aura.Router or a micro-framework router creates an array of parameters. (Alternatively, the parameters may be an object that implements ArrayAccess).

The parameters are then passed to the Dispatcher. It examines them and picks an object to invoke with those parameters, optionally with a method determined by the parameters.

The Dispatcher then examines the returned result from that first invocation. If the result is itself a dispatchable object, the Dispatcher will recursively dispatch the result until something other than a dispatchable object is returned.

When a non-dispatchable result is returned, the Dispatcher stops recursion and returns the non-dispatchable result.

Closures and Invokable Objects

First, we tell the Dispatcher to examine the controller parameter to find the name of the object to dispatch to:

Next, we set a closure object into the Dispatcher using setObject():

We can now dispatch to that closure by using the name as the value for the controller parameter:

The same goes for invokable objects. First, define a class with an __invoke() method:

Next, set an instance of the object into the Dispatcher:

Finally, dispatch to the invokable object (the parameters and logic are the same as above):

Object Method

We can tell the Dispatcher to examine the params for a method to call on the object. This method will take precedence over the __invoke() method on an object, if such a method exists.

First, tell the Dispatcher to examine the value of the action param to find the name of the method it should invoke.

Next, define the object we will dispatch to; note that the method is read() instead of __invoke().

Then, we set the object into the Dispatcher ...

... and finally, we invoke the Dispatcher; we have added an action parameter with the name of the method to invoke:

Embedding Objects in Parameters

If you like, you can place dispatchable objects directly in the parameters. (This is often how micro-framework routers work.) For example, let's put a closure into the controller parameter; when we invoke the Dispatcher, it will invoke that closure.

The same is true for invokable objects ...

... and for object-methods:

Recursion and Lazy Loading

The Dispatcher is recursive. After dispatching to the first object, if that object returns a dispatchable object, the Dispatcher will re-dispatch to that object. It will continue doing this until the returned result is not a dispatchable object.

Let's turn the above example of an invokable object in the Dispatcher into a lazy-loaded instantiation. All we have to do is wrap the instantiation in another dispatchable object (in this example, a closure). The benefit of this is that we can fill the Dispatcher with as many objects as we like, and they won't get instantiated until the Dispatcher calls on them.

Then we invoke the dispatcher with the same params as before.

What happens is this:

• The Dispatcher finds the 'blog' dispatchable object, sees that it is a closure, and invokes it with the params.

• The Dispatcher examines the result, sees the result is a dispatchable object, and invokes it with the params.

• The Dispatcher examines that result, sees that it is not a callable object, and returns the result.

Sending The Array Of Params Directly

Sometimes you will want to send the entire array of parameters directly to the object method or closure, as opposed to matching parameter keys with function argument names. To do so, name a key in the parameters array for the argument name that will receive them, and then set the parameters array into itself using that name. If may be easier to do this by reference, or by copy, depending on your needs.

Refactoring To Architecture Changes

The Dispatcher is built with the idea that some developers may begin with a micro-framework architecture, and evolve over time toward a full-stack architecture.

At first, the developer uses closures embedded in the params:

After adding several controllers, the developer is likely to want to keep the routing configurations separate from the controller actions. At this point the developer may start putting the controller actions in the Dispatcher:

As the number and complexity of controllers continues to grow, the developer may wish to put the controllers into their own classes, lazy-loading along the way:

Finally, the developer may collect several actions into a single controller, keeping related functionality in the same class. At this point the developer should call setMethodParam() to tell the Dispatcher where to find the method to invoke on the dispatchable object.

Construction-Based Configuration

You can set all dispatchable objects, along with the object parameter name and the method parameter name, at construction time. This makes it easier to configure the Dispatcher object in a single call.

Intercessory Dispatch Methods

Sometimes your classes will have an intercessory method that picks an action to run, either on itself or on another object. This package provides an InvokeMethodTrait to invoke a method on an object using named parameters. (The InvokeMethodTrait honors protected and private scopes.)

You can then dispatch to the object as normal, and it will determine its own logical flow.