class RestController extends ActionController (View source)

An action controller for RESTful web services

Properties

protected UriBuilder $uriBuilder from  AbstractController
protected ValidatorResolver $validatorResolver from  AbstractController
protected ActionRequest $request

The current request

protected ActionResponse $response

The response which will be returned by this action controller

protected Arguments $arguments

Arguments passed to the controller

from  AbstractController
protected ControllerContext $controllerContext from  AbstractController
protected PersistenceManagerInterface $persistenceManager from  AbstractController
protected array $supportedMediaTypes

A list of IANA media types which are supported by this controller

from  AbstractController
protected string $negotiatedMediaType

The media type that was negotiated by this controller

from  AbstractController
protected ObjectManagerInterface $objectManager from  ActionController
protected ReflectionService $reflectionService from  ActionController
protected MvcPropertyMappingConfigurationService $mvcPropertyMappingConfigurationService from  ActionController
protected ViewConfigurationManager $viewConfigurationManager from  ActionController
protected ViewInterface $view

The current view, as resolved by resolveView()

from  ActionController
protected string $viewObjectNamePattern

Pattern after which the view object name is built if no format-specific view could be resolved.

from  ActionController
protected array $viewFormatToObjectNameMap

A list of formats and object names of the views which should render them.

from  ActionController
protected string $defaultViewObjectName

The default view object to use if none of the resolved views can render a response for the current request.

from  ActionController
protected string $defaultViewImplementation from  ActionController
protected string $actionMethodName

Name of the action method

from  ActionController
protected string $errorMethodName

Name of the special error action method which is called in case of errors

from  ActionController
protected array $settings from  ActionController
protected LoggerInterface $logger from  ActionController
protected bool $enableDynamicTypeValidation

Feature flag to enable the potentially breaking support of validation for dynamic types specified with __type argument or in the PropertyMapperConfiguration.

from  ActionController
protected string $resourceArgumentName

Name of the action method argument which acts as the resource for the RESTful controller. If an argument with the specified name is passed to the controller, the show, update and delete actions can be triggered automatically.

Methods

initializeController(ActionRequest $request, ActionResponse $response)

Initializes the controller

getControllerContext()

Returns this controller's context.

void
addFlashMessage(string $messageBody, string $messageTitle = '', string $severity = Error\Message::SEVERITY_OK, array $messageArguments = [], int $messageCode = null)

Creates a Message object and adds it to the FlashMessageContainer.

never
forward(string $actionName, string $controllerName = null, string $packageKey = null, array $arguments = [])

Forwards the request to another action and / or controller.

never
forwardToRequest(ActionRequest $request)

Forwards the request to another action and / or controller.

never
redirect(string $actionName, string|null $controllerName = null, string|null $packageKey = null, array $arguments = [], int $delay = 0, int $statusCode = 303, string $format = null)

Redirects the request to another action and / or controller.

never
redirectToRequest(ActionRequest $request, int $delay = 0, int $statusCode = 303)

Redirects the request to another action and / or controller.

never
redirectToUri(UriInterface $uri, int $delay = 0, int $statusCode = 303)

Redirects to another URI

never
throwStatus(int $statusCode, string $statusMessage = null, string $content = null)

Sends the specified HTTP status immediately.

void
mapRequestArgumentsToControllerArguments(ActionRequest $request, Arguments $arguments)

Maps arguments delivered by the request object to the local controller arguments.

void
injectSettings(array $settings)

No description

void
injectLogger(LoggerInterface $logger)

Injects the (system) logger based on PSR-3.

void
injectThrowableStorage(ThrowableStorageInterface $throwableStorage)

Injects the throwable storage.

ResponseInterface
processRequest(ActionRequest $request)

Handles a request. The result output is returned by altering the given response.

string
resolveActionMethodName(ActionRequest $request)

Determines the action method and assures that the method exists.

void
initializeActionMethodArguments(Arguments $arguments)

Implementation of the arguments initialization in the action controller: Automatically registers arguments of the current action

static array
getActionMethodParameters(ObjectManagerInterface $objectManager)

Returns a map of action method names and their parameters.

array
getInformationNeededForInitializeActionMethodValidators()

This is a helper method purely used to make initializeActionMethodValidators() testable without mocking static methods.

void
initializeActionMethodValidators(Arguments $arguments)

