CodeIgniter v4.5 API

ResourceController extends BaseResource
in package

Application

uses ResponseTrait

An extendable controller to provide a RESTful API for a resource.

Properties

$codes : array<string, int>: 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|null: How to format the response data.
$formatter : FormatterInterface|null: Current Formatter instance. This is usually set by ResponseTrait::format
$helpers : array<int, string>: Helpers that will be automatically loaded on class instantiation.
$logger : LoggerInterface: Instance of logger to use.
$model : object|null
$modelName : string|null
$request : CLIRequest|IncomingRequest: Instance of the main Request object.
$response : ResponseInterface: Instance of the main response object.
$validator : ValidationInterface|null: Once validation has been run, will hold the Validation instance.

Methods

create() : ResponseInterface|string|void: Create a new resource object, from "posted" parameters
delete() : ResponseInterface|string|void: Delete the designated resource object from the model
edit() : ResponseInterface|string|void: Return the editable properties of a resource object
index() : ResponseInterface|string|void: Return an array of resource objects, themselves in array format
initController() : void: Constructor.
new() : ResponseInterface|string|void: Return a new resource object, with default properties
setFormat() : void: Set/change the expected response representation for returned objects
setModel() : void: Set or change the model this controller is bound to.
show() : ResponseInterface|string|void: Return the properties of a resource object
update() : ResponseInterface|string|void: Add or update a model resource, from "posted" properties
cachePage() : void: How long to cache the current page for.
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.
forceHTTPS() : void: 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! :)
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.
validate() : bool: A shortcut to performing validation on Request data.
validateData() : bool: A shortcut to performing validation on any input data.
setValidator() : void

$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]

$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|null
    $format
     = 'json'

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

$formatter

Current Formatter instance. This is usually set by ResponseTrait::format


    protected
        FormatterInterface|null
    $formatter

$helpers

Helpers that will be automatically loaded on class instantiation.


    protected
        array<int, string>
    $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
        CLIRequest|IncomingRequest
    $request

$response

Instance of the main response object.


    protected
        ResponseInterface
    $response

$validator

Once validation has been run, will hold the Validation instance.


    protected
        ValidationInterface|null
    $validator

create()

Create a new resource object, from "posted" parameters


    public
                    create() : ResponseInterface|string|void

Return values

ResponseInterface|string|void

delete()

Delete the designated resource object from the model


    public
                    delete([int|string|null $id = null ]) : ResponseInterface|string|void

Parameters

$id : int|string|null = null

Return values

ResponseInterface|string|void

edit()

Return the editable properties of a resource object


    public
                    edit([int|string|null $id = null ]) : ResponseInterface|string|void

Parameters

$id : int|string|null = null

Return values

ResponseInterface|string|void

index()

Return an array of resource objects, themselves in array format


    public
                    index() : ResponseInterface|string|void

Return values

ResponseInterface|string|void

initController()

Constructor.


    public
                    initController(RequestInterface $request, ResponseInterface $response, LoggerInterface $logger) : void

Parameters

$request : RequestInterface
$response : ResponseInterface
$logger : LoggerInterface

new()

Return a new resource object, with default properties


    public
                    new() : ResponseInterface|string|void

Return values

ResponseInterface|string|void

setFormat()

Set/change the expected response representation for returned objects


    public
                    setFormat([string $format = 'json' ]) : void

Parameters

$format : string = 'json': Response format

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

show()

Return the properties of a resource object


    public
                    show([int|string|null $id = null ]) : ResponseInterface|string|void

Parameters

$id : int|string|null = null

Return values

ResponseInterface|string|void

update()

Add or update a model resource, from "posted" properties


    public
                    update([int|string|null $id = null ]) : ResponseInterface|string|void

Parameters

$id : int|string|null = null

Return values

ResponseInterface|string|void

cachePage()

How long to cache the current page for.


    protected
                    cachePage(int $time) : void

Parameters

$time : int

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

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 ]) : void

Parameters

$duration : int = 31536000: The number of seconds this link should be considered secure for. Only with HSTS header. Default value is 1 year.

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

Return values

$this

validate()

A shortcut to performing validation on Request data.


    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

Return values

bool

validateData()

A shortcut to performing validation on any input data.


    protected
                    validateData(array<string|int, mixed> $data, array<string|int, mixed>|string $rules[, array<string|int, mixed> $messages = [] ][, string|null $dbGroup = null ]) : bool

Parameters

$data : array<string|int, mixed>: The data to validate
$rules : array<string|int, mixed>|string
$messages : array<string|int, mixed> = []: An array of custom error messages
$dbGroup : string|null = null: The database group to use

Return values

bool

setValidator()


    private
                    setValidator(array<string|int, mixed>|string $rules, array<string|int, mixed> $messages) : void

Parameters

$rules : array<string|int, mixed>|string
$messages : array<string|int, mixed>

ResourceController extends BaseResource in package Application uses ResponseTrait

Tags

Table of Contents

Properties

Methods

Properties

$codes

$forceHTTPS

$format

Tags

$formatter

$helpers

$logger

$model

$modelName

$request

$response

$validator

Methods

create()

Return values

delete()

Parameters

Return values

edit()

Parameters

Return values

index()

Return values

initController()

Parameters

new()

Return values

setFormat()

Parameters

Tags

setModel()

Parameters

show()

Parameters

Return values

update()

Parameters

Return values

cachePage()

Parameters

Tags

fail()

Parameters

Return values

failForbidden()

Parameters

Return values

failNotFound()

Parameters

Return values

failResourceExists()

Parameters

Return values

failResourceGone()

Parameters

Return values

failServerError()

Parameters

Return values

failTooManyRequests()

Parameters

Return values

failUnauthorized()

Parameters

Return values

failValidationError()

Parameters

Return values

failValidationErrors()

Parameters

Return values

forceHTTPS()

Parameters

Tags

ResourceController extends BaseResource
in package

Application

uses ResponseTrait