This is an old revision of the document!

ApiResponse

Layer: Core · Source: lib/core/ApiResponse.php:24 (lines 24–620)

class ApiResponse

Inheritance

No parent, interface or trait. This is a root type.

Constants (18)

Visibility	Name	Value	Line
`-`	`HTTP_OK`	`200;`	29
`-`	`HTTP_CREATED`	`201;`	30
`-`	`HTTP_NO_CONTENT`	`204;`	31
`-`	`HTTP_BAD_REQUEST`	`400;`	32
`-`	`HTTP_UNAUTHORIZED`	`401;`	33
`-`	`HTTP_FORBIDDEN`	`403;`	34
`-`	`HTTP_NOT_FOUND`	`404;`	35
`-`	`HTTP_METHOD_NOT_ALLOWED`	`405;`	36
`-`	`HTTP_NOT_ACCEPTABLE`	`406;`	37
`-`	`HTTP_UNSUPPORTED_MEDIA_TYPE`	`415;`	38
`-`	`HTTP_CONFLICT`	`409;`	39
`-`	`HTTP_UNPROCESSABLE_ENTITY`	`422;`	40
`-`	`HTTP_TOO_MANY_REQUESTS`	`429;`	41
`-`	`HTTP_INTERNAL_SERVER_ERROR`	`500;`	42
`-`	`HTTP_SERVICE_UNAVAILABLE`	`503;`	43
`-`	`RATE_LIMIT`	`60;`	48
`-`	`RATE_WINDOW`	`60;`	49
`-`	`CACHE_TTL`	`300;`	54

Properties (1)

Visibility	Type	Name	Default	Line
`private static`	`static`	`$pendingHeaders`	`[];`	66

Methods (29)

Visibility	Method	Summary	Line
public static	`initRateLimit()`	Initialize rate limiting (fallback when RateLimiter class not loaded)	74
public static	`setRateLimitHeaders()`	Set rate limit headers from RateLimiter result or fallback	86
public static	`withHeader()`	Queue a header to be sent with the response	109
public static	`withEtag()`	Set ETag header for cache validation	121
public static	`withLastModified()`	Set Last-Modified header for cache validation	136
public static	`withLocation()`	Set Location header for redirect or created resource	150
public static	`checkEtagMatch()`	Check If-None-Match header against provided ETag	162
public static	`checkModifiedSince()`	Check If-Modified-Since header against provided timestamp	193
public static	`notModified()`	Send a 304 Not Modified response	215
private static	`setCacheHeaders()`	Set cache headers based on HTTP method	231
public static	`success()`	Send a successful JSON response	264
public static	`created()`	Send a created response (201)	289
public static	`noContent()`	Send a no content response (204)	314
public static	`error()`	Send an error response	328
public static	`badRequest()`	Send a 400 Bad Request error	353
public static	`unauthorized()`	Send a 401 Unauthorized error	364
public static	`forbidden()`	Send a 403 Forbidden error	375
public static	`notAcceptable()`	Send a 406 Not Acceptable error	387
public static	`unsupportedMediaType()`	Send a 415 Unsupported Media Type error	399
public static	`conflict()`	Send a 409 Conflict error	410
public static	`notFound()`	Send a 404 Not Found error	421
public static	`unprocessableEntity()`	Send a 422 Unprocessable Entity error	433
public static	`tooManyRequests()`	Send a 429 Too Many Requests error	445
public static	`methodNotAllowed()`	Send a method not allowed error	458
public static	`paginated()`	Send a paginated response with HATEOAS links	475
public static	`validateAccept()`	Validate Accept header against supported types	507
private static	`send()`	Send raw JSON response	544
private static	`getErrorCode()`	Get error code from status code	586
public static	`setCorsHeaders()`	Set CORS headers for cross-origin requests	612

initRateLimit()

public static function initRateLimit($limit = self::RATE_LIMIT, $window = self::RATE_WINDOW)

lines 74–79 (6)

Initialize rate limiting (fallback when RateLimiter class not loaded)

Parameter	Type	Default	Description
`$limit`	`(untyped)`	`self::RATE_LIMIT`	none
`$window`	`(untyped)`	`self::RATE_WINDOW`	none

Returns: (none declared)

setRateLimitHeaders()

public static function setRateLimitHeaders($rateResult = null)

lines 86–101 (16)

Set rate limit headers from RateLimiter result or fallback

Parameter	Type	Default	Description
`$rateResult`	`(untyped)`	`null`	RateLimiter check result

Returns: (none declared)

withHeader()

public static function withHeader($header)

lines 109–112 (4)

Queue a header to be sent with the response

Parameter	Type	Default	Description
`$header`	`(untyped)`	required	none

Returns: (none declared) — void

withEtag()

public static function withEtag($etag, $weak = false)

lines 121–128 (8)

