Actions

This document assumes you’ve installed hiraeth/bootstrap or a combination of hiraeth/diactoros, hiraeth/fastroute, and hiraeth/actions. If you haven’t your mileage may vary. See the installation docs for more information.

Actions are PHP classes which handle incoming web requests. Their primary responsibility is mapping incoming requests data to your domain level services, models, repositories, etc, and then returning a result.

The only requirement of an action is that it implements the __invoke() method to perform the operations for which it is responsible. One of the simplest examples of a valid action would, therefore, be the following:

class HelloWorld
{
    public function __invoke()
    {
        return 'Hello World';
    }
}

The suggested directory for actions is local/actions. Once you’ve added your action, regenerate autoloading:

composer dump-autoload

Creating From Abstract Action

While the example above is valid, it’s not very practical because we don’t have any access to the data or tools we need to really analyze our request or generate an appropriate response. While it’s possible to add a __construct() method and get what we need injected, hiraeth/bootstrap{: .package]} provided an abstract action implementation that will cover most of the basics.

To make use of this functionality out of the box, simply make sure your action extends AbstractAction:

class MyCustomAction extends AbstractAction
{
    ...
}

The AbstractAction name is an alias, by default, to Hiraeth\Actions\AbstractAction. You can use this alias to avoid more complex namespacing, however, because the alias is only regsitered if the class does not already exist, it allows you to easily add functionality to the abstract action implementation later by simply creating your own real AbstractAction.

Accessing Request Information

Once you have extended the AbstractAction, it’s now possible to easily access the PSR-7 server request object that represents the incoming client request via $this->request:

public function __invoke()
{
    if ($this->request->getMethod() == 'POST') {
        ...
    }
}

For a full list of available methods, their arguments, and returned data types available on the request object, see the PSR-7 server request interface documentation.

Accessing Request Data

It is 100% possible to access all request data via the server request object through standard PSR-7 interfaces. Depending on the complexity of the incoming data, this may actually be necessary at time to distinguish between query parameters, post data, files, etc. However, more common is the need to have this information easily combined together and/or to get default values if it hasn’t been sent.

Hiraeth’s AbstractAction provides two methods for easily accomplishing these tasks.

Checking If Data Exists

If you need to check if a parameter has been sent (regardless of via query parameter, request body, or custom attributes), you can use the has() method:

if ($this->has('file')) {
    ...
}

Getting Data

To get the data by name, you can use the get() method in very much the same way.

$this->get('file')

In addition to being able to get data that has been sent, you can also provide a default in the event it hasn’t. This is common, for example, in the case of pagination, where you likely want to default to a value of 1 if a specific page has not been requested:

$this->get('page', 1)

Returning Data

Hiraeth does not require actions to return a particular object or type of data. Rather, it uses a system of responders which are registered in the configuration and which, in turn will be matched against your action’s return value to convert it into a proper response. That said, the Hiraeth\Actions\AbstractAction provides a number of helpers to create the most common return types.

Templates

return $this->template('@pages/index.html', $template_data)

Redirects

return $this->redirect('/people', ['page' => 1])

Responses

return $this->response(404)

You can also return some data quite directly using the built in responders. For example, if you want to send back some JSON, you can simply return an array:

return [
    'title' => 'A nice JSON response',
    'body'  => 'Nothing to see here'
]

Now that you’ve got your action in place, you’re going to need to add a route in order to map a URL to your action.

Add a Route No, I want to learn more about responders