From 6ebe484abd77861c184a6e98e35cee03d6891683 Mon Sep 17 00:00:00 2001 From: Alex Tselegidis Date: Sun, 10 Jul 2016 10:59:39 +0200 Subject: [PATCH] Added dockblock comments to new classes. --- src/engine/Api/V1/Authorization.php | 2 +- src/engine/Api/V1/Parsers/Appointments.php | 16 +++++++++++++++ .../Api/V1/Parsers/ParsersInterface.php | 19 +++++++++++++++++- src/engine/Api/V1/Processors/Filter.php | 17 ++++++++++++++-- src/engine/Api/V1/Processors/Minimize.php | 19 ++++++++++++++++++ src/engine/Api/V1/Processors/Paginate.php | 18 +++++++++++++++++ src/engine/Api/V1/Processors/Search.php | 20 +++++++++++++++++++ src/engine/Api/V1/Processors/Sort.php | 12 ++++++++++- 8 files changed, 118 insertions(+), 5 deletions(-) diff --git a/src/engine/Api/V1/Authorization.php b/src/engine/Api/V1/Authorization.php index 92460dd0..3fdc6c59 100644 --- a/src/engine/Api/V1/Authorization.php +++ b/src/engine/Api/V1/Authorization.php @@ -18,7 +18,7 @@ use \EA\Engine\Types\NonEmptyString; /** * API v1 Authorization Class * - * This class will handle the authorization procedure. + * This class will handle the authorization procedure of the API. */ class Authorization { /** diff --git a/src/engine/Api/V1/Parsers/Appointments.php b/src/engine/Api/V1/Parsers/Appointments.php index 83828c9e..e0b3b8b7 100644 --- a/src/engine/Api/V1/Parsers/Appointments.php +++ b/src/engine/Api/V1/Parsers/Appointments.php @@ -13,7 +13,17 @@ namespace EA\Engine\Api\V1\Parsers; +/** + * Appointments Parser + * + * This class will handle the encoding and decoding from the API requests. + */ class Appointments implements ParsersInterface { + /** + * Encode Response Array + * + * @param array &$response The response to be encoded. + */ public function encode(array &$response) { $encodedResponse = [ 'id' => $response['id'] !== null ? (int)$response['id'] : null, @@ -31,6 +41,12 @@ class Appointments implements ParsersInterface { $response = $encodedResponse; } + /** + * Decode Request + * + * @param array &$request The request to be decoded. + * @param array $base Optional (null), if provided it will be used as a base array. + */ public function decode(array &$request, array $base = null) { $decodedRequest = $base ?: []; diff --git a/src/engine/Api/V1/Parsers/ParsersInterface.php b/src/engine/Api/V1/Parsers/ParsersInterface.php index 147615ca..8ec7322b 100644 --- a/src/engine/Api/V1/Parsers/ParsersInterface.php +++ b/src/engine/Api/V1/Parsers/ParsersInterface.php @@ -13,7 +13,24 @@ namespace EA\Engine\Api\V1\Parsers; +/** + * Parsers Interface + * + * Every parser needs the "encode" and "decode" methods. + */ interface ParsersInterface { + /** + * Encode Response Array + * + * @param array &$response The response to be encoded. + */ public function encode(array &$response); - public function decode(array &$request); + + /** + * Decode Request + * + * @param array &$request The request to be decoded. + * @param array $base Optional (null), if provided it will be used as a base array. + */ + public function decode(array &$request, array $base = null); } diff --git a/src/engine/Api/V1/Processors/Filter.php b/src/engine/Api/V1/Processors/Filter.php index fb432f95..0fdaa8dd 100644 --- a/src/engine/Api/V1/Processors/Filter.php +++ b/src/engine/Api/V1/Processors/Filter.php @@ -13,9 +13,22 @@ namespace EA\Engine\Api\V1\Processors; +/** + * Filter Processor + * + * This class will handle custom filters upon the response array. In some specific cases it might be + * easier to apply some custom filtering in order to get the required results. + * + * @todo Implement this processor class. + */ class Filter implements ProcessorsInterface { - { +{ + /** + * Process Response Array + * + * @param array &$response The response array to be processed. + */ public static function process(array &$response) { - // will be implemented at a later point + // Not implemented yet. } } diff --git a/src/engine/Api/V1/Processors/Minimize.php b/src/engine/Api/V1/Processors/Minimize.php index 282d3b49..350fcc66 100644 --- a/src/engine/Api/V1/Processors/Minimize.php +++ b/src/engine/Api/V1/Processors/Minimize.php @@ -13,7 +13,26 @@ namespace EA\Engine\Api\V1\Processors; +/** + * Minimize Processor + * + * This processor will check for the "fields" GET parameters and provide only the required fields in + * every response entry. This might come in handy when the client needs specific information and not + * the whole objects. + * + * Make sure that the response parameter is a sequential array and not a single entry by the time this + * processor is executed. + */ class Minimize implements ProcessorsInterface { + /** + * Process Response Array + * + * Example: + * http://ea-installation.com/api/v1/appointments?fields=id,book,start,end + * + * + * @param array &$response The response array to be processed. + */ public static function process(array &$response) { if (!isset($_GET['fields'])) { return; diff --git a/src/engine/Api/V1/Processors/Paginate.php b/src/engine/Api/V1/Processors/Paginate.php index 83b400d9..b8eadcae 100644 --- a/src/engine/Api/V1/Processors/Paginate.php +++ b/src/engine/Api/V1/Processors/Paginate.php @@ -13,7 +13,25 @@ namespace EA\Engine\Api\V1\Processors; +/** + * Paginate Processor + * + * This class will handle the pagination GET parameters ("page", "length"). The "page" parameter + * is required in order for the pagination to work. The "length" is optional and the default value + * is 20 entries per page. + * + * Make sure that the response parameter is a sequential array and not a single entry by the time this + * processor is executed. + */ class Paginate implements ProcessorsInterface { + /** + * Process Response Array + * + * Example: + * http://ea-installation.com/api/v1/appointments?page=3&length=30 + * + * @param array &$response The response array to be processed. + */ public static function process(array &$response) { if (!isset($_GET['page'])) { return; diff --git a/src/engine/Api/V1/Processors/Search.php b/src/engine/Api/V1/Processors/Search.php index a4a774c1..b22eba05 100644 --- a/src/engine/Api/V1/Processors/Search.php +++ b/src/engine/Api/V1/Processors/Search.php @@ -13,7 +13,19 @@ namespace EA\Engine\Api\V1\Processors; +/** + * Search Processor + * + * This class will search the response with the "q" GET parameter and only provide the entries + * that match the keyword. Make sure that the response parameter is a sequential array and not + * a single entry by the time this processor is executed. + */ class Search implements ProcessorsInterface { + /** + * Process Response Array + * + * @param array &$response The response array to be processed. + */ public static function process(array &$response) { if (!isset($_GET['q'])) { return; @@ -31,6 +43,14 @@ class Search implements ProcessorsInterface { $response = $searchedResponse; } + /** + * Recursive Array Search + * + * @param array $haystack Array to search in. + * @param string $needle Keyword to be searched. + * + * @return int|bool Returns the index of the search occurence or false it nothing was found. + */ protected static function _recursiveArraySearch(array $haystack, $needle) { foreach ($haystack as $key => $value) { $currentKey = $key; diff --git a/src/engine/Api/V1/Processors/Sort.php b/src/engine/Api/V1/Processors/Sort.php index 1f1d82ca..7c72d67c 100644 --- a/src/engine/Api/V1/Processors/Sort.php +++ b/src/engine/Api/V1/Processors/Sort.php @@ -13,9 +13,19 @@ namespace EA\Engine\Api\V1\Processors; +/** + * Sort Processor + * + * This class will sort the response array with the provided GET parameters. Make sure that the + * response parameter is a sequential array and not a single entry by the time this processor is + * executed. + */ class Sort implements ProcessorsInterface { /** - * Supports up to 3 fields. + * Supports up to 3 columns for sorting. + * + * Example: + * http://ea-installation.com/api/v1/appointments?sort=-start,+notes,-hash * * @param array &$response The response array to be processed. */