Set ETag header for cache validation

Parameter	Type	Default	Description
`$etag`	`(untyped)`	required	ETag value (will be quoted automatically)
`$weak`	`(untyped)`	`false`	Whether this is a weak validator

Returns: (none declared) — void

withLastModified()

public static function withLastModified($timestamp)

lines 136–142 (7)

Set Last-Modified header for cache validation

Parameter	Type	Default	Description
`$timestamp`	`(untyped)`	required	Unix timestamp or HTTP date string

Returns: (none declared) — void

withLocation()

public static function withLocation($url)

lines 150–153 (4)

Set Location header for redirect or created resource

Parameter	Type	Default	Description
`$url`	`(untyped)`	required	none

Returns: (none declared) — void

checkEtagMatch()

public static function checkEtagMatch($etag)

lines 162–184 (23)

Check If-None-Match header against provided ETag

Returns true if client should use cached version (send 304)

Parameter	Type	Default	Description
`$etag`	`(untyped)`	required	Current ETag for the resource

Returns: (none declared) — bool True if 304 should be sent

checkModifiedSince()

public static function checkModifiedSince($timestamp)

lines 193–208 (16)

Check If-Modified-Since header against provided timestamp

Returns true if client should use cached version (send 304)

Parameter	Type	Default	Description
`$timestamp`	`(untyped)`	required	Unix timestamp or HTTP date string

Returns: (none declared) — bool True if 304 should be sent

notModified()

public static function notModified()

lines 215–222 (8)

Send a 304 Not Modified response

Takes no parameters.

Returns: (none declared) — void

setCacheHeaders()

private static function setCacheHeaders($statusCode, $ttl = self::CACHE_TTL)

lines 231–252 (22)

Set cache headers based on HTTP method

Parameter	Type	Default	Description
`$statusCode`	`(untyped)`	required	none
`$ttl`	`(untyped)`	`self::CACHE_TTL`	Cache TTL in seconds (default 300)

Returns: (none declared) — void

success()

public static function success($data = null, $statusCode = self::HTTP_OK, $message = null, $links = [], $ttl = self::CACHE_TTL)

lines 264–278 (15)

Send a successful JSON response

Parameter	Type	Default	Description
`$data`	`(untyped)`	`null`	The data to be encoded as JSON
`$statusCode`	`(untyped)`	`self::HTTP_OK`	HTTP status code (default: 200)
`$message`	`(untyped)`	`null`	Optional success message
`$links`	`(untyped)`	`[]`	Optional HATEOAS links
`$ttl`	`(untyped)`	`self::CACHE_TTL`	Cache TTL in seconds

Returns: (none declared) — void

created()

