CodeIgniter v4.5 API

ResponseTrait

Provides common, more readable, methods to provide consistent HTTP responses under a variety of common situations when working as an API.

Table of Contents

Properties

$stringAsHtml  : bool
$codes  : array<string, int>
Allows child classes to override the status code that is used in their API.
$format  : string|null
How to format the response data.
$formatter  : FormatterInterface|null
Current Formatter instance. This is usually set by ResponseTrait::format

Methods

fail()  : ResponseInterface
Used for generic failures that no custom methods exist for.
failForbidden()  : ResponseInterface
Used when access is always denied to this resource and no amount of trying again will help.
failNotFound()  : ResponseInterface
Used when a specified resource cannot be found.
failResourceExists()  : ResponseInterface
Use when trying to create a new resource and it already exists.
failResourceGone()  : ResponseInterface
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()  : ResponseInterface
Used when there is a server error.
failTooManyRequests()  : ResponseInterface
Used when the user has made too many requests for the resource recently.
failUnauthorized()  : ResponseInterface
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()  : ResponseInterface
Used when the data provided by the client cannot be validated.
failValidationErrors()  : ResponseInterface
Used when the data provided by the client cannot be validated on one or more fields.
format()  : string|null
Handles formatting a response. Currently, makes some heavy assumptions and needs updating! :)
respond()  : ResponseInterface
Provides a single, simple method to return an API response, formatted to match the requested format, with proper content-type and status code.
respondCreated()  : ResponseInterface
Used after successfully creating a new resource.
respondDeleted()  : ResponseInterface
Used after a resource has been successfully deleted.
respondNoContent()  : ResponseInterface
Used after a command has been successfully executed but there is no meaningful reply to send back to the client.
respondUpdated()  : ResponseInterface
Used after a resource has been successfully updated.
setResponseFormat()  : $this
Sets the format the response should be in.

Properties

$stringAsHtml

public bool $stringAsHtml

Whether to treat string data as HTML in JSON response. Setting true is only for backward compatibility.

$codes

Allows child classes to override the status code that is used in their API.

protected array<string, int> $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|null $format = 'json'

Either 'json' or 'xml'. If null is set, it will be determined through content negotiation.

Tags
phpstan-var

'html'|'json'|'xml'|null

Methods

fail()

Used for generic failures that no custom methods exist for.

protected fail(array<string|int, mixed>|string $messages[, int $status = 400 ][, string|null $code = null ][, string $customMessage = '' ]) : ResponseInterface
Parameters
$messages : array<string|int, mixed>|string
$status : int = 400

HTTP status code

$code : string|null = null

Custom, API-specific, error code

$customMessage : string = ''
Return values
ResponseInterface

failForbidden()

Used when access is always denied to this resource and no amount of trying again will help.

protected failForbidden([string $description = 'Forbidden' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Forbidden'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

failNotFound()

Used when a specified resource cannot be found.

protected failNotFound([string $description = 'Not Found' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Not Found'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

failResourceExists()

Use when trying to create a new resource and it already exists.

protected failResourceExists([string $description = 'Conflict' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Conflict'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

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.

protected failResourceGone([string $description = 'Gone' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Gone'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

failServerError()

Used when there is a server error.

protected failServerError([string $description = 'Internal Server Error' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
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
ResponseInterface

failTooManyRequests()

Used when the user has made too many requests for the resource recently.

protected failTooManyRequests([string $description = 'Too Many Requests' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Too Many Requests'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

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.

protected failUnauthorized([string $description = 'Unauthorized' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$description : string = 'Unauthorized'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

failValidationError()

Used when the data provided by the client cannot be validated.

protected failValidationError([string $description = 'Bad Request' ][, string|null $code = null ][, string $message = '' ]) : ResponseInterface

Use failValidationErrors instead

Parameters
$description : string = 'Bad Request'
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

failValidationErrors()

Used when the data provided by the client cannot be validated on one or more fields.

protected failValidationErrors(array<int, string>|string $errors[, string|null $code = null ][, string $message = '' ]) : ResponseInterface
Parameters
$errors : array<int, string>|string
$code : string|null = null
$message : string = ''
Return values
ResponseInterface

format()

Handles formatting a response. Currently, makes some heavy assumptions and needs updating! :)

protected format([array<string|int, mixed>|string|null $data = null ]) : string|null
Parameters
$data : array<string|int, mixed>|string|null = null
Return values
string|null

respond()

Provides a single, simple method to return an API response, formatted to match the requested format, with proper content-type and status code.

protected respond([array<string|int, mixed>|string|null $data = null ][, int|null $status = null ][, string $message = '' ]) : ResponseInterface
Parameters
$data : array<string|int, mixed>|string|null = null
$status : int|null = null
$message : string = ''
Return values
ResponseInterface

respondCreated()

Used after successfully creating a new resource.

protected respondCreated([array<string|int, mixed>|string|null $data = null ][, string $message = '' ]) : ResponseInterface
Parameters
$data : array<string|int, mixed>|string|null = null
$message : string = ''
Return values
ResponseInterface

respondDeleted()

Used after a resource has been successfully deleted.

protected respondDeleted([array<string|int, mixed>|string|null $data = null ][, string $message = '' ]) : ResponseInterface
Parameters
$data : array<string|int, mixed>|string|null = null
$message : string = ''
Return values
ResponseInterface

respondNoContent()

Used after a command has been successfully executed but there is no meaningful reply to send back to the client.

protected respondNoContent([string $message = 'No Content' ]) : ResponseInterface
Parameters
$message : string = 'No Content'
Return values
ResponseInterface

respondUpdated()

Used after a resource has been successfully updated.

protected respondUpdated([array<string|int, mixed>|string|null $data = null ][, string $message = '' ]) : ResponseInterface
Parameters
$data : array<string|int, mixed>|string|null = null
$message : string = ''
Return values
ResponseInterface

setResponseFormat()

Sets the format the response should be in.

protected setResponseFormat([string|null $format = null ]) : $this
Parameters
$format : string|null = null

Response format

Tags
phpstan-param

'json'|'xml' $format

Return values
$this 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results