ResponseTrait
Response trait.
Provides common, more readable, methods to provide consistent HTTP responses under a variety of common situations when working as an API.
Table of Contents
- $request : IncomingRequest
- $response : Response
- $codes : array<string|int, mixed>
- Allows child classes to override the status code that is used in their API.
- $format : string
- How to format the response data.
- $formatter : FormatterInterface
- Current Formatter instance. This is usually set by ResponseTrait::format
- fail() : mixed
- Used for generic failures that no custom methods exist for.
- failForbidden() : mixed
- Used when access is always denied to this resource and no amount of trying again will help.
- failNotFound() : mixed
- Used when a specified resource cannot be found.
- failResourceExists() : mixed
- Use when trying to create a new resource and it already exists.
- failResourceGone() : mixed
- Use when a resource was previously deleted. This is different than Not Found, because here we know the data previously existed, but is now gone, where Not Found means we simply cannot find any information about it.
- failServerError() : Response
- Used when there is a server error.
- failTooManyRequests() : mixed
- Used when the user has made too many requests for the resource recently.
- failUnauthorized() : mixed
- Used when the client is either didn't send authorization information, or had bad authorization credentials. User is encouraged to try again with the proper information.
- failValidationError() : mixed
- Used when the data provided by the client cannot be validated.
- failValidationErrors() : mixed
- Used when the data provided by the client cannot be validated on one or more fields.
- respond() : mixed
- Provides a single, simple method to return an API response, formatted to match the requested format, with proper content-type and status code.
- respondCreated() : mixed
- Used after successfully creating a new resource.
- respondDeleted() : mixed
- Used after a resource has been successfully deleted.
- respondNoContent() : mixed
- Used after a command has been successfully executed but there is no meaningful reply to send back to the client.
- respondUpdated() : mixed
- Used after a resource has been successfully updated.
- setResponseFormat() : $this
- Sets the format the response should be in.
- format() : string|null
- Handles formatting a response. Currently makes some heavy assumptions and needs updating! :)
Properties
$request
public
IncomingRequest
$request
$response
public
Response
$response
$codes
Allows child classes to override the status code that is used in their API.
protected
array<string|int, mixed>
$codes
= ['created' => 201, 'deleted' => 200, 'updated' => 200, 'no_content' => 204, 'invalid_request' => 400, 'unsupported_response_type' => 400, 'invalid_scope' => 400, 'temporarily_unavailable' => 400, 'invalid_grant' => 400, 'invalid_credentials' => 400, 'invalid_refresh' => 400, 'no_data' => 400, 'invalid_data' => 400, 'access_denied' => 401, 'unauthorized' => 401, 'invalid_client' => 401, 'forbidden' => 403, 'resource_not_found' => 404, 'not_acceptable' => 406, 'resource_exists' => 409, 'conflict' => 409, 'resource_gone' => 410, 'payload_too_large' => 413, 'unsupported_media_type' => 415, 'too_many_requests' => 429, 'server_error' => 500, 'unsupported_grant_type' => 501, 'not_implemented' => 501]
$format
How to format the response data.
protected
string
$format
= 'json'
Either 'json' or 'xml'. If blank will be determine through content negotiation.
$formatter
Current Formatter instance. This is usually set by ResponseTrait::format
protected
FormatterInterface
$formatter
Methods
fail()
Used for generic failures that no custom methods exist for.
public
fail(string|array<string|int, mixed> $messages[, int $status = 400 ][, string|null $code = null ][, string $customMessage = '' ]) : mixed
Parameters
- $messages : string|array<string|int, mixed>
- $status : int = 400
-
HTTP status code
- $code : string|null = null
-
Custom, API-specific, error code
- $customMessage : string = ''
Return values
mixed —failForbidden()
Used when access is always denied to this resource and no amount of trying again will help.
public
failForbidden([string $description = 'Forbidden' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Forbidden'
- $code : string = null
- $message : string = ''
Return values
mixed —failNotFound()
Used when a specified resource cannot be found.
public
failNotFound([string $description = 'Not Found' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Not Found'
- $code : string = null
- $message : string = ''
Return values
mixed —failResourceExists()
Use when trying to create a new resource and it already exists.
public
failResourceExists([string $description = 'Conflict' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Conflict'
- $code : string = null
- $message : string = ''
Return values
mixed —failResourceGone()
Use when a resource was previously deleted. This is different than Not Found, because here we know the data previously existed, but is now gone, where Not Found means we simply cannot find any information about it.
public
failResourceGone([string $description = 'Gone' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Gone'
- $code : string = null
- $message : string = ''
Return values
mixed —failServerError()
Used when there is a server error.
public
failServerError([string $description = 'Internal Server Error' ][, string|null $code = null ][, string $message = '' ]) : Response
Parameters
- $description : string = 'Internal Server Error'
-
The error message to show the user.
- $code : string|null = null
-
A custom, API-specific, error code.
- $message : string = ''
-
A custom "reason" message to return.
Return values
Response —The value of the Response's send() method.
failTooManyRequests()
Used when the user has made too many requests for the resource recently.
public
failTooManyRequests([string $description = 'Too Many Requests' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Too Many Requests'
- $code : string = null
- $message : string = ''
Return values
mixed —failUnauthorized()
Used when the client is either didn't send authorization information, or had bad authorization credentials. User is encouraged to try again with the proper information.
public
failUnauthorized([string $description = 'Unauthorized' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Unauthorized'
- $code : string = null
- $message : string = ''
Return values
mixed —failValidationError()
Used when the data provided by the client cannot be validated.
public
failValidationError([string $description = 'Bad Request' ][, string $code = null ][, string $message = '' ]) : mixed
Parameters
- $description : string = 'Bad Request'
- $code : string = null
- $message : string = ''
Tags
Return values
mixed —failValidationErrors()
Used when the data provided by the client cannot be validated on one or more fields.
public
failValidationErrors(string|array<string|int, string> $errors[, string|null $code = null ][, string $message = '' ]) : mixed
Parameters
- $errors : string|array<string|int, string>
- $code : string|null = null
- $message : string = ''
Return values
mixed —respond()
Provides a single, simple method to return an API response, formatted to match the requested format, with proper content-type and status code.
public
respond([array<string|int, mixed>|string|null $data = null ][, int $status = null ][, string $message = '' ]) : mixed
Parameters
- $data : array<string|int, mixed>|string|null = null
- $status : int = null
- $message : string = ''
Return values
mixed —respondCreated()
Used after successfully creating a new resource.
public
respondCreated([mixed $data = null ][, string $message = '' ]) : mixed
Parameters
- $data : mixed = null
-
Data.
- $message : string = ''
-
Message.
Return values
mixed —respondDeleted()
Used after a resource has been successfully deleted.
public
respondDeleted([mixed $data = null ][, string $message = '' ]) : mixed
Parameters
- $data : mixed = null
-
Data.
- $message : string = ''
-
Message.
Return values
mixed —respondNoContent()
Used after a command has been successfully executed but there is no meaningful reply to send back to the client.
public
respondNoContent([string $message = 'No Content' ]) : mixed
Parameters
- $message : string = 'No Content'
-
Message.
Return values
mixed —respondUpdated()
Used after a resource has been successfully updated.
public
respondUpdated([mixed $data = null ][, string $message = '' ]) : mixed
Parameters
- $data : mixed = null
-
Data.
- $message : string = ''
-
Message.
Return values
mixed —setResponseFormat()
Sets the format the response should be in.
public
setResponseFormat([string $format = null ]) : $this
Parameters
- $format : string = null
Return values
$this —format()
Handles formatting a response. Currently makes some heavy assumptions and needs updating! :)
protected
format([string|array<string|int, mixed>|null $data = null ]) : string|null
Parameters
- $data : string|array<string|int, mixed>|null = null