public static function created($data, $message = &#039;Resource created successfully&#039;, $links = [], $locationUrl = null)

lines 289–307 (19)

Send a created response (201)

Parameter	Type	Default	Description
`$data`	`(untyped)`	required	The created resource data
`$message`	`(untyped)`	'`Resource created successfully`'	Optional success message
`$links`	`(untyped)`	`[]`	Optional HATEOAS links
`$locationUrl`	`(untyped)`	`null`	Optional Location header URL

Returns: (none declared) — void

noContent()

public static function noContent()

lines 314–317 (4)

Send a no content response (204)

Takes no parameters.

Returns: (none declared) — void

error()

public static function error($message, $statusCode = self::HTTP_INTERNAL_SERVER_ERROR, $errorCode = null, $errors = null)

lines 328–344 (17)

Send an error response

Parameter	Type	Default	Description
`$message`	`(untyped)`	required	Error message
`$statusCode`	`(untyped)`	`self::HTTP_INTERNAL_SERVER_ERROR`	HTTP status code
`$errorCode`	`(untyped)`	`null`	Optional machine-readable error code
`$errors`	`(untyped)`	`null`	Optional validation errors array

Returns: (none declared) — void

badRequest()

public static function badRequest($message = &#039;Bad Request&#039;, $errors = null)

lines 353–356 (4)

Send a 400 Bad Request error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Bad Request`'	Error message
`$errors`	`(untyped)`	`null`	Optional validation errors

Returns: (none declared) — void

unauthorized()

public static function unauthorized($message = &#039;Unauthorized - Authentication required&#039;)

lines 364–367 (4)

Send a 401 Unauthorized error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Unauthorized - Authentication required`'	Error message

Returns: (none declared) — void

forbidden()

public static function forbidden($message = &#039;Forbidden - Access denied&#039;)

lines 375–378 (4)

Send a 403 Forbidden error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Forbidden - Access denied`'	Error message

Returns: (none declared) — void

notAcceptable()

public static function notAcceptable($message = &#039;Not Acceptable - Requested media type not supported&#039;, $supportedTypes = [&#039;application/json&#039;])

lines 387–391 (5)

Send a 406 Not Acceptable error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Not Acceptable - Requested media type not supported`'	Error message
`$supportedTypes`	`(untyped)`	`['application/json']`	List of supported content types

Returns: (none declared) — void

unsupportedMediaType()

public static function unsupportedMediaType($message = &#039;Unsupported Media Type&#039;)

lines 399–402 (4)

Send a 415 Unsupported Media Type error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Unsupported Media Type`'	Error message

Returns: (none declared) — void

conflict()

public static function conflict($message = &#039;Conflict - Resource already exists&#039;)

lines 410–413 (4)

Send a 409 Conflict error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Conflict - Resource already exists`'	Error message

Returns: (none declared) — void

notFound()

public static function notFound($message = &#039;Resource not found&#039;)

lines 421–424 (4)

Send a 404 Not Found error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Resource not found`'	Error message

Returns: (none declared) — void

unprocessableEntity()

public static function unprocessableEntity($message = &#039;Validation failed&#039;, $errors = null)

lines 433–436 (4)

Send a 422 Unprocessable Entity error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Validation failed`'	Error message
`$errors`	`(untyped)`	`null`	Validation errors

Returns: (none declared) — void

tooManyRequests()

public static function tooManyRequests($message = &#039;Too many requests - Please slow down&#039;, $retryAfter = 60)

lines 445–449 (5)

Send a 429 Too Many Requests error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Too many requests - Please slow down`'	Error message
`$retryAfter`	`(untyped)`	`60`	Seconds until retry

Returns: (none declared) — void

methodNotAllowed()

public static function methodNotAllowed($message = &#039;Method not allowed&#039;, $allowedMethods = &#039;GET, POST, PUT, DELETE, PATCH, OPTIONS&#039;)

lines 458–462 (5)

Send a method not allowed error

Parameter	Type	Default	Description
`$message`	`(untyped)`	'`Method not allowed`'	Error message
`$allowedMethods`	`(untyped)`	'`GET, POST, PUT, DELETE, PATCH, OPTIONS`'	Comma-separated list of allowed methods

Returns: (none declared) — void

paginated()

public static function paginated($data, $currentPage, $perPage, $totalItems, $links = [], $ttl = self::CACHE_TTL)

lines 475–498 (24)

Send a paginated response with HATEOAS links

Parameter	Type	Default	Description
`$data`	`(untyped)`	required	The paginated data
`$currentPage`	`(untyped)`	required	Current page number
`$perPage`	`(untyped)`	required	Items per page
`$totalItems`	`(untyped)`	required	Total number of items
`$links`	`(untyped)`	`[]`	Optional HATEOAS links
`$ttl`	`(untyped)`	`self::CACHE_TTL`	Cache TTL in seconds

Returns: (none declared) — void

validateAccept()

public static function validateAccept($supportedTypes = [&#039;application/json&#039;, &#039;*/*&#039;])

lines 507–534 (28)

Validate Accept header against supported types

Returns true if request is acceptable

Parameter	Type	Default	Description
`$supportedTypes`	`(untyped)`	`['application/json', '/']`	List of supported MIME types

Returns: (none declared) — bool

send()

private static function send($data, $statusCode, $ttl = self::CACHE_TTL)

lines 544–578 (35)

Send raw JSON response

Parameter	Type	Default	Description
`$data`	`(untyped)`	required	Data to be encoded
`$statusCode`	`(untyped)`	required	HTTP status code
`$ttl`	`(untyped)`	`self::CACHE_TTL`	Cache TTL in seconds

Returns: (none declared) — void

getErrorCode()

private static function getErrorCode($statusCode)

lines 586–604 (19)

Get error code from status code

Parameter	Type	Default	Description
`$statusCode`	`(untyped)`	required	HTTP status code

Returns: (none declared) — string Machine-readable error code

setCorsHeaders()

public static function setCorsHeaders($origin = &#039;*&#039;)

lines 612–619 (8)

Set CORS headers for cross-origin requests

Parameter	Type	Default	Description
`$origin`	`(untyped)`	'`*`'	Allowed origin (default: *)

Returns: (none declared) — void

This page is generated from source by 'tools/gendoc'. Edits will be overwritten.

Scriptlog Documentation

Table of Contents

ApiResponse

Inheritance

Constants (18)

Properties (1)

Methods (29)

initRateLimit()

setRateLimitHeaders()

withHeader()

withEtag()

withLastModified()

withLocation()

checkEtagMatch()

checkModifiedSince()

notModified()

setCacheHeaders()

success()

created()

noContent()

error()

badRequest()

unauthorized()

forbidden()

notAcceptable()

unsupportedMediaType()

conflict()

notFound()

unprocessableEntity()

tooManyRequests()

methodNotAllowed()

paginated()

validateAccept()

send()

getErrorCode()

setCorsHeaders()