Adds the needed validators to the Arguments:

static array
getActionValidationGroups(ObjectManagerInterface $objectManager)

Returns a map of action method names and their validation groups.

static array
getActionValidateAnnotationData(ObjectManagerInterface $objectManager)

Returns a map of action method names and their validation parameters.

void
initializeAction()

Initializes the controller before invoking an action method.

ResponseInterface
callActionMethod(ActionRequest $request, Arguments $arguments, ResponseInterface $httpResponse)

Calls the specified action method and passes the arguments.

static array
static array
getPublicActionMethods(ObjectManagerInterface $objectManager)

No description

resolveView(ActionRequest $request)

Prepares a view for the current action and stores it in $this->view.

emitViewResolved(ViewInterface $view)

Emit that the view is resolved. The passed ViewInterface reference, gives the possibility to add variables to the view, before passing it on to further rendering

mixed
resolveViewObjectName(ActionRequest $request)

Determines the fully qualified view object name.

void
initializeView(ViewInterface $view)

Initializes the view before invoking an action method.

string
errorAction()

A special action which is called if the originally intended action could not be called, for example if the arguments were not valid.

void
handleTargetNotFoundError()

Checks if the arguments validation result contain errors of type TargetNotFoundError and throws a TargetNotFoundException if that's the case for a top-level object.

void
addErrorFlashMessage()

If an error occurred during this request, this adds a flash message describing the error to the flash message container.

void
forwardToReferringRequest()

If information on the request before the current request was sent, this method forwards back to the originating request. This effectively ends processing of the current request, so do not call this method before you have finished the necessary business logic!

string
getFlattenedValidationErrorMessage()

Returns a string containing all validation errors separated by PHP_EOL.

Error|false
getErrorFlashMessage()

A template method for displaying custom error flash messages, or to display no flash message at all on errors. Override this to customize the flash message in your action controller.

ResponseInterface
renderView(ResponseInterface $httpResponse)

Renders the view and returns the psr response.

void
initializeCreateAction()

Allow creation of resources in createAction()

void
initializeUpdateAction()

Allow modification of resources in updateAction()

Details

protected initializeController(ActionRequest $request, ActionResponse $response)

Initializes the controller

This method should be called by the concrete processRequest() method.

Parameters

ActionRequest $request
ActionResponse $response

ControllerContext getControllerContext()

Returns this controller's context.

Note that the context is only available after processRequest() has been called.

Return Value

ControllerContext

The current controller context

void addFlashMessage(string $messageBody, string $messageTitle = '', string $severity = Error\Message::SEVERITY_OK, array $messageArguments = [], int $messageCode = null)

Creates a Message object and adds it to the FlashMessageContainer.

This method should be used to add FlashMessages rather than interacting with the container directly.

Parameters

string $messageBody

text of the FlashMessage

string $messageTitle

optional header of the FlashMessage

string $severity

severity of the FlashMessage (one of the Message::SEVERITY_* constants)

array $messageArguments

arguments to be passed to the FlashMessage

int $messageCode

Return Value

void

Exceptions

InvalidArgumentException

See also

Message

protected never forward(string $actionName, string $controllerName = null, string $packageKey = null, array $arguments = [])

Forwards the request to another action and / or controller.

Request is directly transferred to the other action / controller

Parameters

string $actionName

Name of the action to forward to

string $controllerName

Unqualified object name of the controller to forward to. If not specified, the current controller is used.

string $packageKey

Key of the package containing the controller to forward to. May also contain the sub package, concatenated with backslash (Vendor.Foo\Bar\Baz). If not specified, the current package is assumed.

array $arguments

Arguments to pass to the target action

Return Value

never

Exceptions

ForwardException
InvalidActionNameException
InvalidArgumentNameException
InvalidArgumentTypeException
InvalidControllerNameException
UnknownObjectException

See also

redirect()

protected never forwardToRequest(ActionRequest $request)

Forwards the request to another action and / or controller.

Request is directly transfered to the other action / controller

Parameters

ActionRequest $request

The request to redirect to

Return Value

never

Exceptions

ForwardException

See also

redirectToRequest()

protected never redirect(string $actionName, string|null $controllerName = null, string|null $packageKey = null, array $arguments = [], int $delay = 0, int $statusCode = 303, string $format = null)

