# Action

The Action component is in charge of providing a context for executing any given instruction.

# Defining an Action

Action is the basic building block for incoming actions to the application. Code below defines class SomeAction by extending Action.

use Chevere\Components\Action\Action;

final class SomeAction extends Action
{
    // ...
}

# Description

The getDescription method is used to define the action description.

public function getDescription(): string
{
    return 'It says "Hello, <name>!"';
}

# Parameters

The getParameters method is used to define the action Parameters, which later will be used to provide matching run method arguments.

use Chevere\Interfaces\Parameter\ParametersInterface;
use Chevere\Components\Parameter\Parameters;
use Chevere\Components\Parameter\IntegerParameter;

public function getParameters(): ParametersInterface
{
    return (new Parameters)
        ->withAddedRequired(
            id: (new IntegerParameter)
                    ->withDescription('The user id.')
        );
}

# Response Data

The getResponseDataParameters method is used to define the response data parameters, which later will be checked against the response data provided in the run method.

use Chevere\Interfaces\Parameter\ParametersInterface;
use Chevere\Components\Parameter\Parameters;
use Chevere\Components\Parameter\IntegerParameter;

public function getResponseDataParameters(): ParametersInterface
{
    return (new Parameters)
        ->withAddedRequired(
            email: new StringParameter
        );
}

# Run

The run method is used to define the actual action instruction that will carried. It pass a variadic number of arguments which are checked against the defined action parameters.

It must return a Response object.

use Chevere\Components\Parameter\IntegerParameter;
use Chevere\Components\Parameter\Parameters;
use Chevere\Components\Response\Response;
use Chevere\Interfaces\Parameter\ArgumentsInterface;
use Chevere\Interfaces\Parameter\ParametersInterface;
use Chevere\Interfaces\Response\ResponseInterface;

public function run(ArgumentsInterface $arguments): ResponseInterface
{
    $id = $arguments->getInteger(name: 'id');
    return $this->getResponse(
        email: (new User($id))->email
    );
}

Passed named arguments will be typed against the defined action parameters.

# Controller

Controller is a special type of action in charge of handling user-triggered instructions and to drive it towards application instructions. It extends on top of Action, adding an extra layer of context.

Learn by Example

Check the Controller example (opens new window) to learn directly playing with code.

# Defining a Controller

Code below defines class SomeController by extending the base Controller.

use Chevere\Components\Actions\Controller;

final class SomeController extends Controller
{
    // ...
}

# Controller Parameters

Controller defines parameters just like an Action, but all parameters must be of type StringParameter. As Controller is designed to be used for handling user-triggered instructions like HTTP endpoints, commands and any other possible layer, the input arguments are of type string.

# Controller Context Parameters

Controller adds context to provide runtime variables that aren't directly taken from the user input. The getContextParameters method is used to define the action parameters, which later will be checked against arguments in the run method.

It must return a Parameters object.

use Chevere\Interfaces\Parameter\ParametersInterface;
use Chevere\Components\Parameter\Parameters;
use Chevere\Components\Parameter\IntegerParameter;

public function getContextParameters(): ParametersInterface
{
    return (new Parameters)
        ->withAddedRequired(
            min: (new IntegerParameter)->withDefault(value: 10)
        );
}

On runtime, the context will be added by running the withContextArguments method:

use Chevere\Interfaces\Parameter\ParametersInterface;
use Chevere\Components\Parameter\Parameters;
use Chevere\Components\Parameter\IntegerParameter;

$controller = (new SomeController)
    ->withContextArguments(min: 200);