Download the PHP package jimbojsb/adore without Composer

Adore

Adore is an extremely lightweight implementation of the Action-Domain-Responder pattern. Currently, this code "works", but should be be considered a pre-alpha draft. I dont' envision it growing in feature complexity, but the API could change considerably based on discoveries made when actually building applications with Adore.

Background

Action-Domain-Responder is an "improvement" on the traditional idea of MVC as it relates to web applications. Paul Jones defines it in detail here: Action-Domain-Responder. The paper defines patterns and separation of concerns, but does not provide any concrete implementation details, and specifically addresses a lack of "glue" for the various concepts. Adore attempts to be that glue, providing routing, dispatching, and response handling. Additionally, Adore provides a way to wire together the action and response components. Adore is provided in it's entirety as one PHP file containing one class and two traits.

Dependencies

In an attempt to not reinvent the wheel, Adore relies on and rather than providing a bespoke implementation of these functions. This allows Adore to be extremely concise and focus on solving only the unsolved portion of the problem.

Installation & Runtime Configuration

Adore, while provided as a single PHP file, does have external dependencies. As such, the only recommended installation method is with Composer. Add the following to your

Bootstrapping

The first step to using Adore is to create a new instance of . This would normally happen in your .

Wiring Actions & Responders

Adore assumes you'll generally provide your own methods for loading Action and Responder classes, presumably PSR autoloading. Adore still needs to know how to resolve the names of these classes. This is done with factory closures. The following examples assumes but does not enforce a basic application namespace organization.

Any initial dependency injection needed for your Actions & Responders should be handled within these closures.

NOTE: The responder factory your specify will be wrapped in another closure to aid in injecting a object.

Error Handling

Adore attempts to provide some rudimentary error handling capabilities. This is done by providing an action name to dispatch if no route is matched, and additional one to dispatch in the case an exception is thrown during execution. The actual names of these actions can be any name you like, and they are resolved through the same action factory provided by you.

Routing

Adore proxies . For a full routing syntax, refer to the documentation. Routes take at a minumum, a path to match and an action name. Optionally, you may specificy which HTTP verbs routes match to, as well as additional parameters to be injection into the action.

Dispatching

Once you've configured your instance, actually dispatching it is as simple as calling:

The order of operations for dispatching a request is roughly as follows:

1. Create a new object
2. Create a new object and load it with the route definitions
3. Route the request
4. Create the appropriate action object using the supplied action factory
5. Inject params, request, responder factory onto the action
6. Call on the action
7. Dispatch the action, which should return a responder
8. Invoke the responder
9. Get the response object from the responder and send it to the client

Creating Actions & Responders

Adore attempts to have a very small footprint on your code. It provides traits instead of interfaces or abstract classes so your application inheritance tree can be completely up to you. The traits that Adore provides are mainly for dependency injection and convenience. They are not strictly required as PHP cannot type check traits, but should you choose not to use them, you would need to implement their methods and properties manually.

Actions and Responders in Adore are designed to be invokeable objects. The main entry point for execution of your code will be the method.

All methods and properties on the Adore traits are prefixed with _ to avoid any name conflicts with your code.

Actions

An action should be a simple PHP class that uses and contains an method. Additionally, you may provide an method if you need to do additional setup before dispatch. is called after the action has been fully wired. Your action is expected to return an invokeable responder.

If your method has arguments, Adore will attempt to match those named properties with keys from the request parameters such that the params are passed to your function, as a convenience.

The provides the following protected properties:

• • An array of all parameters derived from the routing process
• • An instance of that represents the current HTTP request context. For a complete listing of features, please see the documentation

The has a reference to the Responder factory, and provides a helper method that can generate wired and initialized responders from inside your action. This is the preferred method to instantiate a Responder.

Responders

A responder should be a simple PHP class that uses and contains an method. Additionally, you may provide an method if you need to do additional setup before dispatch. is called after the responder has been fully wired. Your responder will be pre-injected with a object. It should act on that object appropriately. After invoking your responder, Adore will use that response object to send a properly formed HTTP response to the client.

The provides the following protected properties:

• • An instance of . For a full listing of the functionality of the
    object, please see the documentation.

Known Issues

• Error action handling and exception catching is barely working if at all
• Relies heavily on components. Perhaps this could be improved in light of PSR-7?