Redirects the request to another action and / or controller.

Redirect will be sent to the client which then performs another request to the new URI.

NOTE: This method only supports web requests and will throw an exception if used with other request types.

Parameters

string $actionName

Name of the action to forward to

string|null $controllerName

Unqualified object name of the controller to forward to. If not specified, the current controller is used.

string|null $packageKey

Key of the package containing the controller to forward to. If not specified, the current package is assumed.

array $arguments

Array of arguments for the target action

int $delay

(optional) The delay in seconds. Default is no delay.

int $statusCode

(optional) The HTTP status code for the redirect. Default is "303 See Other"

string $format

The format to use for the redirect URI

Return Value

never

Exceptions

StopActionException
Exception
MissingActionNameException

See also

forward()

protected never redirectToRequest(ActionRequest $request, int $delay = 0, int $statusCode = 303)

Redirects the request to another action and / or controller.

Redirect will be sent to the client which then performs another request to the new URI.

Parameters

ActionRequest $request

The request to redirect to

int $delay

(optional) The delay in seconds. Default is no delay.

int $statusCode

(optional) The HTTP status code for the redirect. Default is "303 See Other"

Return Value

never

Exceptions

MissingActionNameException
StopActionException
Exception

See also

forwardToRequest()

protected never redirectToUri(UriInterface $uri, int $delay = 0, int $statusCode = 303)

Redirects to another URI

Parameters

UriInterface $uri

Either a string or a psr uri

int $delay

(optional) The delay in seconds. Default is no delay.

int $statusCode

(optional) The HTTP status code for the redirect. Default is "303 See Other"

Return Value

never

Exceptions

StopActionException

protected never throwStatus(int $statusCode, string $statusMessage = null, string $content = null)

Sends the specified HTTP status immediately.

NOTE: This method only supports web requests and will throw an exception if used with other request types.

Parameters

int $statusCode

The HTTP status code

string $statusMessage

A custom HTTP status message

string $content

Body content which further explains the status

Return Value

never

Exceptions

StopActionException

protected void mapRequestArgumentsToControllerArguments(ActionRequest $request, Arguments $arguments)

Maps arguments delivered by the request object to the local controller arguments.

Parameters

ActionRequest $request
Arguments $arguments

Return Value

void

Exceptions

RequiredArgumentMissingException
NoSuchArgumentException
Exception
Exception

void injectSettings(array $settings)

No description

Parameters

array $settings

Return Value

void

void injectLogger(LoggerInterface $logger)

Injects the (system) logger based on PSR-3.

Parameters

LoggerInterface $logger

Return Value

void

void injectThrowableStorage(ThrowableStorageInterface $throwableStorage)

Injects the throwable storage.

Parameters

ThrowableStorageInterface $throwableStorage

Return Value

void

ResponseInterface processRequest(ActionRequest $request)

Handles a request. The result output is returned by altering the given response.

Parameters

ActionRequest $request

The dispatched action request

Return Value

ResponseInterface

The resulting created response

Exceptions

InvalidActionVisibilityException
InvalidArgumentTypeException
NoSuchActionException
StopActionException
ForwardException
ViewNotFoundException
NoSuchArgumentException
Exception
Exception

protected string resolveActionMethodName(ActionRequest $request)

Determines the action method and assures that the method exists.

Parameters

ActionRequest $request

Return Value

string

Method name of the current action

Exceptions

NoSuchActionException
StopActionException
InvalidActionNameException
InvalidActionVisibilityException

protected void initializeActionMethodArguments(Arguments $arguments)

Implementation of the arguments initialization in the action controller: Automatically registers arguments of the current action

Don't override this method - use initializeAction() instead.

Parameters

Arguments $arguments

Return Value

void

Exceptions

InvalidArgumentTypeException

See also

initializeArguments()

static array getActionMethodParameters(ObjectManagerInterface $objectManager)

Returns a map of action method names and their parameters.

Parameters

ObjectManagerInterface $objectManager

Return Value

array

Array of method parameters by action name

protected array getInformationNeededForInitializeActionMethodValidators()

This is a helper method purely used to make initializeActionMethodValidators() testable without mocking static methods.

Return Value

array

protected void initializeActionMethodValidators(Arguments $arguments)

