ResourceController
extends BaseResource
in package
Uses
ResponseTrait
An extendable controller to provide a RESTful API for a resource.
Table of Contents
- $codes : array<string|int, mixed>
- Allows child classes to override the status code that is used in their API.
- $forceHTTPS : int
- Should enforce HTTPS access for all methods in this controller.
- $format : string
- How to format the response data.
- $formatter : FormatterInterface
- Current Formatter instance. This is usually set by ResponseTrait::format
- $helpers : array<string|int, mixed>
- Helpers that will be automatically loaded on class instantiation.
- $logger : LoggerInterface
- Instance of logger to use.
- $model : object|null
- $modelName : string|null
- $request : RequestInterface
- Instance of the main Request object.
- $response : ResponseInterface
- Instance of the main response object.
- $validator : Validation
- Once validation has been run, will hold the Validation instance.
- create() : mixed
- Create a new resource object, from "posted" parameters
- delete() : mixed
- Delete the designated resource object from the model
- edit() : mixed
- Return the editable properties of a resource object
- 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.
- index() : mixed
- Return an array of resource objects, themselves in array format
- initController() : mixed
- Constructor.
- new() : mixed
- Return a new resource object, with default properties
- 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.
- setFormat() : void
- Set/change the expected response representation for returned objects
- setModel() : void
- Set or change the model this controller is bound to.
- setResponseFormat() : $this
- Sets the format the response should be in.
- show() : mixed
- Return the properties of a resource object
- update() : mixed
- Add or update a model resource, from "posted" properties
- cachePage() : mixed
- Provides a simple way to tie into the main CodeIgniter class and tell it how long to cache the current page for.
- forceHTTPS() : mixed
- A convenience method to use when you need to ensure that a single method is reached only via HTTPS. If it isn't, then a redirect will happen back to this method and HSTS header will be sent to have modern browsers transform requests automatically.
- format() : string|null
- Handles formatting a response. Currently makes some heavy assumptions and needs updating! :)
- loadHelpers() : mixed
- Handles "auto-loading" helper files.
- validate() : bool
- A shortcut to performing validation on input data. If validation is not successful, a $errors property will be set on this class.
Properties
$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]
$forceHTTPS
Should enforce HTTPS access for all methods in this controller.
protected
int
$forceHTTPS
= 0
Number of seconds to set HSTS header
$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
$helpers
Helpers that will be automatically loaded on class instantiation.
protected
array<string|int, mixed>
$helpers
= []
$logger
Instance of logger to use.
protected
LoggerInterface
$logger
$model
protected
object|null
$model
The model that holding this resource's data
$modelName
protected
string|null
$modelName
The model that holding this resource's data
$request
Instance of the main Request object.
protected
RequestInterface
$request
$response
Instance of the main response object.
protected
ResponseInterface
$response
$validator
Once validation has been run, will hold the Validation instance.
protected
Validation
$validator
Methods
create()
Create a new resource object, from "posted" parameters
public
create() : mixed
Return values
mixed —delete()
Delete the designated resource object from the model
public
delete([mixed $id = null ]) : mixed
Parameters
- $id : mixed = null
Return values
mixed —edit()
Return the editable properties of a resource object
public
edit([mixed $id = null ]) : mixed
Parameters
- $id : mixed = null
Return values
mixed —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 —index()
Return an array of resource objects, themselves in array format
public
index() : mixed
Return values
mixed —initController()
Constructor.
public
initController(RequestInterface $request, ResponseInterface $response, LoggerInterface $logger) : mixed
Parameters
- $request : RequestInterface
- $response : ResponseInterface
- $logger : LoggerInterface
Tags
Return values
mixed —new()
Return a new resource object, with default properties
public
new() : mixed
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 —setFormat()
Set/change the expected response representation for returned objects
public
setFormat([string $format = 'json' ]) : void
Parameters
- $format : string = 'json'
Return values
void —setModel()
Set or change the model this controller is bound to.
public
setModel([object|string|null $which = null ]) : void
Given either the name or the object, determine the other.
Parameters
- $which : object|string|null = null
Return values
void —setResponseFormat()
Sets the format the response should be in.
public
setResponseFormat([string $format = null ]) : $this
Parameters
- $format : string = null
Return values
$this —show()
Return the properties of a resource object
public
show([mixed $id = null ]) : mixed
Parameters
- $id : mixed = null
Return values
mixed —update()
Add or update a model resource, from "posted" properties
public
update([mixed $id = null ]) : mixed
Parameters
- $id : mixed = null
Return values
mixed —cachePage()
Provides a simple way to tie into the main CodeIgniter class and tell it how long to cache the current page for.
protected
cachePage(int $time) : mixed
Parameters
- $time : int
Return values
mixed —forceHTTPS()
A convenience method to use when you need to ensure that a single method is reached only via HTTPS. If it isn't, then a redirect will happen back to this method and HSTS header will be sent to have modern browsers transform requests automatically.
protected
forceHTTPS([int $duration = 31536000 ]) : mixed
Parameters
- $duration : int = 31536000
-
The number of seconds this link should be considered secure for. Only with HSTS header. Default value is 1 year.
Tags
Return values
mixed —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
Return values
string|null —loadHelpers()
Handles "auto-loading" helper files.
protected
loadHelpers() : mixed
Tags
Return values
mixed —validate()
A shortcut to performing validation on input data. If validation is not successful, a $errors property will be set on this class.
protected
validate(array<string|int, mixed>|string $rules[, array<string|int, mixed> $messages = [] ]) : bool
Parameters
- $rules : array<string|int, mixed>|string
- $messages : array<string|int, mixed> = []
-
An array of custom error messages