OrderStatusesApiV2Controller
extends HttpApiV2Controller
in package
Class HttpApiV2Controller
Contains common functionality for all the GX2 APIv2 controllers. You can use the $api instance in the child-controllers in order to gain access to request and response information. The $uri variable is an array that contains the requested resource path.
You can use a protected "__initialize" method in your child controllers for performing common operations without overriding the parent constructor method.
This class contains some private methods that define the core operations of each controller and should not be called from a child-controller (like validation, authorization, rate limiting). The only way to disable the execution of these methods is to override the controller.
Table of Contents
- DEFAULT_CONTROLLER_NAME = 'DefaultApiV2Controller'
- Default controller to be loaded when no resource was selected.
- DEFAULT_PAGE_ITEMS = 50
- Defines the default page offset for responses that return multiple items.
- DEFAULT_RATE_LIMIT = 5000
- Defines the maximum request limit for an authorized client.
- DEFAULT_RATE_RESET_PERIOD = 15
- Defines the duration of an API session in minutes.
- $orderStatusService : OrderStatusServiceInterface
- $pager : Pager
- Pagination information.
- $request : Request
- $response : Response
- $sorters : array<string|int, mixed>
- Sorter information array.
- $uri : array<string|int, mixed>
- Contains the request URI segments after the root api version segment.
- __construct() : mixed
- AbstractApiV2Controller Constructor
- __initialize() : mixed
- Initialize Controller
- delete() : mixed
- get() : mixed
- getCallableResource() : mixed
- getResponse() : Response
- post() : mixed
- put() : mixed
- _getMappedControllerUri() : array<string|int, mixed>
- Get the relative URI for the mapped controller.
- _initializePagingAndSortingFields() : mixed
- Initialize pager and sorters fields.
- _linkResponse() : mixed
- Include links to response resources.
- _locateResource() : mixed
- Add location header to a specific response.
- _mapResponse() : bool
- Map the sub-resource to another controller.
- _minimizeResponse() : mixed
- Minimize response using the $fields parameter.
- _paginateResponse() : mixed
- Paginate response using the $page and $per_page GET parameters.
- _prepareResponse() : mixed
- [PRIVATE] Prepare response headers.
- _searchResponse() : mixed
- Perform a search on the response array.
- _setJsonValue() : string
- _setPaginationHeader() : mixed
- [PRIVATE] Set header pagination links.
- _setPaginationHeaderByPage() : mixed
- [PRIVATE] Set header pagination links.
- _setRateLimitHeader() : mixed
- [PRIVATE] Handle rate limit headers.
- _sortResponse() : mixed
- Sort response array with the "sort" GET parameter.
- _validateRequest() : mixed
- [PRIVATE] Validate request before proceeding with response.
- _writeResponse() : mixed
- Write JSON encoded response data.
- getRootUri() : string
- _deserializeOrderStatus() : OrderStatus
- Deserializes an order status object.
- _serializeOrderStatus() : array<string|int, mixed>
- Serializes an order status object.
- _serializeOrderStatusCollection() : array<string|int, mixed>
- Serializes an order status collection.
Constants
DEFAULT_CONTROLLER_NAME
Default controller to be loaded when no resource was selected.
public
string
DEFAULT_CONTROLLER_NAME
= 'DefaultApiV2Controller'
DEFAULT_PAGE_ITEMS
Defines the default page offset for responses that return multiple items.
public
int
DEFAULT_PAGE_ITEMS
= 50
DEFAULT_RATE_LIMIT
Defines the maximum request limit for an authorized client.
public
int
DEFAULT_RATE_LIMIT
= 5000
DEFAULT_RATE_RESET_PERIOD
Defines the duration of an API session in minutes.
public
int
DEFAULT_RATE_RESET_PERIOD
= 15
Properties
$orderStatusService
protected
OrderStatusServiceInterface
$orderStatusService
$pager
Pagination information.
protected
Pager
$pager
$request
protected
Request
$request
$response
protected
Response
$response
$sorters
Sorter information array.
protected
array<string|int, mixed>
$sorters
= []
$uri
Contains the request URI segments after the root api version segment.
protected
array<string|int, mixed>
$uri
Example: URI - api.php/v2/customers/73/addresses CODE - $this->uri[1]; // will return '73'
Methods
__construct()
AbstractApiV2Controller Constructor
public
__construct(Request $request, Response $response, array<string|int, mixed> $uri) : mixed
Call this constructor from every child controller class in order to set the Slim instance and the request routes arguments to the class.
Parameters
- $request : Request
- $response : Response
- $uri : array<string|int, mixed>
-
This array contains all the segments of the current request, starting from the resource.
Tags
Return values
mixed —__initialize()
Initialize Controller
public
__initialize() : mixed
Return values
mixed —delete()
public
delete() : mixed
Tags
Return values
mixed —get()
public
get() : mixed
Tags
Return values
mixed —getCallableResource()
public
static getCallableResource(mixed $controller, array<string|int, mixed> $mappedURI, ServerRequest $request) : mixed
Parameters
- $controller : mixed
- $mappedURI : array<string|int, mixed>
- $request : ServerRequest
Return values
mixed —getResponse()
public
getResponse() : Response
Return values
Response —post()
public
post() : mixed
Tags
Return values
mixed —put()
public
put() : mixed
Tags
Return values
mixed —_getMappedControllerUri()
Get the relative URI for the mapped controller.
protected
_getMappedControllerUri(IntType $index, array<string|int, mixed> $uri) : array<string|int, mixed>
Parameters
- $index : IntType
-
Contains the URI position relative to the current controller.
- $uri : array<string|int, mixed>
-
Contains the original URI
Return values
array<string|int, mixed> —the mapped controller URI
_initializePagingAndSortingFields()
Initialize pager and sorters fields.
protected
_initializePagingAndSortingFields() : mixed
One of the common functionaries of the APIv2 is the pagination and sorting. The fields initialized by this method are helpers to facilitate the access to sort and pagination information
Return values
mixed —_linkResponse()
Include links to response resources.
protected
_linkResponse(array<string|int, mixed> &$response) : mixed
The APIv2 operates with simple resources that might be linked with other resources. This architecture promotes flexibility so that API consumers can have a simpler structure. This method will search for existing external resources and will add a link to the end of each resource.
IMPORTANT: If for some reason you need to include custom links to your resources do not use this method. Include them inside your controller method manually.
NOTICE #1: This method will only search at the first level of the resource. That means that nested ID values will not be taken into concern.
NOTICE #2: You can provide both associative (single response item) or sequential (multiple response items) arrays and this method will adjust the links accordingly.
Parameters
- $response : array<string|int, mixed>
-
Passed by reference, new links will be appended into the end of each resource.
Return values
mixed —_locateResource()
Add location header to a specific response.
protected
_locateResource(string $p_name, int $p_id) : mixed
Use this method whenever you want the "Location" header to point to an existing resource so that clients can use it to fetch that resource without having to generate the URL themselves.
Parameters
- $p_name : string
- $p_id : int
Tags
Return values
mixed —_mapResponse()
Map the sub-resource to another controller.
protected
_mapResponse(array<string|int, mixed> $criteria) : bool
Some API resources contain many subresources which makes the creation of a single controller class complicated and hard to maintain. This method will forward the request to a another controller by checking the provided criteria.
Example:
$criteria = array( 'items' => 'OrdersItemsAttributesApiV2Controller', 'totals' => 'OrdersTotalsApiV2Controller' );
Notice: Each controller should map a direct subresource and not deeper ones. This way every API controller is responsible to map its direct subresources.
Parameters
- $criteria : array<string|int, mixed>
-
An array containing the mapping criteria.
Tags
Return values
bool —Returns whether the request was eventually mapped.
_minimizeResponse()
Minimize response using the $fields parameter.
protected
_minimizeResponse(array<string|int, mixed> &$response) : mixed
APIv2 supports the GET "fields" parameter which enables the client to select the exact fields to be included in the response. It does not support nested fields, only first-level.
You can provide both associative (single response item) or sequential (multiple response items) arrays and this method will adjust the links accordingly.
Parameters
- $response : array<string|int, mixed>
-
Passed by reference, it will be minified to the required fields.
Return values
mixed —_paginateResponse()
Paginate response using the $page and $per_page GET parameters.
protected
_paginateResponse(array<string|int, mixed> &$response[, int $p_totalItemCount = null ]) : mixed
One of the common functionalities of the APIv2 is the pagination and this can be easily achieved by this function which will update the response with the records that need to be returned. This method will automatically set the pagination headers in the response so that client apps can easily navigate through results.
Parameters
- $response : array<string|int, mixed>
-
Passed by reference, it will be paginated according to the provided parameters.
- $p_totalItemCount : int = null
-
|null Optionally set the total number of resources.
Return values
mixed —_prepareResponse()
[PRIVATE] Prepare response headers.
protected
_prepareResponse() : mixed
This method will prepare default attributes of the API responses. Further response settings must be set explicitly from each controller method separately.
Not available to child-controllers (private method).
Return values
mixed —_searchResponse()
Perform a search on the response array.
protected
_searchResponse(array<string|int, mixed> &$response, string $p_keyword) : mixed
Normally the best way to filter the results is through the corresponding service but some times there is not specific method for searching the requested resource or subresource. When this is the case use this method to filter the results of the response before returning them back to the client.
Parameters
- $response : array<string|int, mixed>
-
Contains the response data to be written.
- $p_keyword : string
-
The keyword to be used for the search.
Tags
Return values
mixed —_setJsonValue()
protected
_setJsonValue(string $jsonString, string $property, string $value) : string
Parameters
- $jsonString : string
-
The json formatted string which should be updated.
- $property : string
-
The name or key of the property which should be updated.
- $value : string
-
The new value which should be set.
Return values
string —The updated json formatted string.
_setPaginationHeader()
[PRIVATE] Set header pagination links.
protected
_setPaginationHeader(int $p_currentPage, int $p_itemsPerPage, int $p_totalItemCount) : mixed
Useful for GET responses that return multiple items to the client. The client can use the links to navigate through the records without having to construct them on its own.
Parameters
- $p_currentPage : int
-
Current request page number.
- $p_itemsPerPage : int
-
The number of items to be returned in each page.
- $p_totalItemCount : int
-
Total number of the resource items.
Tags
Return values
mixed —_setPaginationHeaderByPage()
[PRIVATE] Set header pagination links.
protected
_setPaginationHeaderByPage([Pager $pager = null ], int $p_totalItemCount) : mixed
Useful for GET responses that return multiple items to the client. The client can use the links to navigate through the records without having to construct them on its own.
Parameters
- $pager : Pager = null
-
Pager object with pagination information
- $p_totalItemCount : int
-
Total number of the resource items.
Tags
Return values
mixed —_setRateLimitHeader()
[PRIVATE] Handle rate limit headers.
protected
_setRateLimitHeader() : mixed
There is a cache file that will store each user session and provide a security mechanism that will protect the shop from DOS attacks or service overuse. Each session will use the hashed "Authorization header" to identify the client. When the limit is reached a "HTTP/1.1 429 Too Many Requests" will be returned.
Headers: X-Rate-Limit-Limit >> Max number of requests allowed. X-Rate-Limit-Remaining >> Number of requests remaining. X-Rate-Limit-Reset >> UTC epoch seconds until the limit is reset.
Important: This method will be executed in every API call and it might slow the response time due to filesystem operations. If the difference is significant then it should be optimized.
Not available to child-controllers (private method).
Tags
Return values
mixed —_sortResponse()
Sort response array with the "sort" GET parameter.
protected
_sortResponse(array<string|int, mixed> &$response) : mixed
This method supports nested sort values, so by providing a "+address.street" value to the "sort" GET parameter the records will be sort by street value in ascending order. Method supports sorting up to 5 fields.
Important #1: This method has some advantages and disadvantages over the classic database sort mechanism. First it does not need mapping between the API fields and the database fields. Second it does not depend on external system code to sort the response items, so if for example a domain-service does not support sorting the result can still be sorted before sent to the client. The disadvantages are that it will only support a predefined number of fields and this is a trade-off because the method should not use the "eval" function, which will introduce security risks. Furthermore it might be a bit slower than the database sorting.
Important #2: This method is using PHP's array_multisort which by default will sort strings in a case sensitive manner. That means that strings starting with a capital letter will come before strings starting with a lowercase letter. http://php.net/manual/en/function.array-multisort.php
Example: // will sort ascending by customer ID and descending by customer company api.php/v2/customers?sort=+id,-address.company
Parameters
- $response : array<string|int, mixed>
-
Passed by reference, contains an array of the multiple items that will returned as a response to the client.
Return values
mixed —_validateRequest()
[PRIVATE] Validate request before proceeding with response.
protected
_validateRequest() : mixed
This method will validate the request headers, user authentication and other parameters before the controller proceeds with the response.
Not available to child-controllers (private method).
Tags
Return values
mixed —_writeResponse()
Write JSON encoded response data.
protected
_writeResponse(array<string|int, mixed> $response[, int $p_statusCode = 200 ]) : mixed
Use this method to write a JSON encoded, pretty printed and unescaped response to the client consumer. It is very important that the API provides pretty printed responses because it is easier for users to debug and develop.
IMPORTANT: PHP v5.3 does not support the JSON_PRETTY_PRINT and JSON_UNESCAPED_SLASHES so this method will check for their existance and then use them if possible.
Parameters
- $response : array<string|int, mixed>
-
Contains the response data to be written.
- $p_statusCode : int = 200
-
(optional) Provide a custom status code for the response, default 200 - Success.
Return values
mixed —getRootUri()
protected
getRootUri() : string
Return values
string —_deserializeOrderStatus()
Deserializes an order status object.
private
_deserializeOrderStatus(array<string|int, mixed> $data) : OrderStatus
Parameters
- $data : array<string|int, mixed>
-
Order status object to be deserialized.
Return values
OrderStatus —Deserialized order status data.
_serializeOrderStatus()
Serializes an order status object.
private
_serializeOrderStatus(OrderStatus $orderStatus) : array<string|int, mixed>
Parameters
- $orderStatus : OrderStatus
-
Order status object to be serialized.
Return values
array<string|int, mixed> —Serialized order status data.
_serializeOrderStatusCollection()
Serializes an order status collection.
private
_serializeOrderStatusCollection(OrderStatusCollection $collection) : array<string|int, mixed>
Parameters
- $collection : OrderStatusCollection
-
Collection of order statuses to be serialized.
Return values
array<string|int, mixed> —Serialized order status collection data.