Adds the needed validators to the Arguments:

  • Validators checking the data type from the "@param" annotation
  • Custom validators specified with validate annotations.
  • Model-based validators (validate annotations in the model)
  • Custom model validator classes

Parameters

Arguments $arguments

Return Value

void

static array getActionValidationGroups(ObjectManagerInterface $objectManager)

Returns a map of action method names and their validation groups.

Parameters

ObjectManagerInterface $objectManager

Return Value

array

Array of validation groups by action method name

static array getActionValidateAnnotationData(ObjectManagerInterface $objectManager)

Returns a map of action method names and their validation parameters.

Parameters

ObjectManagerInterface $objectManager

Return Value

array

Array of validate annotation parameters by action method name

protected void initializeAction()

Initializes the controller before invoking an action method.

Override this method to solve tasks which all actions have in common.

Return Value

void

protected ResponseInterface callActionMethod(ActionRequest $request, Arguments $arguments, ResponseInterface $httpResponse)

Calls the specified action method and passes the arguments.

If the action returns a string, it is appended to the content in the response object. If the action doesn't return anything and a valid view exists, the view is rendered automatically.

Parameters

ActionRequest $request
Arguments $arguments
ResponseInterface $httpResponse

The most likely empty response, previously available as $this->response

Return Value

ResponseInterface

static array getActionIgnoredValidationArguments(ObjectManagerInterface $objectManager)

No description

Parameters

ObjectManagerInterface $objectManager

Return Value

array

Array of argument names as key by action method name

static array getPublicActionMethods(ObjectManagerInterface $objectManager)

No description

Parameters

ObjectManagerInterface $objectManager

Return Value

array

Array of all public action method names, indexed by method name

protected ViewInterface resolveView(ActionRequest $request)

Prepares a view for the current action and stores it in $this->view.

By default, this method tries to locate a view with a name matching the current action.

Parameters

ActionRequest $request

Return Value

ViewInterface

the resolved view

Exceptions

ViewNotFoundException

protected emitViewResolved(ViewInterface $view)

Emit that the view is resolved. The passed ViewInterface reference, gives the possibility to add variables to the view, before passing it on to further rendering

Parameters

ViewInterface $view

protected mixed resolveViewObjectName(ActionRequest $request)

Determines the fully qualified view object name.

Parameters

ActionRequest $request

Return Value

mixed

The fully qualified view object name or false if no matching view could be found.

protected void initializeView(ViewInterface $view)

Initializes the view before invoking an action method.

Override this method to solve assign variables common for all actions or prepare the view in another way before the action is called.

Parameters

ViewInterface $view

The view to be initialized

Return Value

void

protected string errorAction()

A special action which is called if the originally intended action could not be called, for example if the arguments were not valid.

The default implementation checks for TargetNotFoundErrors, sets a flash message, request errors and forwards back to the originating action. This is suitable for most actions dealing with form input.

Return Value

string

protected void handleTargetNotFoundError()

Checks if the arguments validation result contain errors of type TargetNotFoundError and throws a TargetNotFoundException if that's the case for a top-level object.

You can override this method (or the errorAction()) if you need a different behavior

Return Value

void

Exceptions

TargetNotFoundException

protected void addErrorFlashMessage()

If an error occurred during this request, this adds a flash message describing the error to the flash message container.

Return Value

void

protected void forwardToReferringRequest()

If information on the request before the current request was sent, this method forwards back to the originating request. This effectively ends processing of the current request, so do not call this method before you have finished the necessary business logic!

Return Value

void

Exceptions

ForwardException

protected string getFlattenedValidationErrorMessage()

Returns a string containing all validation errors separated by PHP_EOL.

Return Value

string

protected Error|false getErrorFlashMessage()

A template method for displaying custom error flash messages, or to display no flash message at all on errors. Override this to customize the flash message in your action controller.

Return Value

Error|false

The flash message or false if no flash message should be set

protected ResponseInterface renderView(ResponseInterface $httpResponse)

Renders the view and returns the psr response.

If a stream is returned it will be applied (to the most likely empty response) which was previously available as $this->response.

Parameters

ResponseInterface $httpResponse

Return Value

ResponseInterface

protected void initializeCreateAction()

Allow creation of resources in createAction()

Return Value

void

protected void initializeUpdateAction()

Allow modification of resources in updateAction()

Return Value

void