MarcinOrlowski / laravel-api-response-builder

src/lang/en/builder.php

Indentation +11 added lines, -11 removed lines

@@ -10,19 +10,19 @@
  */
 return [
 
-    'ok'                       => 'OK',
-    'no_error_message'         => 'Error #:api_code',
+	'ok'                       => 'OK',
+	'no_error_message'         => 'Error #:api_code',
 
-    // can be used by Exception Handler (if enabled)
-    'uncaught_exception'       => 'Uncaught exception :message',
-    // we talking API call here, hence we have http_not_found
-    'http_not_found'           => 'Item not found',
-    'http_exception'           => 'HTTP exception :message',
-    'http_service_unavailable' => 'Service maintenance in progress',
+	// can be used by Exception Handler (if enabled)
+	'uncaught_exception'       => 'Uncaught exception :message',
+	// we talking API call here, hence we have http_not_found
+	'http_not_found'           => 'Item not found',
+	'http_exception'           => 'HTTP exception :message',
+	'http_service_unavailable' => 'Service maintenance in progress',
 
-    // Exception Handler (added in 3.3.0)
-    'authentication_exception' => 'Not authorized to access',
-    'validation_exception'     => 'Invalid data',
+	// Exception Handler (added in 3.3.0)
+	'authentication_exception' => 'Not authorized to access',
+	'validation_exception'     => 'Invalid data',
 
 ];
 

src/lang/pl/builder.php

Indentation +11 added lines, -11 removed lines

@@ -10,18 +10,18 @@
  */
 return [
 
-    'ok'                       => 'OK',
-    'no_error_message'         => 'Błąd #:api_code',
+	'ok'                       => 'OK',
+	'no_error_message'         => 'Błąd #:api_code',
 
-    // can be used by Exception Handler (if enabled)
-    'uncaught_exception'       => 'Nieprzechwycony wyjątek :message',
-    // we talking API call here, hence we have http_not_found
-    'http_not_found'           => 'Element nie znaleziony',
-    'http_exception'           => 'Wyjątek HTTP :message',
-    'http_service_unavailable' => 'Trwa przerwa serwisowa',
+	// can be used by Exception Handler (if enabled)
+	'uncaught_exception'       => 'Nieprzechwycony wyjątek :message',
+	// we talking API call here, hence we have http_not_found
+	'http_not_found'           => 'Element nie znaleziony',
+	'http_exception'           => 'Wyjątek HTTP :message',
+	'http_service_unavailable' => 'Trwa przerwa serwisowa',
 
-    // Exception Handler (added in 3.3.0)
-    'authentication_exception' => 'Brak autoryzacji dostępu',
-    'validation_exception'     => 'Nieprawidłowe dane',
+	// Exception Handler (added in 3.3.0)
+	'authentication_exception' => 'Brak autoryzacji dostępu',
+	'validation_exception'     => 'Nieprawidłowe dane',
 
 ];

src/ResponseBuilder.php

Spacing +2 added lines, -2 removed lines

@@ -505,7 +505,7 @@ 
         $data = $converter->convert($data);
         if ($data !== null && !is_object($data)) {
             // ensure we get object in final JSON structure in data node
-            $data = (object)$data;
+            $data = (object) $data;
         }
 
         // get human readable message for API code or use message string (if given instead of API code)
@@ -527,7 +527,7 @@ 
 
         if ($debug_data !== null) {
             $debug_key = Config::get(static::CONF_KEY_DEBUG_DEBUG_KEY, self::KEY_DEBUG);
-            $response[ $debug_key ] = $debug_data;
+            $response[$debug_key] = $debug_data;
         }
 
         return $response;

Indentation +494 added lines, -494 removed lines

@@ -24,499 +24,499 @@
  */
 class ResponseBuilder
 {
-    /**
-     * Default HTTP code to be used with success responses
-     *
-     * @var int
-     */
-    public const DEFAULT_HTTP_CODE_OK = HttpResponse::HTTP_OK;
-
-    /**
-     * Default HTTP code to be used with error responses
-     *
-     * @var int
-     */
-    public const DEFAULT_HTTP_CODE_ERROR = HttpResponse::HTTP_BAD_REQUEST;
-
-    /**
-     * Min allowed HTTP code for errorXXX()
-     *
-     * @var int
-     */
-    public const ERROR_HTTP_CODE_MIN = 400;
-
-    /**
-     * Max allowed HTTP code for errorXXX()
-     *
-     * @var int
-     */
-    public const ERROR_HTTP_CODE_MAX = 599;
-
-    /**
-     * Configuration keys
-     */
-    public const CONF_KEY_DEBUG_DEBUG_KEY        = 'response_builder.debug.debug_key';
-    public const CONF_KEY_DEBUG_EX_TRACE_ENABLED = 'response_builder.debug.exception_handler.trace_enabled';
-    public const CONF_KEY_DEBUG_EX_TRACE_KEY     = 'response_builder.debug.exception_handler.trace_key';
-    public const CONF_KEY_MAP                    = 'response_builder.map';
-    public const CONF_KEY_ENCODING_OPTIONS       = 'response_builder.encoding_options';
-    public const CONF_KEY_CLASSES                = 'response_builder.classes';
-    public const CONF_KEY_MIN_CODE               = 'response_builder.min_code';
-    public const CONF_KEY_MAX_CODE               = 'response_builder.max_code';
-    public const CONF_EXCEPTION_HANDLER_KEY      = 'response_builder.exception_handler';
-
-    /**
-     * Default keys to be used by exception handler while adding debug information
-     */
-    public const KEY_DEBUG   = 'debug';
-    public const KEY_TRACE   = 'trace';
-    public const KEY_CLASS   = 'class';
-    public const KEY_FILE    = 'file';
-    public const KEY_LINE    = 'line';
-    public const KEY_KEY     = 'key';
-    public const KEY_METHOD  = 'method';
-    public const KEY_SUCCESS = 'success';
-    public const KEY_CODE    = 'code';
-    public const KEY_LOCALE  = 'locale';
-    public const KEY_MESSAGE = 'message';
-    public const KEY_DATA    = 'data';
-
-    /**
-     * Default key to be used by exception handler while processing ValidationException
-     * to return all the error messages
-     *
-     * @var string
-     */
-    public const KEY_MESSAGES = 'messages';
-
-    /**
-     * Default JSON encoding options. Must be specified as final value (i.e. 271) and NOT
-     * PHP expression i.e. `JSON_HEX_TAG|JSON_HEX_APOS|...` as such syntax is not yet supported
-     * by PHP.
-     *
-     * 271 = JSON_HEX_TAG|JSON_HEX_APOS|JSON_HEX_AMP|JSON_HEX_QUOT|JSON_UNESCAPED_UNICODE
-     *
-     * @var int
-     */
-    public const DEFAULT_ENCODING_OPTIONS = 271;
-
-
-
-    /**
-     * Returns success
-     *
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer|null      $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                         for default DEFAULT_HTTP_CODE_OK.
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     */
-    public static function success($data = null, $api_code = null, array $placeholders = null,
-                                   int $http_code = null, int $json_opts = null): HttpResponse
-    {
-        return static::buildSuccessResponse($data, $api_code, $placeholders, $http_code, $json_opts);
-    }
-
-    /**
-     * Returns success
-     *
-     * @param integer|null $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
-     * @param array|null   $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                    substitution or @null if none.
-     * @param integer|null $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                    for default DEFAULT_HTTP_CODE_OK.
-     *
-     * @return HttpResponse
-     */
-    public static function successWithCode(int $api_code = null, array $placeholders = null,
-                                           int $http_code = null): HttpResponse
-    {
-        return static::success(null, $api_code, $placeholders, $http_code);
-    }
-
-    /**
-     * Returns success with custom HTTP code
-     *
-     * @param integer|null $http_code HTTP return code to be set for this response. If @null is passed, falls back
-     *                                to DEFAULT_HTTP_CODE_OK.
-     *
-     * @return HttpResponse
-     */
-    public static function successWithHttpCode(int $http_code = null): HttpResponse
-    {
-        return static::buildSuccessResponse(null, BaseApiCodes::OK(), [], $http_code);
-    }
-
-    /**
-     * @param string            $message       Custom message to be returned as part of the response.
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                         for default DEFAULT_HTTP_CODE_OK.
-     *
-     * @return \Symfony\Component\HttpFoundation\Response
-     */
-    public static function successWithMessage(string $message, $data = null, int $api_code = null,
-                                              int $http_code = null): HttpResponse
-    {
-        return static::buildSuccessResponse($data, $api_code, [], $http_code, null, $message);
-    }
-
-    /**
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node.
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer|null      $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                         for default DEFAULT_HTTP_CODE_OK.
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     *
-     * @throws \InvalidArgumentException Thrown when provided arguments are invalid.
-     */
-    protected static function buildSuccessResponse($data = null, int $api_code = null, array $placeholders = null,
-                                                   int $http_code = null, int $json_opts = null,
-                                                   $msg_or_api_code = null): HttpResponse
-    {
-        $http_code = $http_code ?? static::DEFAULT_HTTP_CODE_OK;
-        $api_code = $api_code ?? BaseApiCodes::OK();
-        $msg_or_api_code = $msg_or_api_code ?? $api_code;
-
-        Validator::assertInt('api_code', $api_code);
-        Validator::assertInt('http_code', $http_code);
-        Validator::assertIntRange('http_code', $http_code, 200, 299);
-        Validator::assertType('msg_or_api_code', $msg_or_api_code, [Validator::TYPE_STRING,
-                                                                    Validator::TYPE_INTEGER]);
-
-        return static::make(true, $api_code, $msg_or_api_code, $data, $http_code, $placeholders, null, $json_opts);
-    }
-
-    /**
-     * Builds error Response object. Supports optional arguments passed to Lang::get() if associated error
-     * message uses placeholders as well as return data payload
-     *
-     * @param integer           $api_code      Your API code to be returned with the response object.
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                         for default DEFAULT_HTTP_CODE_ERROR.
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     */
-    public static function error(int $api_code, array $placeholders = null, $data = null, int $http_code = null,
-                                 int $encoding_options = null): HttpResponse
-    {
-        return static::buildErrorResponse($data, $api_code, $http_code, $placeholders, $encoding_options);
-    }
-
-    /**
-     * @param integer           $api_code      Your API code to be returned with the response object.
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     */
-    public static function errorWithData(int $api_code, $data, array $placeholders = null,
-                                         int $json_opts = null): HttpResponse
-    {
-        return static::buildErrorResponse($data, $api_code, null, $placeholders, $json_opts);
-    }
-
-    /**
-     * @param integer           $api_code      Your API code to be returned with the response object.
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer           $http_code     HTTP code to be used for HttpResponse sent.
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     *
-     * @throws \InvalidArgumentException if http_code is @null
-     */
-    public static function errorWithDataAndHttpCode(int $api_code, $data, int $http_code, array $placeholders = null,
-                                                    int $json_opts = null): HttpResponse
-    {
-        return static::buildErrorResponse($data, $api_code, $http_code, $placeholders, $json_opts);
-    }
-
-    /**
-     * @param integer    $api_code     Your API code to be returned with the response object.
-     * @param integer    $http_code    HTTP code to be used for HttpResponse sent or @null
-     *                                 for default DEFAULT_HTTP_CODE_ERROR.
-     * @param array|null $placeholders Placeholders passed to Lang::get() for message placeholders
-     *                                 substitution or @null if none.
-     *
-     * @return HttpResponse
-     *
-     * @throws \InvalidArgumentException if http_code is @null
-     */
-    public static function errorWithHttpCode(int $api_code, int $http_code, array $placeholders = null): HttpResponse
-    {
-        return static::buildErrorResponse(null, $api_code, $http_code, $placeholders);
-    }
-
-    /**
-     * @param integer           $api_code  Your API code to be returned with the response object.
-     * @param string            $message   Custom message to be returned as part of error response
-     * @param object|array|null $data      Array of primitives and supported objects to be returned in 'data' node
-     *                                     of the JSON response, single supported object or @null if there's no
-     *                                     to be returned.
-     * @param integer|null      $http_code Optional HTTP status code to be used for HttpResponse sent
-     *                                     or @null for DEFAULT_HTTP_CODE_ERROR
-     * @param integer|null      $json_opts See http://php.net/manual/en/function.json-encode.php for supported
-     *                                     options or pass @null to use value from your config (or defaults).
-     *
-     * @return HttpResponse
-     */
-    public static function errorWithMessageAndData(int $api_code, string $message, $data,
-                                                   int $http_code = null, int $json_opts = null): HttpResponse
-    {
-        return static::buildErrorResponse($data, $api_code, $http_code, null,
-            $message, null, $json_opts);
-    }
-
-    /**
-     * @param integer           $api_code   Your API code to be returned with the response object.
-     * @param string            $message    custom message to be returned as part of error response
-     * @param object|array|null $data       Array of primitives and supported objects to be returned in 'data' node
-     *                                      of the JSON response, single supported object or @null if there's no
-     *                                      to be returned.
-     * @param integer|null      $http_code  HTTP code to be used for HttpResponse sent or @null
-     *                                      for default DEFAULT_HTTP_CODE_ERROR.
-     * @param integer|null      $json_opts  See http://php.net/manual/en/function.json-encode.php for supported
-     *                                      options or pass @null to use value from your config (or defaults).
-     * @param array|null        $debug_data optional debug data array to be added to returned JSON.
-     *
-     * @return HttpResponse
-     */
-    public static function errorWithMessageAndDataAndDebug(int $api_code, string $message, $data,
-                                                           int $http_code = null, int $json_opts = null,
-                                                           array $debug_data = null): HttpResponse
-    {
-        return static::buildErrorResponse($data, $api_code, $http_code, null,
-            $message, null, $json_opts, $debug_data);
-    }
-
-    /**
-     * @param integer      $api_code  Your API code to be returned with the response object.
-     * @param string       $message   Custom message to be returned as part of error response
-     * @param integer|null $http_code HTTP code to be used with final response sent or @null
-     *                                for default DEFAULT_HTTP_CODE_ERROR.
-     *
-     * @return HttpResponse
-     */
-    public static function errorWithMessage(int $api_code, string $message, int $http_code = null): HttpResponse
-    {
-        return static::buildErrorResponse(null, $api_code, $http_code, null, $message);
-    }
-
-    /**
-     * Builds error Response object. Supports optional arguments passed to Lang::get() if associated error message
-     * uses placeholders as well as return data payload
-     *
-     * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
-     *                                         of the JSON response, single supported object or @null if there's no
-     *                                         to be returned.
-     * @param integer           $api_code      Your API code to be returned with the response object.
-     * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
-     *                                         for default DEFAULT_HTTP_CODE_ERROR.
-     * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
-     *                                         substitution or @null if none.
-     * @param string|null       $message       custom message to be returned as part of error response
-     * @param array|null        $headers       optional HTTP headers to be returned in error response
-     * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
-     *                                         options or pass @null to use value from your config (or defaults).
-     * @param array|null        $debug_data    optional debug data array to be added to returned JSON.
-     *
-     * @return HttpResponse
-     *
-     * @throws \InvalidArgumentException Thrown if $code is not correct, outside the range, equals OK code etc.
-     *
-     * @noinspection MoreThanThreeArgumentsInspection
-     */
-    protected static function buildErrorResponse($data, int $api_code, int $http_code = null,
-                                                 array $placeholders = null,
-                                                 string $message = null, array $headers = null,
-                                                 int $json_opts = null,
-                                                 array $debug_data = null): HttpResponse
-    {
-        $http_code = $http_code ?? static::DEFAULT_HTTP_CODE_ERROR;
-        $headers = $headers ?? [];
-
-        Validator::assertInt('api_code', $api_code);
-
-        $code_ok = BaseApiCodes::OK();
-        if ($api_code !== $code_ok) {
-            Validator::assertIntRange('api_code', $api_code, BaseApiCodes::getMinCode(), BaseApiCodes::getMaxCode());
-        }
-        if ($api_code === $code_ok) {
-            throw new \InvalidArgumentException(
-                "Error response cannot use api_code of value  {$code_ok} which is reserved for OK");
-        }
-
-        Validator::assertInt('http_code', $http_code);
-        Validator::assertIntRange('http_code', $http_code, static::ERROR_HTTP_CODE_MIN, static::ERROR_HTTP_CODE_MAX);
-
-        $msg_or_api_code = $message ?? $api_code;
-
-        return static::make(false, $api_code, $msg_or_api_code, $data, $http_code,
-            $placeholders, $headers, $json_opts, $debug_data);
-    }
-
-    /**
-     * @param boolean           $success         @true if response reports successful operation, @false otherwise.
-     * @param integer           $api_code        Your API code to be returned with the response object.
-     * @param string|integer    $msg_or_api_code message string or valid API code to get message for
-     * @param object|array|null $data            optional additional data to be included in response object
-     * @param integer|null      $http_code       HTTP code for the HttpResponse or @null for either DEFAULT_HTTP_CODE_OK
-     *                                           or DEFAULT_HTTP_CODE_ERROR depending on the $success.
-     * @param array|null        $placeholders    Placeholders passed to Lang::get() for message placeholders
-     *                                           substitution or @null if none.
-     * @param array|null        $headers         Optional HTTP headers to be returned in the response.
-     * @param integer|null      $json_opts       See http://php.net/manual/en/function.json-encode.php for supported
-     *                                           options or pass @null to use value from your config (or defaults).
-     * @param array|null        $debug_data      Optional debug data array to be added to returned JSON.
-     *
-     * @return HttpResponse
-     *
-     * @throws \InvalidArgumentException If $api_code is neither a string nor valid integer code.
-     * @throws \InvalidArgumentException if $data is an object of class that is not configured in "classes" mapping.
-     *
-     * @noinspection MoreThanThreeArgumentsInspection
-     */
-    protected static function make(bool $success, int $api_code, $msg_or_api_code, $data = null,
-                                   int $http_code = null, array $placeholders = null, array $headers = null,
-                                   int $json_opts = null, array $debug_data = null): HttpResponse
-    {
-        $headers = $headers ?? [];
-        $http_code = $http_code ?? ($success ? static::DEFAULT_HTTP_CODE_OK : static::DEFAULT_HTTP_CODE_ERROR);
-        $json_opts = $json_opts ?? Config::get(self::CONF_KEY_ENCODING_OPTIONS, static::DEFAULT_ENCODING_OPTIONS);
-
-        Validator::assertInt('encoding_options', $json_opts);
-
-        Validator::assertInt('api_code', $api_code);
-        if (!BaseApiCodes::isCodeValid($api_code)) {
-            $min = BaseApiCodes::getMinCode();
-            $max = BaseApiCodes::getMaxCode();
-            throw new \InvalidArgumentException("API code value ({$api_code}) is out of allowed range {$min}-{$max}");
-        }
-
-        return Response::json(
-            static::buildResponse($success, $api_code, $msg_or_api_code, $placeholders, $data, $debug_data),
-            $http_code, $headers, $json_opts);
-    }
-
-    /**
-     * If $msg_or_api_code is integer value, returns human readable message associated with that code (with
-     * fallback to built-in default string if no api code mapping is set. If $msg_or_api_code is a string,
-     * returns it unaltered.
-     *
-     * @param boolean    $success      @true if response reports successful operation, @false otherwise.
-     * @param integer    $api_code     Your API code to be returned with the response object.
-     * @param array|null $placeholders Placeholders passed to Lang::get() for message placeholders
-     *                                 substitution or @null if none.
-     *
-     * @return string
-     */
-    protected static function getMessageForApiCode(bool $success, int $api_code, array $placeholders = null): string
-    {
-        // We got integer value here not a message string, so we need to check if we have the mapping for
-        // this string already configured.
-        $key = BaseApiCodes::getCodeMessageKey($api_code);
-        if ($key === null) {
-            // nope, let's get the default one instead, based of
-            $fallback_code = $success ? BaseApiCodes::OK() : BaseApiCodes::NO_ERROR_MESSAGE();
-            $key = BaseApiCodes::getCodeMessageKey($fallback_code);
-        }
-
-        $placeholders = $placeholders ?? [];
-        if (!array_key_exists('api_code', $placeholders)) {
-            $placeholders['api_code'] = $api_code;
-        }
-
-        return \Lang::get($key, $placeholders);
-    }
-
-    /**
-     * Creates standardised API response array. This is final method called in the whole pipeline before we
-     * return final JSON back to client. If you want to manipulate your response, this is the place to do that.
-     * If you set APP_DEBUG to true, 'code_hex' field will be additionally added to reported JSON for easier
-     * manual debugging.
-     *
-     * @param boolean           $success         @true if response reports successful operation, @false otherwise.
-     * @param integer           $api_code        Your API code to be returned with the response object.
-     * @param string|integer    $msg_or_api_code Message string or valid API code to get message for.
-     * @param array|null        $placeholders    Placeholders passed to Lang::get() for message placeholders
-     *                                           substitution or @null if none.
-     * @param object|array|null $data            API response data if any
-     * @param array|null        $debug_data      optional debug data array to be added to returned JSON.
-     *
-     * @return array response ready to be encoded as json and sent back to client
-     *
-     * @throws \RuntimeException in case of missing or invalid "classes" mapping configuration
-     */
-    protected static function buildResponse(bool $success, int $api_code,
-                                            $msg_or_api_code, array $placeholders = null,
-                                            $data = null, array $debug_data = null): array
-    {
-        // ensure $data is either @null, array or object of class with configured mapping.
-        $converter = new Converter();
-
-        $data = $converter->convert($data);
-        if ($data !== null && !is_object($data)) {
-            // ensure we get object in final JSON structure in data node
-            $data = (object)$data;
-        }
-
-        // get human readable message for API code or use message string (if given instead of API code)
-        if (is_int($msg_or_api_code)) {
-            $message = self::getMessageForApiCode($success, $msg_or_api_code, $placeholders);
-        } else {
-            Validator::assertString('message', $msg_or_api_code);
-            $message = $msg_or_api_code;
-        }
-
-        /** @noinspection PhpUndefinedClassInspection */
-        $response = [
-            static::KEY_SUCCESS => $success,
-            static::KEY_CODE    => $api_code,
-            static::KEY_LOCALE  => \App::getLocale(),
-            static::KEY_MESSAGE => $message,
-            static::KEY_DATA    => $data,
-        ];
-
-        if ($debug_data !== null) {
-            $debug_key = Config::get(static::CONF_KEY_DEBUG_DEBUG_KEY, self::KEY_DEBUG);
-            $response[ $debug_key ] = $debug_data;
-        }
-
-        return $response;
-    }
+	/**
+	 * Default HTTP code to be used with success responses
+	 *
+	 * @var int
+	 */
+	public const DEFAULT_HTTP_CODE_OK = HttpResponse::HTTP_OK;
+
+	/**
+	 * Default HTTP code to be used with error responses
+	 *
+	 * @var int
+	 */
+	public const DEFAULT_HTTP_CODE_ERROR = HttpResponse::HTTP_BAD_REQUEST;
+
+	/**
+	 * Min allowed HTTP code for errorXXX()
+	 *
+	 * @var int
+	 */
+	public const ERROR_HTTP_CODE_MIN = 400;
+
+	/**
+	 * Max allowed HTTP code for errorXXX()
+	 *
+	 * @var int
+	 */
+	public const ERROR_HTTP_CODE_MAX = 599;
+
+	/**
+	 * Configuration keys
+	 */
+	public const CONF_KEY_DEBUG_DEBUG_KEY        = 'response_builder.debug.debug_key';
+	public const CONF_KEY_DEBUG_EX_TRACE_ENABLED = 'response_builder.debug.exception_handler.trace_enabled';
+	public const CONF_KEY_DEBUG_EX_TRACE_KEY     = 'response_builder.debug.exception_handler.trace_key';
+	public const CONF_KEY_MAP                    = 'response_builder.map';
+	public const CONF_KEY_ENCODING_OPTIONS       = 'response_builder.encoding_options';
+	public const CONF_KEY_CLASSES                = 'response_builder.classes';
+	public const CONF_KEY_MIN_CODE               = 'response_builder.min_code';
+	public const CONF_KEY_MAX_CODE               = 'response_builder.max_code';
+	public const CONF_EXCEPTION_HANDLER_KEY      = 'response_builder.exception_handler';
+
+	/**
+	 * Default keys to be used by exception handler while adding debug information
+	 */
+	public const KEY_DEBUG   = 'debug';
+	public const KEY_TRACE   = 'trace';
+	public const KEY_CLASS   = 'class';
+	public const KEY_FILE    = 'file';
+	public const KEY_LINE    = 'line';
+	public const KEY_KEY     = 'key';
+	public const KEY_METHOD  = 'method';
+	public const KEY_SUCCESS = 'success';
+	public const KEY_CODE    = 'code';
+	public const KEY_LOCALE  = 'locale';
+	public const KEY_MESSAGE = 'message';
+	public const KEY_DATA    = 'data';
+
+	/**
+	 * Default key to be used by exception handler while processing ValidationException
+	 * to return all the error messages
+	 *
+	 * @var string
+	 */
+	public const KEY_MESSAGES = 'messages';
+
+	/**
+	 * Default JSON encoding options. Must be specified as final value (i.e. 271) and NOT
+	 * PHP expression i.e. `JSON_HEX_TAG|JSON_HEX_APOS|...` as such syntax is not yet supported
+	 * by PHP.
+	 *
+	 * 271 = JSON_HEX_TAG|JSON_HEX_APOS|JSON_HEX_AMP|JSON_HEX_QUOT|JSON_UNESCAPED_UNICODE
+	 *
+	 * @var int
+	 */
+	public const DEFAULT_ENCODING_OPTIONS = 271;
+
+
+
+	/**
+	 * Returns success
+	 *
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer|null      $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                         for default DEFAULT_HTTP_CODE_OK.
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 */
+	public static function success($data = null, $api_code = null, array $placeholders = null,
+								   int $http_code = null, int $json_opts = null): HttpResponse
+	{
+		return static::buildSuccessResponse($data, $api_code, $placeholders, $http_code, $json_opts);
+	}
+
+	/**
+	 * Returns success
+	 *
+	 * @param integer|null $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
+	 * @param array|null   $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                    substitution or @null if none.
+	 * @param integer|null $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                    for default DEFAULT_HTTP_CODE_OK.
+	 *
+	 * @return HttpResponse
+	 */
+	public static function successWithCode(int $api_code = null, array $placeholders = null,
+										   int $http_code = null): HttpResponse
+	{
+		return static::success(null, $api_code, $placeholders, $http_code);
+	}
+
+	/**
+	 * Returns success with custom HTTP code
+	 *
+	 * @param integer|null $http_code HTTP return code to be set for this response. If @null is passed, falls back
+	 *                                to DEFAULT_HTTP_CODE_OK.
+	 *
+	 * @return HttpResponse
+	 */
+	public static function successWithHttpCode(int $http_code = null): HttpResponse
+	{
+		return static::buildSuccessResponse(null, BaseApiCodes::OK(), [], $http_code);
+	}
+
+	/**
+	 * @param string            $message       Custom message to be returned as part of the response.
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                         for default DEFAULT_HTTP_CODE_OK.
+	 *
+	 * @return \Symfony\Component\HttpFoundation\Response
+	 */
+	public static function successWithMessage(string $message, $data = null, int $api_code = null,
+											  int $http_code = null): HttpResponse
+	{
+		return static::buildSuccessResponse($data, $api_code, [], $http_code, null, $message);
+	}
+
+	/**
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node.
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer|null      $api_code      API code to be returned or @null to use value of BaseApiCodes::OK().
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                         for default DEFAULT_HTTP_CODE_OK.
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 *
+	 * @throws \InvalidArgumentException Thrown when provided arguments are invalid.
+	 */
+	protected static function buildSuccessResponse($data = null, int $api_code = null, array $placeholders = null,
+												   int $http_code = null, int $json_opts = null,
+												   $msg_or_api_code = null): HttpResponse
+	{
+		$http_code = $http_code ?? static::DEFAULT_HTTP_CODE_OK;
+		$api_code = $api_code ?? BaseApiCodes::OK();
+		$msg_or_api_code = $msg_or_api_code ?? $api_code;
+
+		Validator::assertInt('api_code', $api_code);
+		Validator::assertInt('http_code', $http_code);
+		Validator::assertIntRange('http_code', $http_code, 200, 299);
+		Validator::assertType('msg_or_api_code', $msg_or_api_code, [Validator::TYPE_STRING,
+																	Validator::TYPE_INTEGER]);
+
+		return static::make(true, $api_code, $msg_or_api_code, $data, $http_code, $placeholders, null, $json_opts);
+	}
+
+	/**
+	 * Builds error Response object. Supports optional arguments passed to Lang::get() if associated error
+	 * message uses placeholders as well as return data payload
+	 *
+	 * @param integer           $api_code      Your API code to be returned with the response object.
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                         for default DEFAULT_HTTP_CODE_ERROR.
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 */
+	public static function error(int $api_code, array $placeholders = null, $data = null, int $http_code = null,
+								 int $encoding_options = null): HttpResponse
+	{
+		return static::buildErrorResponse($data, $api_code, $http_code, $placeholders, $encoding_options);
+	}
+
+	/**
+	 * @param integer           $api_code      Your API code to be returned with the response object.
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 */
+	public static function errorWithData(int $api_code, $data, array $placeholders = null,
+										 int $json_opts = null): HttpResponse
+	{
+		return static::buildErrorResponse($data, $api_code, null, $placeholders, $json_opts);
+	}
+
+	/**
+	 * @param integer           $api_code      Your API code to be returned with the response object.
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer           $http_code     HTTP code to be used for HttpResponse sent.
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 *
+	 * @throws \InvalidArgumentException if http_code is @null
+	 */
+	public static function errorWithDataAndHttpCode(int $api_code, $data, int $http_code, array $placeholders = null,
+													int $json_opts = null): HttpResponse
+	{
+		return static::buildErrorResponse($data, $api_code, $http_code, $placeholders, $json_opts);
+	}
+
+	/**
+	 * @param integer    $api_code     Your API code to be returned with the response object.
+	 * @param integer    $http_code    HTTP code to be used for HttpResponse sent or @null
+	 *                                 for default DEFAULT_HTTP_CODE_ERROR.
+	 * @param array|null $placeholders Placeholders passed to Lang::get() for message placeholders
+	 *                                 substitution or @null if none.
+	 *
+	 * @return HttpResponse
+	 *
+	 * @throws \InvalidArgumentException if http_code is @null
+	 */
+	public static function errorWithHttpCode(int $api_code, int $http_code, array $placeholders = null): HttpResponse
+	{
+		return static::buildErrorResponse(null, $api_code, $http_code, $placeholders);
+	}
+
+	/**
+	 * @param integer           $api_code  Your API code to be returned with the response object.
+	 * @param string            $message   Custom message to be returned as part of error response
+	 * @param object|array|null $data      Array of primitives and supported objects to be returned in 'data' node
+	 *                                     of the JSON response, single supported object or @null if there's no
+	 *                                     to be returned.
+	 * @param integer|null      $http_code Optional HTTP status code to be used for HttpResponse sent
+	 *                                     or @null for DEFAULT_HTTP_CODE_ERROR
+	 * @param integer|null      $json_opts See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                     options or pass @null to use value from your config (or defaults).
+	 *
+	 * @return HttpResponse
+	 */
+	public static function errorWithMessageAndData(int $api_code, string $message, $data,
+												   int $http_code = null, int $json_opts = null): HttpResponse
+	{
+		return static::buildErrorResponse($data, $api_code, $http_code, null,
+			$message, null, $json_opts);
+	}
+
+	/**
+	 * @param integer           $api_code   Your API code to be returned with the response object.
+	 * @param string            $message    custom message to be returned as part of error response
+	 * @param object|array|null $data       Array of primitives and supported objects to be returned in 'data' node
+	 *                                      of the JSON response, single supported object or @null if there's no
+	 *                                      to be returned.
+	 * @param integer|null      $http_code  HTTP code to be used for HttpResponse sent or @null
+	 *                                      for default DEFAULT_HTTP_CODE_ERROR.
+	 * @param integer|null      $json_opts  See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                      options or pass @null to use value from your config (or defaults).
+	 * @param array|null        $debug_data optional debug data array to be added to returned JSON.
+	 *
+	 * @return HttpResponse
+	 */
+	public static function errorWithMessageAndDataAndDebug(int $api_code, string $message, $data,
+														   int $http_code = null, int $json_opts = null,
+														   array $debug_data = null): HttpResponse
+	{
+		return static::buildErrorResponse($data, $api_code, $http_code, null,
+			$message, null, $json_opts, $debug_data);
+	}
+
+	/**
+	 * @param integer      $api_code  Your API code to be returned with the response object.
+	 * @param string       $message   Custom message to be returned as part of error response
+	 * @param integer|null $http_code HTTP code to be used with final response sent or @null
+	 *                                for default DEFAULT_HTTP_CODE_ERROR.
+	 *
+	 * @return HttpResponse
+	 */
+	public static function errorWithMessage(int $api_code, string $message, int $http_code = null): HttpResponse
+	{
+		return static::buildErrorResponse(null, $api_code, $http_code, null, $message);
+	}
+
+	/**
+	 * Builds error Response object. Supports optional arguments passed to Lang::get() if associated error message
+	 * uses placeholders as well as return data payload
+	 *
+	 * @param object|array|null $data          Array of primitives and supported objects to be returned in 'data' node
+	 *                                         of the JSON response, single supported object or @null if there's no
+	 *                                         to be returned.
+	 * @param integer           $api_code      Your API code to be returned with the response object.
+	 * @param integer|null      $http_code     HTTP code to be used for HttpResponse sent or @null
+	 *                                         for default DEFAULT_HTTP_CODE_ERROR.
+	 * @param array|null        $placeholders  Placeholders passed to Lang::get() for message placeholders
+	 *                                         substitution or @null if none.
+	 * @param string|null       $message       custom message to be returned as part of error response
+	 * @param array|null        $headers       optional HTTP headers to be returned in error response
+	 * @param integer|null      $json_opts     See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                         options or pass @null to use value from your config (or defaults).
+	 * @param array|null        $debug_data    optional debug data array to be added to returned JSON.
+	 *
+	 * @return HttpResponse
+	 *
+	 * @throws \InvalidArgumentException Thrown if $code is not correct, outside the range, equals OK code etc.
+	 *
+	 * @noinspection MoreThanThreeArgumentsInspection
+	 */
+	protected static function buildErrorResponse($data, int $api_code, int $http_code = null,
+												 array $placeholders = null,
+												 string $message = null, array $headers = null,
+												 int $json_opts = null,
+												 array $debug_data = null): HttpResponse
+	{
+		$http_code = $http_code ?? static::DEFAULT_HTTP_CODE_ERROR;
+		$headers = $headers ?? [];
+
+		Validator::assertInt('api_code', $api_code);
+
+		$code_ok = BaseApiCodes::OK();
+		if ($api_code !== $code_ok) {
+			Validator::assertIntRange('api_code', $api_code, BaseApiCodes::getMinCode(), BaseApiCodes::getMaxCode());
+		}
+		if ($api_code === $code_ok) {
+			throw new \InvalidArgumentException(
+				"Error response cannot use api_code of value  {$code_ok} which is reserved for OK");
+		}
+
+		Validator::assertInt('http_code', $http_code);
+		Validator::assertIntRange('http_code', $http_code, static::ERROR_HTTP_CODE_MIN, static::ERROR_HTTP_CODE_MAX);
+
+		$msg_or_api_code = $message ?? $api_code;
+
+		return static::make(false, $api_code, $msg_or_api_code, $data, $http_code,
+			$placeholders, $headers, $json_opts, $debug_data);
+	}
+
+	/**
+	 * @param boolean           $success         @true if response reports successful operation, @false otherwise.
+	 * @param integer           $api_code        Your API code to be returned with the response object.
+	 * @param string|integer    $msg_or_api_code message string or valid API code to get message for
+	 * @param object|array|null $data            optional additional data to be included in response object
+	 * @param integer|null      $http_code       HTTP code for the HttpResponse or @null for either DEFAULT_HTTP_CODE_OK
+	 *                                           or DEFAULT_HTTP_CODE_ERROR depending on the $success.
+	 * @param array|null        $placeholders    Placeholders passed to Lang::get() for message placeholders
+	 *                                           substitution or @null if none.
+	 * @param array|null        $headers         Optional HTTP headers to be returned in the response.
+	 * @param integer|null      $json_opts       See http://php.net/manual/en/function.json-encode.php for supported
+	 *                                           options or pass @null to use value from your config (or defaults).
+	 * @param array|null        $debug_data      Optional debug data array to be added to returned JSON.
+	 *
+	 * @return HttpResponse
+	 *
+	 * @throws \InvalidArgumentException If $api_code is neither a string nor valid integer code.
+	 * @throws \InvalidArgumentException if $data is an object of class that is not configured in "classes" mapping.
+	 *
+	 * @noinspection MoreThanThreeArgumentsInspection
+	 */
+	protected static function make(bool $success, int $api_code, $msg_or_api_code, $data = null,
+								   int $http_code = null, array $placeholders = null, array $headers = null,
+								   int $json_opts = null, array $debug_data = null): HttpResponse
+	{
+		$headers = $headers ?? [];
+		$http_code = $http_code ?? ($success ? static::DEFAULT_HTTP_CODE_OK : static::DEFAULT_HTTP_CODE_ERROR);
+		$json_opts = $json_opts ?? Config::get(self::CONF_KEY_ENCODING_OPTIONS, static::DEFAULT_ENCODING_OPTIONS);
+
+		Validator::assertInt('encoding_options', $json_opts);
+
+		Validator::assertInt('api_code', $api_code);
+		if (!BaseApiCodes::isCodeValid($api_code)) {
+			$min = BaseApiCodes::getMinCode();
+			$max = BaseApiCodes::getMaxCode();
+			throw new \InvalidArgumentException("API code value ({$api_code}) is out of allowed range {$min}-{$max}");
+		}
+
+		return Response::json(
+			static::buildResponse($success, $api_code, $msg_or_api_code, $placeholders, $data, $debug_data),
+			$http_code, $headers, $json_opts);
+	}
+
+	/**
+	 * If $msg_or_api_code is integer value, returns human readable message associated with that code (with
+	 * fallback to built-in default string if no api code mapping is set. If $msg_or_api_code is a string,
+	 * returns it unaltered.
+	 *
+	 * @param boolean    $success      @true if response reports successful operation, @false otherwise.
+	 * @param integer    $api_code     Your API code to be returned with the response object.
+	 * @param array|null $placeholders Placeholders passed to Lang::get() for message placeholders
+	 *                                 substitution or @null if none.
+	 *
+	 * @return string
+	 */
+	protected static function getMessageForApiCode(bool $success, int $api_code, array $placeholders = null): string
+	{
+		// We got integer value here not a message string, so we need to check if we have the mapping for
+		// this string already configured.
+		$key = BaseApiCodes::getCodeMessageKey($api_code);
+		if ($key === null) {
+			// nope, let's get the default one instead, based of
+			$fallback_code = $success ? BaseApiCodes::OK() : BaseApiCodes::NO_ERROR_MESSAGE();
+			$key = BaseApiCodes::getCodeMessageKey($fallback_code);
+		}
+
+		$placeholders = $placeholders ?? [];
+		if (!array_key_exists('api_code', $placeholders)) {
+			$placeholders['api_code'] = $api_code;
+		}
+
+		return \Lang::get($key, $placeholders);
+	}
+
+	/**
+	 * Creates standardised API response array. This is final method called in the whole pipeline before we
+	 * return final JSON back to client. If you want to manipulate your response, this is the place to do that.
+	 * If you set APP_DEBUG to true, 'code_hex' field will be additionally added to reported JSON for easier
+	 * manual debugging.
+	 *
+	 * @param boolean           $success         @true if response reports successful operation, @false otherwise.
+	 * @param integer           $api_code        Your API code to be returned with the response object.
+	 * @param string|integer    $msg_or_api_code Message string or valid API code to get message for.
+	 * @param array|null        $placeholders    Placeholders passed to Lang::get() for message placeholders
+	 *                                           substitution or @null if none.
+	 * @param object|array|null $data            API response data if any
+	 * @param array|null        $debug_data      optional debug data array to be added to returned JSON.
+	 *
+	 * @return array response ready to be encoded as json and sent back to client
+	 *
+	 * @throws \RuntimeException in case of missing or invalid "classes" mapping configuration
+	 */
+	protected static function buildResponse(bool $success, int $api_code,
+											$msg_or_api_code, array $placeholders = null,
+											$data = null, array $debug_data = null): array
+	{
+		// ensure $data is either @null, array or object of class with configured mapping.
+		$converter = new Converter();
+
+		$data = $converter->convert($data);
+		if ($data !== null && !is_object($data)) {
+			// ensure we get object in final JSON structure in data node
+			$data = (object)$data;
+		}
+
+		// get human readable message for API code or use message string (if given instead of API code)
+		if (is_int($msg_or_api_code)) {
+			$message = self::getMessageForApiCode($success, $msg_or_api_code, $placeholders);
+		} else {
+			Validator::assertString('message', $msg_or_api_code);
+			$message = $msg_or_api_code;
+		}
+
+		/** @noinspection PhpUndefinedClassInspection */
+		$response = [
+			static::KEY_SUCCESS => $success,
+			static::KEY_CODE    => $api_code,
+			static::KEY_LOCALE  => \App::getLocale(),
+			static::KEY_MESSAGE => $message,
+			static::KEY_DATA    => $data,
+		];
+
+		if ($debug_data !== null) {
+			$debug_key = Config::get(static::CONF_KEY_DEBUG_DEBUG_KEY, self::KEY_DEBUG);
+			$response[ $debug_key ] = $debug_data;
+		}
+
+		return $response;
+	}
 
 }

src/BaseApiCodes.php

Indentation +168 added lines, -168 removed lines

@@ -19,173 +19,173 @@
  */
 class BaseApiCodes
 {
-    use ApiCodesHelpers;
-
-    /**
-     * protected code range - lowest code for reserved range.
-     *
-     * @var int
-     */
-    public const RESERVED_MIN_API_CODE_OFFSET = 0;
-
-    /**
-     * protected code range - highest code for reserved range
-     *
-     * @var int
-     */
-    public const RESERVED_MAX_API_CODE_OFFSET = 19;
-
-    /**
-     * built-in codes: OK
-     *
-     * @var int
-     */
-    protected const OK_OFFSET = 0;
-    /**
-     * built-in code for fallback message mapping
-     *
-     * @var int
-     */
-    protected const NO_ERROR_MESSAGE_OFFSET = 1;
-    /**
-     * built-in error code for HTTP_NOT_FOUND exception
-     *
-     * @var int
-     */
-    protected const EX_HTTP_NOT_FOUND_OFFSET = 10;
-    /**
-     * built-in error code for HTTP_SERVICE_UNAVAILABLE exception
-     *
-     * @var int
-     */
-    protected const EX_HTTP_SERVICE_UNAVAILABLE_OFFSET = 11;
-    /**
-     * built-in error code for HTTP_EXCEPTION
-     *
-     * @var int
-     */
-    protected const EX_HTTP_EXCEPTION_OFFSET = 12;
-    /**
-     * built-in error code for UNCAUGHT_EXCEPTION
-     *
-     * @var int
-     */
-    protected const EX_UNCAUGHT_EXCEPTION_OFFSET = 13;
-
-    /**
-     * built-in error code for \Illuminate\Auth\AuthenticationException
-     *
-     * @var int
-     */
-    protected const EX_AUTHENTICATION_EXCEPTION_OFFSET = 14;
-
-    /**
-     * built-in error code for \Illuminate\Auth\AuthenticationException
-     *
-     * @var int
-     */
-    protected const EX_VALIDATION_EXCEPTION_OFFSET = 15;
-
-    /**
-     * Returns base code mapping array
-     *
-     * @return array
-     */
-    protected static function getBaseMap(): array
-    {
-        /**
-         * @var array built-in codes mapping
-         */
-        return [
-            self::OK()                          => 'response-builder::builder.ok',
-            self::NO_ERROR_MESSAGE()            => 'response-builder::builder.no_error_message',
-            self::EX_HTTP_NOT_FOUND()           => 'response-builder::builder.http_not_found',
-            self::EX_HTTP_SERVICE_UNAVAILABLE() => 'response-builder::builder.http_service_unavailable',
-            self::EX_HTTP_EXCEPTION()           => 'response-builder::builder.http_exception',
-            self::EX_UNCAUGHT_EXCEPTION()       => 'response-builder::builder.uncaught_exception',
-            self::EX_AUTHENTICATION_EXCEPTION() => 'response-builder::builder.authentication_exception',
-            self::EX_VALIDATION_EXCEPTION()     => 'response-builder::builder.validation_exception',
-        ];
-    }
-
-    /**
-     * Returns API code for internal code OK
-     *
-     * @return int valid API code in current range
-     */
-    public static function OK(): int
-    {
-        return static::getCodeForInternalOffset(static::OK_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code NO_ERROR_MESSAGE
-     *
-     * @return int valid API code in current range
-     */
-    public static function NO_ERROR_MESSAGE(): int
-    {
-        return static::getCodeForInternalOffset(static::NO_ERROR_MESSAGE_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_HTTP_NOT_FOUND
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_HTTP_NOT_FOUND(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_HTTP_NOT_FOUND_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_HTTP_EXCEPTION
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_HTTP_EXCEPTION(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_HTTP_EXCEPTION_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_UNCAUGHT_EXCEPTION
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_UNCAUGHT_EXCEPTION(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_UNCAUGHT_EXCEPTION_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_AUTHENTICATION_EXCEPTION
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_AUTHENTICATION_EXCEPTION(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_AUTHENTICATION_EXCEPTION_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_VALIDATION_EXCEPTION
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_VALIDATION_EXCEPTION(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_VALIDATION_EXCEPTION_OFFSET);
-    }
-
-    /**
-     * Returns API code for internal code EX_HTTP_SERVICE_UNAVAILABLE
-     *
-     * @return int valid API code in current range
-     */
-    public static function EX_HTTP_SERVICE_UNAVAILABLE(): int
-    {
-        return static::getCodeForInternalOffset(static::EX_HTTP_SERVICE_UNAVAILABLE_OFFSET);
-    }
+	use ApiCodesHelpers;
+
+	/**
+	 * protected code range - lowest code for reserved range.
+	 *
+	 * @var int
+	 */
+	public const RESERVED_MIN_API_CODE_OFFSET = 0;
+
+	/**
+	 * protected code range - highest code for reserved range
+	 *
+	 * @var int
+	 */
+	public const RESERVED_MAX_API_CODE_OFFSET = 19;
+
+	/**
+	 * built-in codes: OK
+	 *
+	 * @var int
+	 */
+	protected const OK_OFFSET = 0;
+	/**
+	 * built-in code for fallback message mapping
+	 *
+	 * @var int
+	 */
+	protected const NO_ERROR_MESSAGE_OFFSET = 1;
+	/**
+	 * built-in error code for HTTP_NOT_FOUND exception
+	 *
+	 * @var int
+	 */
+	protected const EX_HTTP_NOT_FOUND_OFFSET = 10;
+	/**
+	 * built-in error code for HTTP_SERVICE_UNAVAILABLE exception
+	 *
+	 * @var int
+	 */
+	protected const EX_HTTP_SERVICE_UNAVAILABLE_OFFSET = 11;
+	/**
+	 * built-in error code for HTTP_EXCEPTION
+	 *
+	 * @var int
+	 */
+	protected const EX_HTTP_EXCEPTION_OFFSET = 12;
+	/**
+	 * built-in error code for UNCAUGHT_EXCEPTION
+	 *
+	 * @var int
+	 */
+	protected const EX_UNCAUGHT_EXCEPTION_OFFSET = 13;
+
+	/**
+	 * built-in error code for \Illuminate\Auth\AuthenticationException
+	 *
+	 * @var int
+	 */
+	protected const EX_AUTHENTICATION_EXCEPTION_OFFSET = 14;
+
+	/**
+	 * built-in error code for \Illuminate\Auth\AuthenticationException
+	 *
+	 * @var int
+	 */
+	protected const EX_VALIDATION_EXCEPTION_OFFSET = 15;
+
+	/**
+	 * Returns base code mapping array
+	 *
+	 * @return array
+	 */
+	protected static function getBaseMap(): array
+	{
+		/**
+		 * @var array built-in codes mapping
+		 */
+		return [
+			self::OK()                          => 'response-builder::builder.ok',
+			self::NO_ERROR_MESSAGE()            => 'response-builder::builder.no_error_message',
+			self::EX_HTTP_NOT_FOUND()           => 'response-builder::builder.http_not_found',
+			self::EX_HTTP_SERVICE_UNAVAILABLE() => 'response-builder::builder.http_service_unavailable',
+			self::EX_HTTP_EXCEPTION()           => 'response-builder::builder.http_exception',
+			self::EX_UNCAUGHT_EXCEPTION()       => 'response-builder::builder.uncaught_exception',
+			self::EX_AUTHENTICATION_EXCEPTION() => 'response-builder::builder.authentication_exception',
+			self::EX_VALIDATION_EXCEPTION()     => 'response-builder::builder.validation_exception',
+		];
+	}
+
+	/**
+	 * Returns API code for internal code OK
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function OK(): int
+	{
+		return static::getCodeForInternalOffset(static::OK_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code NO_ERROR_MESSAGE
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function NO_ERROR_MESSAGE(): int
+	{
+		return static::getCodeForInternalOffset(static::NO_ERROR_MESSAGE_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_HTTP_NOT_FOUND
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_HTTP_NOT_FOUND(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_HTTP_NOT_FOUND_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_HTTP_EXCEPTION
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_HTTP_EXCEPTION(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_HTTP_EXCEPTION_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_UNCAUGHT_EXCEPTION
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_UNCAUGHT_EXCEPTION(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_UNCAUGHT_EXCEPTION_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_AUTHENTICATION_EXCEPTION
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_AUTHENTICATION_EXCEPTION(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_AUTHENTICATION_EXCEPTION_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_VALIDATION_EXCEPTION
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_VALIDATION_EXCEPTION(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_VALIDATION_EXCEPTION_OFFSET);
+	}
+
+	/**
+	 * Returns API code for internal code EX_HTTP_SERVICE_UNAVAILABLE
+	 *
+	 * @return int valid API code in current range
+	 */
+	public static function EX_HTTP_SERVICE_UNAVAILABLE(): int
+	{
+		return static::getCodeForInternalOffset(static::EX_HTTP_SERVICE_UNAVAILABLE_OFFSET);
+	}
 
 }

src/ApiCodesHelpers.php

Spacing +1 added lines, -1 removed lines

@@ -112,7 +112,7 @@
 
         $map = static::getMap();
 
-        return $map[ $api_code ] ?? null;
+        return $map[$api_code] ?? null;
     }
 
     /**

Indentation +123 added lines, -123 removed lines

@@ -21,128 +21,128 @@
  */
 trait ApiCodesHelpers
 {
-    /**
-     * Returns lowest allowed error code for this module
-     *
-     * @return integer
-     *
-     * @throws \RuntimeException Throws exception if no min_code set up
-     */
-    public static function getMinCode(): int
-    {
-        $key = ResponseBuilder::CONF_KEY_MIN_CODE;
-        $min_code = Config::get($key, null);
-
-        if ($min_code === null) {
-            throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', $key));
-        }
-
-        return $min_code;
-    }
-
-    /**
-     * Returns highest allowed error code for this module
-     *
-     * @return integer
-     *
-     * @throws \RuntimeException Throws exception if no max_code set up
-     */
-    public static function getMaxCode(): int
-    {
-        $key = ResponseBuilder::CONF_KEY_MAX_CODE;
-        $max_code = Config::get($key, null);
-
-        if ($max_code === null) {
-            throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', $key));
-        }
-
-        return $max_code;
-    }
-
-    /**
-     * Returns array of error code constants defined in this class. Used mainly for debugging/tests
-     *
-     * @return array
-     * @throws \ReflectionException
-     */
-    public static function getApiCodeConstants(): array
-    {
-        /** @noinspection PhpUnhandledExceptionInspection */
-        return (new \ReflectionClass(static::class))->getConstants();
-    }
-
-    /**
-     * Returns complete error code to locale string mapping array
-     *
-     * @return array
-     *
-     * @throws \RuntimeException Thrown when builder map is not configured.
-     */
-    public static function getMap(): array
-    {
-        $user_map = Config::get(ResponseBuilder::CONF_KEY_MAP, null);
-        if ($user_map === null) {
-            throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', ResponseBuilder::CONF_KEY_MAP));
-        }
-        if (!is_array($user_map)) {
-            throw new \RuntimeException(sprintf('CONFIG: "%s" must be an array', ResponseBuilder::CONF_KEY_MAP));
-        }
-        return Util::mergeConfig(BaseApiCodes::getBaseMap(), $user_map);
-    }
-
-    /**
-     * Returns locale mappings key for given api code or @null if there's no mapping
-     *
-     * @param integer $api_code Api code to look for mapped message for.
-     *
-     * @return string|null
-     *
-     * @throws \InvalidArgumentException If $code is not in allowed range.
-     */
-    public static function getCodeMessageKey(int $api_code): ?string
-    {
-        if (!static::isCodeValid($api_code)) {
-            $min = static::getMinCode();
-            $max = static::getMaxCode();
-            throw new \InvalidArgumentException("API code value ({$api_code}) is out of allowed range {$min}-{$max}");
-        }
-
-        $map = static::getMap();
-
-        return $map[ $api_code ] ?? null;
-    }
-
-    /**
-     * Checks if given API $code can be used in current configuration.
-     *
-     * @param int $code API code to validate
-     *
-     * @return bool
-     */
-    public static function isCodeValid(int $code): bool
-    {
-        return ($code === 0) || (($code >= static::getMinCode()) && ($code <= static::getMaxCode()));
-    }
-
-    /**
-     * Returns final API code for internal code, remapped to configured code range
-     *
-     * @param int $internal_code
-     *
-     * @return int
-     *
-     * @throws \InvalidArgumentException
-     */
-    protected static function getCodeForInternalOffset(int $internal_code): int
-    {
-        $min = static::RESERVED_MIN_API_CODE_OFFSET;
-        $max = static::RESERVED_MAX_API_CODE_OFFSET;
-        if (($internal_code < $min) || ($internal_code > $max)) {
-            throw new \InvalidArgumentException(
-                "Invalid internal code ({$internal_code}). Must be between {$min}-{$max} inclusive.");
-        }
-
-        return ($internal_code === 0) ? 0 : $internal_code + static::getMinCode();
-    }
+	/**
+	 * Returns lowest allowed error code for this module
+	 *
+	 * @return integer
+	 *
+	 * @throws \RuntimeException Throws exception if no min_code set up
+	 */
+	public static function getMinCode(): int
+	{
+		$key = ResponseBuilder::CONF_KEY_MIN_CODE;
+		$min_code = Config::get($key, null);
+
+		if ($min_code === null) {
+			throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', $key));
+		}
+
+		return $min_code;
+	}
+
+	/**
+	 * Returns highest allowed error code for this module
+	 *
+	 * @return integer
+	 *
+	 * @throws \RuntimeException Throws exception if no max_code set up
+	 */
+	public static function getMaxCode(): int
+	{
+		$key = ResponseBuilder::CONF_KEY_MAX_CODE;
+		$max_code = Config::get($key, null);
+
+		if ($max_code === null) {
+			throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', $key));
+		}
+
+		return $max_code;
+	}
+
+	/**
+	 * Returns array of error code constants defined in this class. Used mainly for debugging/tests
+	 *
+	 * @return array
+	 * @throws \ReflectionException
+	 */
+	public static function getApiCodeConstants(): array
+	{
+		/** @noinspection PhpUnhandledExceptionInspection */
+		return (new \ReflectionClass(static::class))->getConstants();
+	}
+
+	/**
+	 * Returns complete error code to locale string mapping array
+	 *
+	 * @return array
+	 *
+	 * @throws \RuntimeException Thrown when builder map is not configured.
+	 */
+	public static function getMap(): array
+	{
+		$user_map = Config::get(ResponseBuilder::CONF_KEY_MAP, null);
+		if ($user_map === null) {
+			throw new \RuntimeException(sprintf('CONFIG: Missing "%s" key', ResponseBuilder::CONF_KEY_MAP));
+		}
+		if (!is_array($user_map)) {
+			throw new \RuntimeException(sprintf('CONFIG: "%s" must be an array', ResponseBuilder::CONF_KEY_MAP));
+		}
+		return Util::mergeConfig(BaseApiCodes::getBaseMap(), $user_map);
+	}
+
+	/**
+	 * Returns locale mappings key for given api code or @null if there's no mapping
+	 *
+	 * @param integer $api_code Api code to look for mapped message for.
+	 *
+	 * @return string|null
+	 *
+	 * @throws \InvalidArgumentException If $code is not in allowed range.
+	 */
+	public static function getCodeMessageKey(int $api_code): ?string
+	{
+		if (!static::isCodeValid($api_code)) {
+			$min = static::getMinCode();
+			$max = static::getMaxCode();
+			throw new \InvalidArgumentException("API code value ({$api_code}) is out of allowed range {$min}-{$max}");
+		}
+
+		$map = static::getMap();
+
+		return $map[ $api_code ] ?? null;
+	}
+
+	/**
+	 * Checks if given API $code can be used in current configuration.
+	 *
+	 * @param int $code API code to validate
+	 *
+	 * @return bool
+	 */
+	public static function isCodeValid(int $code): bool
+	{
+		return ($code === 0) || (($code >= static::getMinCode()) && ($code <= static::getMaxCode()));
+	}
+
+	/**
+	 * Returns final API code for internal code, remapped to configured code range
+	 *
+	 * @param int $internal_code
+	 *
+	 * @return int
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	protected static function getCodeForInternalOffset(int $internal_code): int
+	{
+		$min = static::RESERVED_MIN_API_CODE_OFFSET;
+		$max = static::RESERVED_MAX_API_CODE_OFFSET;
+		if (($internal_code < $min) || ($internal_code > $max)) {
+			throw new \InvalidArgumentException(
+				"Invalid internal code ({$internal_code}). Must be between {$min}-{$max} inclusive.");
+		}
+
+		return ($internal_code === 0) ? 0 : $internal_code + static::getMinCode();
+	}
 
 }

src/Converter.php

Spacing +6 added lines, -6 removed lines

@@ -72,12 +72,12 @@ 
         // check for exact class name match...
         $cls = get_class($data);
         if (array_key_exists($cls, $this->classes)) {
-            $result = $this->classes[ $cls ];
+            $result = $this->classes[$cls];
         } else {
             // no exact match, then lets try with `instanceof`
             foreach (array_keys($this->classes) as $class_name) {
                 if ($data instanceof $class_name) {
-                    $result = $this->classes[ $class_name ];
+                    $result = $this->classes[$class_name];
                     break;
                 }
             }
@@ -107,7 +107,7 @@ 
 
         if (is_object($data)) {
             $cfg = $this->getClassMappingConfigOrThrow($data);
-            $data = [$cfg[ ResponseBuilder::KEY_KEY ] => $data->{$cfg[ ResponseBuilder::KEY_METHOD ]}()];
+            $data = [$cfg[ResponseBuilder::KEY_KEY] => $data->{$cfg[ResponseBuilder::KEY_METHOD]}()];
         } elseif (!is_array($data)) {
             throw new \InvalidArgumentException(
                 sprintf('Payload must be null, array or object with mapping ("%s" given).', gettype($data)));
@@ -149,13 +149,13 @@ 
 
         foreach ($data as $key => $val) {
             if (is_array($val)) {
-                $data[ $key ] = $this->convertArray($val);
+                $data[$key] = $this->convertArray($val);
             } elseif (is_object($val)) {
                 $cls = get_class($val);
                 if (array_key_exists($cls, $this->classes)) {
-                    $conversion_method = $this->classes[ $cls ][ ResponseBuilder::KEY_METHOD ];
+                    $conversion_method = $this->classes[$cls][ResponseBuilder::KEY_METHOD];
                     $converted_data = $val->$conversion_method();
-                    $data[ $key ] = $converted_data;
+                    $data[$key] = $converted_data;
                 }
             }
         }

Indentation +175 added lines, -175 removed lines

@@ -23,179 +23,179 @@
  */
 class Converter
 {
-    /**
-     * @var array
-     */
-    protected $classes = [];
-
-    /**
-     * Converter constructor.
-     *
-     * @throws \RuntimeException
-     */
-    public function __construct()
-    {
-        $classes = static::getClassesMapping() ?? [];
-        if (!is_array($classes)) {
-            throw new \RuntimeException(
-                sprintf('CONFIG: "classes" mapping must be an array (%s given)', gettype($classes)));
-        }
-
-        $this->classes = $classes;
-    }
-
-    /**
-     * Returns local copy of configuration mapping for the classes.
-     *
-     * @return array
-     */
-    public function getClasses(): array
-    {
-        return $this->classes;
-    }
-
-    /**
-     * Checks if we have "classes" mapping configured for $data object class.
-     * Returns @true if there's valid config for this class.
-     * Throws \RuntimeException if there's no config "classes" mapping entry for this object configured.
-     * Throws \InvalidArgumentException if No data conversion mapping configured for given class.
-     *
-     * @param object $data Object to check mapping for.
-     *
-     * @return array
-     *
-     * @throws \InvalidArgumentException
-     */
-    protected function getClassMappingConfigOrThrow(object $data): array
-    {
-        $result = null;
-
-        // check for exact class name match...
-        $cls = get_class($data);
-        if (array_key_exists($cls, $this->classes)) {
-            $result = $this->classes[ $cls ];
-        } else {
-            // no exact match, then lets try with `instanceof`
-            foreach (array_keys($this->classes) as $class_name) {
-                if ($data instanceof $class_name) {
-                    $result = $this->classes[ $class_name ];
-                    break;
-                }
-            }
-        }
-
-        if ($result === null) {
-            throw new \InvalidArgumentException(sprintf('No data conversion mapping configured for "%s" class.', $cls));
-        }
-
-        return $result;
-    }
-
-    /**
-     * We need to prepare source data
-     *
-     * @param object|array|null $data
-     *
-     * @return array|null
-     *
-     * @throws \InvalidArgumentException
-     */
-    public function convert($data = null): ?array
-    {
-        if ($data === null) {
-            return null;
-        }
-
-        if (is_object($data)) {
-            $cfg = $this->getClassMappingConfigOrThrow($data);
-            $data = [$cfg[ ResponseBuilder::KEY_KEY ] => $data->{$cfg[ ResponseBuilder::KEY_METHOD ]}()];
-        } elseif (!is_array($data)) {
-            throw new \InvalidArgumentException(
-                sprintf('Payload must be null, array or object with mapping ("%s" given).', gettype($data)));
-        }
-
-        return $this->convertArray($data);
-    }
-
-    /**
-     * Recursively walks $data array and converts all known objects if found. Note
-     * $data array is passed by reference so source $data array may be modified.
-     *
-     * @param array $data array to recursively convert known elements of
-     *
-     * @return array
-     *
-     * @throws \RuntimeException
-     */
-    protected function convertArray(array $data): array
-    {
-        // This is to ensure that we either have array with user provided keys i.e. ['foo'=>'bar'], which will then
-        // be turned into JSON object or array without user specified keys (['bar']) which we would return as JSON
-        // array. But you can't mix these two as the final JSON would not produce predictable results.
-        $string_keys_cnt = 0;
-        $int_keys_cnt = 0;
-        foreach ($data as $key => $val) {
-            if (is_int($key)) {
-                $int_keys_cnt++;
-            } else {
-                $string_keys_cnt++;
-            }
-
-            if (($string_keys_cnt > 0) && ($int_keys_cnt > 0)) {
-                throw new \RuntimeException(
-                    'Invalid data array. Either set own keys for all the items or do not specify any keys at all. ' .
-                    'Arrays with mixed keys are not supported by design.');
-            }
-        }
-
-        foreach ($data as $key => $val) {
-            if (is_array($val)) {
-                $data[ $key ] = $this->convertArray($val);
-            } elseif (is_object($val)) {
-                $cls = get_class($val);
-                if (array_key_exists($cls, $this->classes)) {
-                    $conversion_method = $this->classes[ $cls ][ ResponseBuilder::KEY_METHOD ];
-                    $converted_data = $val->$conversion_method();
-                    $data[ $key ] = $converted_data;
-                }
-            }
-        }
-
-        return $data;
-    }
-
-    /**
-     * Reads and validates "classes" config mapping
-     *
-     * @return array Classes mapping as specified in configuration or empty array if configuration found
-     *
-     * @throws \RuntimeException if "classes" mapping is technically invalid (i.e. not array etc).
-     */
-    protected static function getClassesMapping(): ?array
-    {
-        $classes = Config::get(ResponseBuilder::CONF_KEY_CLASSES);
-
-        if ($classes !== null) {
-            if (!is_array($classes)) {
-                throw new \RuntimeException(
-                    sprintf('CONFIG: "classes" mapping must be an array (%s given)', gettype($classes)));
-            }
-
-            $mandatory_keys = [
-                ResponseBuilder::KEY_KEY,
-                ResponseBuilder::KEY_METHOD,
-            ];
-            foreach ($classes as $class_name => $class_config) {
-                foreach ($mandatory_keys as $key_name) {
-                    if (!array_key_exists($key_name, $class_config)) {
-                        throw new \RuntimeException("CONFIG: Missing '{$key_name}' for '{$class_name}' class mapping");
-                    }
-                }
-            }
-        } else {
-            $classes = [];
-        }
-
-        return $classes;
-    }
+	/**
+	 * @var array
+	 */
+	protected $classes = [];
+
+	/**
+	 * Converter constructor.
+	 *
+	 * @throws \RuntimeException
+	 */
+	public function __construct()
+	{
+		$classes = static::getClassesMapping() ?? [];
+		if (!is_array($classes)) {
+			throw new \RuntimeException(
+				sprintf('CONFIG: "classes" mapping must be an array (%s given)', gettype($classes)));
+		}
+
+		$this->classes = $classes;
+	}
+
+	/**
+	 * Returns local copy of configuration mapping for the classes.
+	 *
+	 * @return array
+	 */
+	public function getClasses(): array
+	{
+		return $this->classes;
+	}
+
+	/**
+	 * Checks if we have "classes" mapping configured for $data object class.
+	 * Returns @true if there's valid config for this class.
+	 * Throws \RuntimeException if there's no config "classes" mapping entry for this object configured.
+	 * Throws \InvalidArgumentException if No data conversion mapping configured for given class.
+	 *
+	 * @param object $data Object to check mapping for.
+	 *
+	 * @return array
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	protected function getClassMappingConfigOrThrow(object $data): array
+	{
+		$result = null;
+
+		// check for exact class name match...
+		$cls = get_class($data);
+		if (array_key_exists($cls, $this->classes)) {
+			$result = $this->classes[ $cls ];
+		} else {
+			// no exact match, then lets try with `instanceof`
+			foreach (array_keys($this->classes) as $class_name) {
+				if ($data instanceof $class_name) {
+					$result = $this->classes[ $class_name ];
+					break;
+				}
+			}
+		}
+
+		if ($result === null) {
+			throw new \InvalidArgumentException(sprintf('No data conversion mapping configured for "%s" class.', $cls));
+		}
+
+		return $result;
+	}
+
+	/**
+	 * We need to prepare source data
+	 *
+	 * @param object|array|null $data
+	 *
+	 * @return array|null
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	public function convert($data = null): ?array
+	{
+		if ($data === null) {
+			return null;
+		}
+
+		if (is_object($data)) {
+			$cfg = $this->getClassMappingConfigOrThrow($data);
+			$data = [$cfg[ ResponseBuilder::KEY_KEY ] => $data->{$cfg[ ResponseBuilder::KEY_METHOD ]}()];
+		} elseif (!is_array($data)) {
+			throw new \InvalidArgumentException(
+				sprintf('Payload must be null, array or object with mapping ("%s" given).', gettype($data)));
+		}
+
+		return $this->convertArray($data);
+	}
+
+	/**
+	 * Recursively walks $data array and converts all known objects if found. Note
+	 * $data array is passed by reference so source $data array may be modified.
+	 *
+	 * @param array $data array to recursively convert known elements of
+	 *
+	 * @return array
+	 *
+	 * @throws \RuntimeException
+	 */
+	protected function convertArray(array $data): array
+	{
+		// This is to ensure that we either have array with user provided keys i.e. ['foo'=>'bar'], which will then
+		// be turned into JSON object or array without user specified keys (['bar']) which we would return as JSON
+		// array. But you can't mix these two as the final JSON would not produce predictable results.
+		$string_keys_cnt = 0;
+		$int_keys_cnt = 0;
+		foreach ($data as $key => $val) {
+			if (is_int($key)) {
+				$int_keys_cnt++;
+			} else {
+				$string_keys_cnt++;
+			}
+
+			if (($string_keys_cnt > 0) && ($int_keys_cnt > 0)) {
+				throw new \RuntimeException(
+					'Invalid data array. Either set own keys for all the items or do not specify any keys at all. ' .
+					'Arrays with mixed keys are not supported by design.');
+			}
+		}
+
+		foreach ($data as $key => $val) {
+			if (is_array($val)) {
+				$data[ $key ] = $this->convertArray($val);
+			} elseif (is_object($val)) {
+				$cls = get_class($val);
+				if (array_key_exists($cls, $this->classes)) {
+					$conversion_method = $this->classes[ $cls ][ ResponseBuilder::KEY_METHOD ];
+					$converted_data = $val->$conversion_method();
+					$data[ $key ] = $converted_data;
+				}
+			}
+		}
+
+		return $data;
+	}
+
+	/**
+	 * Reads and validates "classes" config mapping
+	 *
+	 * @return array Classes mapping as specified in configuration or empty array if configuration found
+	 *
+	 * @throws \RuntimeException if "classes" mapping is technically invalid (i.e. not array etc).
+	 */
+	protected static function getClassesMapping(): ?array
+	{
+		$classes = Config::get(ResponseBuilder::CONF_KEY_CLASSES);
+
+		if ($classes !== null) {
+			if (!is_array($classes)) {
+				throw new \RuntimeException(
+					sprintf('CONFIG: "classes" mapping must be an array (%s given)', gettype($classes)));
+			}
+
+			$mandatory_keys = [
+				ResponseBuilder::KEY_KEY,
+				ResponseBuilder::KEY_METHOD,
+			];
+			foreach ($classes as $class_name => $class_config) {
+				foreach ($mandatory_keys as $key_name) {
+					if (!array_key_exists($key_name, $class_config)) {
+						throw new \RuntimeException("CONFIG: Missing '{$key_name}' for '{$class_name}' class mapping");
+					}
+				}
+			}
+		} else {
+			$classes = [];
+		}
+
+		return $classes;
+	}
 }

src/Validator.php

Indentation +76 added lines, -76 removed lines

@@ -15,88 +15,88 @@
  */
 class Validator
 {
-    /** @var string */
-    public const TYPE_STRING = 'string';
+	/** @var string */
+	public const TYPE_STRING = 'string';
 
-    /** @var string */
-    public const TYPE_INTEGER = 'integer';
+	/** @var string */
+	public const TYPE_INTEGER = 'integer';
 
-    /** @var string */
-    public const TYPE_BOOL = 'boolean';
+	/** @var string */
+	public const TYPE_BOOL = 'boolean';
 
-    /**
-     * Checks if given $val is of type integer
-     *
-     * @param string $key Name of the key to be used if exception is thrown.
-     * @param mixed  $var Variable to be asserted.
-     *
-     * @return void
-     *
-     * @throws \InvalidArgumentException
-     */
-    public static function assertInt(string $key, $var): void
-    {
-        self::assertType($key, $var, [self::TYPE_INTEGER]);
-    }
+	/**
+	 * Checks if given $val is of type integer
+	 *
+	 * @param string $key Name of the key to be used if exception is thrown.
+	 * @param mixed  $var Variable to be asserted.
+	 *
+	 * @return void
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	public static function assertInt(string $key, $var): void
+	{
+		self::assertType($key, $var, [self::TYPE_INTEGER]);
+	}
 
-    /**
-     * Checks if given $val is of type string
-     *
-     * @param string $name Label or name of the variable to be used in exception message (if thrown).
-     * @param mixed  $var  Variable to be asserted.
-     *
-     * @return void
-     *
-     * @throws \InvalidArgumentException
-     */
-    public static function assertString(string $name, $var): void
-    {
-        self::assertType($name, $var, [self::TYPE_STRING]);
-    }
+	/**
+	 * Checks if given $val is of type string
+	 *
+	 * @param string $name Label or name of the variable to be used in exception message (if thrown).
+	 * @param mixed  $var  Variable to be asserted.
+	 *
+	 * @return void
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	public static function assertString(string $name, $var): void
+	{
+		self::assertType($name, $var, [self::TYPE_STRING]);
+	}
 
-    /**
-     * @param string $name Label or name of the variable to be used in exception message (if thrown).
-     * @param mixed  $var  Variable to be asserted.
-     * @param int    $min  Min allowed value (inclusive)
-     * @param int    $max  Max allowed value (inclusive)
-     *
-     * @return void
-     *
-     * @throws \InvalidArgumentException
-     * @throws \RuntimeException
-     */
-    public static function assertIntRange(string $name, $var, int $min, int $max): void
-    {
-        self::assertInt($name, $var);
+	/**
+	 * @param string $name Label or name of the variable to be used in exception message (if thrown).
+	 * @param mixed  $var  Variable to be asserted.
+	 * @param int    $min  Min allowed value (inclusive)
+	 * @param int    $max  Max allowed value (inclusive)
+	 *
+	 * @return void
+	 *
+	 * @throws \InvalidArgumentException
+	 * @throws \RuntimeException
+	 */
+	public static function assertIntRange(string $name, $var, int $min, int $max): void
+	{
+		self::assertInt($name, $var);
 
-        if ($min > $max) {
-            throw new \RuntimeException(
-                sprintf('%s: Invalid range for "%s". Ensure bound values are not swapped.', __FUNCTION__, $name));
-        }
+		if ($min > $max) {
+			throw new \RuntimeException(
+				sprintf('%s: Invalid range for "%s". Ensure bound values are not swapped.', __FUNCTION__, $name));
+		}
 
-        if (($min > $var) || ($var > $max)) {
-            throw new \InvalidArgumentException(
-                sprintf('Invalid value of "%s" (%d). Must be between %d-%d inclusive.', $name, $var, $min, $max));
-        }
-    }
+		if (($min > $var) || ($var > $max)) {
+			throw new \InvalidArgumentException(
+				sprintf('Invalid value of "%s" (%d). Must be between %d-%d inclusive.', $name, $var, $min, $max));
+		}
+	}
 
-    /**
-     * Checks if $item (of name $key) is of type that is include in $allowed_types.
-     *
-     * @param string $name          Label or name of the variable to be used in exception message (if thrown).
-     * @param mixed  $var           Variable to be asserted.
-     * @param array  $allowed_types Array of allowed types for $var, i.e. [Validator::TYPE_INTEGER]
-     *
-     * @return void
-     *
-     * @throws \InvalidArgumentException
-     */
-    public static function assertType(string $name, $var, array $allowed_types): void
-    {
-        $type = gettype($var);
-        if (!in_array($type, $allowed_types)) {
-            $msg = sprintf('"%s" must be one of allowed types: %s (%s given)', $name, implode(', ', $allowed_types), gettype($var));
-            throw new \InvalidArgumentException($msg);
-        }
-    }
+	/**
+	 * Checks if $item (of name $key) is of type that is include in $allowed_types.
+	 *
+	 * @param string $name          Label or name of the variable to be used in exception message (if thrown).
+	 * @param mixed  $var           Variable to be asserted.
+	 * @param array  $allowed_types Array of allowed types for $var, i.e. [Validator::TYPE_INTEGER]
+	 *
+	 * @return void
+	 *
+	 * @throws \InvalidArgumentException
+	 */
+	public static function assertType(string $name, $var, array $allowed_types): void
+	{
+		$type = gettype($var);
+		if (!in_array($type, $allowed_types)) {
+			$msg = sprintf('"%s" must be one of allowed types: %s (%s given)', $name, implode(', ', $allowed_types), gettype($var));
+			throw new \InvalidArgumentException($msg);
+		}
+	}
 }

src/Util.php

Spacing +5 added lines, -5 removed lines

@@ -34,20 +34,20 @@
         $array = $original;
         foreach ($merging as $m_key => $m_val) {
             if (array_key_exists($m_key, $original)) {
-                $orig_type = gettype($original[ $m_key ]);
+                $orig_type = gettype($original[$m_key]);
                 $m_type = gettype($m_val);
                 if ($orig_type !== $m_type) {
                     throw new \RuntimeException(
                         "Incompatible types. Cannot merge {$m_type} into {$orig_type} (key '{$m_key}').");
                 }
 
-                if (is_array($merging[ $m_key ])) {
-                    $array[ $m_key ] = static::mergeConfig($original[ $m_key ], $m_val);
+                if (is_array($merging[$m_key])) {
+                    $array[$m_key] = static::mergeConfig($original[$m_key], $m_val);
                 } else {
-                    $array[ $m_key ] = $m_val;
+                    $array[$m_key] = $m_val;
                 }
             } else {
-                $array[ $m_key ] = $m_val;
+                $array[$m_key] = $m_val;
             }
         }
 

Indentation +51 added lines, -51 removed lines

@@ -15,59 +15,59 @@
  */
 final class Util
 {
-    /**
-     * Merges the configs together and takes multi-dimensional arrays into account.
-     * Support for multi-dimensional config array. Built-in config merge only supports flat arrays.
-     * Throws \RuntimeException if arrays stucture causes type conflics (i.e. you want to merge
-     * array with int).
-     *
-     * @param array $original Array to merge other array into. Usually default values to overwrite.
-     * @param array $merging  Array with items to be merged into $original, overriding (primitives) or merging
-     *                        (arrays) entries in destination array.
-     *
-     * @return array
-     *
-     * @throws \RuntimeException
-     */
-    public static function mergeConfig(array $original, array $merging): array
-    {
-        $array = $original;
-        foreach ($merging as $m_key => $m_val) {
-            if (array_key_exists($m_key, $original)) {
-                $orig_type = gettype($original[ $m_key ]);
-                $m_type = gettype($m_val);
-                if ($orig_type !== $m_type) {
-                    throw new \RuntimeException(
-                        "Incompatible types. Cannot merge {$m_type} into {$orig_type} (key '{$m_key}').");
-                }
+	/**
+	 * Merges the configs together and takes multi-dimensional arrays into account.
+	 * Support for multi-dimensional config array. Built-in config merge only supports flat arrays.
+	 * Throws \RuntimeException if arrays stucture causes type conflics (i.e. you want to merge
+	 * array with int).
+	 *
+	 * @param array $original Array to merge other array into. Usually default values to overwrite.
+	 * @param array $merging  Array with items to be merged into $original, overriding (primitives) or merging
+	 *                        (arrays) entries in destination array.
+	 *
+	 * @return array
+	 *
+	 * @throws \RuntimeException
+	 */
+	public static function mergeConfig(array $original, array $merging): array
+	{
+		$array = $original;
+		foreach ($merging as $m_key => $m_val) {
+			if (array_key_exists($m_key, $original)) {
+				$orig_type = gettype($original[ $m_key ]);
+				$m_type = gettype($m_val);
+				if ($orig_type !== $m_type) {
+					throw new \RuntimeException(
+						"Incompatible types. Cannot merge {$m_type} into {$orig_type} (key '{$m_key}').");
+				}
 
-                if (is_array($merging[ $m_key ])) {
-                    $array[ $m_key ] = static::mergeConfig($original[ $m_key ], $m_val);
-                } else {
-                    $array[ $m_key ] = $m_val;
-                }
-            } else {
-                $array[ $m_key ] = $m_val;
-            }
-        }
+				if (is_array($merging[ $m_key ])) {
+					$array[ $m_key ] = static::mergeConfig($original[ $m_key ], $m_val);
+				} else {
+					$array[ $m_key ] = $m_val;
+				}
+			} else {
+				$array[ $m_key ] = $m_val;
+			}
+		}
 
-        return $array;
-    }
+		return $array;
+	}
 
-    /**
-     * Sorts array by value, assuming value is an array and contains `pri` key with integer (positive/negative)
-     * value which is used for sorting higher -> lower priority.
-     *
-     * @param array &$array
-     */
-    public static function sortArrayByPri(array &$array): void
-    {
-        // we now need to sort 'classes' node by priority
-        uasort($array, function($array_a, $array_b) {
-            $pri_a = $array_a['pri'] ?? 0;
-            $pri_b = $array_b['pri'] ?? 0;
+	/**
+	 * Sorts array by value, assuming value is an array and contains `pri` key with integer (positive/negative)
+	 * value which is used for sorting higher -> lower priority.
+	 *
+	 * @param array &$array
+	 */
+	public static function sortArrayByPri(array &$array): void
+	{
+		// we now need to sort 'classes' node by priority
+		uasort($array, function($array_a, $array_b) {
+			$pri_a = $array_a['pri'] ?? 0;
+			$pri_b = $array_b['pri'] ?? 0;
 
-            return $pri_b <=> $pri_a;
-        });
-    }
+			return $pri_b <=> $pri_a;
+		});
+	}
 }

src/ExceptionHandlerHelper.php

Indentation +159 added lines, -159 removed lines

@@ -27,165 +27,165 @@
  */
 class ExceptionHandlerHelper
 {
-    /**
-     * Exception types
-     */
-    public const TYPE_HTTP_NOT_FOUND_KEY           = 'http_not_found';
-    public const TYPE_HTTP_SERVICE_UNAVAILABLE_KEY = 'http_service_unavailable';
-    public const TYPE_HTTP_UNAUTHORIZED_KEY        = 'authentication_exception';
-    public const TYPE_HTTP_EXCEPTION_KEY           = 'http_exception';
-    public const TYPE_VALIDATION_EXCEPTION_KEY     = 'validation_exception';
-    public const TYPE_UNCAUGHT_EXCEPTION_KEY       = 'uncaught_exception';
-    public const TYPE_AUTHENTICATION_EXCEPTION_KEY = 'authentication_exception';
-
-    /**
-     * Render an exception into valid API response.
-     *
-     * @param \Illuminate\Http\Request $request   Request object
-     * @param \Exception               $exception Exception
-     *
-     * @return HttpResponse
-     */
-    public static function render(/** @scrutinizer ignore-unused */ $request, Exception $exception): HttpResponse
-    {
-        $result = null;
-
-        if ($exception instanceof HttpException) {
-            switch ($exception->getStatusCode()) {
-                case HttpResponse::HTTP_NOT_FOUND:
-                    $result = static::error($exception, static::TYPE_HTTP_NOT_FOUND_KEY,
-                        BaseApiCodes::EX_HTTP_NOT_FOUND(), HttpResponse::HTTP_NOT_FOUND);
-                    break;
-
-                case HttpResponse::HTTP_SERVICE_UNAVAILABLE:
-                    $result = static::error($exception, static::TYPE_HTTP_SERVICE_UNAVAILABLE_KEY,
-                        BaseApiCodes::EX_HTTP_SERVICE_UNAVAILABLE(), HttpResponse::HTTP_SERVICE_UNAVAILABLE);
-                    break;
-
-                case HttpResponse::HTTP_UNAUTHORIZED:
-                    $result = static::error($exception, static::TYPE_HTTP_UNAUTHORIZED_KEY,
-                        BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(), HttpResponse::HTTP_UNAUTHORIZED);
-                    break;
-
-                default:
-                    $result = static::error($exception, static::TYPE_HTTP_EXCEPTION_KEY,
-                        BaseApiCodes::EX_HTTP_EXCEPTION(), HttpResponse::HTTP_BAD_REQUEST);
-                    break;
-            }
-        } elseif ($exception instanceof ValidationException) {
-            $result = static::error($exception, static::TYPE_VALIDATION_EXCEPTION_KEY,
-                BaseApiCodes::EX_VALIDATION_EXCEPTION(), HttpResponse::HTTP_BAD_REQUEST);
-        }
-
-        if ($result === null) {
-            $result = static::error($exception, static::TYPE_UNCAUGHT_EXCEPTION_KEY,
-                BaseApiCodes::EX_UNCAUGHT_EXCEPTION(), HttpResponse::HTTP_INTERNAL_SERVER_ERROR);
-        }
-
-        return $result;
-    }
-
-    /**
-     * Convert an authentication exception into an unauthenticated response.
-     *
-     * @param \Illuminate\Http\Request                 $request
-     * @param \Illuminate\Auth\AuthenticationException $exception
-     *
-     * @return HttpResponse
-     */
-    protected function unauthenticated(/** @scrutinizer ignore-unused */ $request,
-                                                                         AuthenticationException $exception): HttpResponse
-    {
-        return static::error($exception, 'authentication_exception', BaseApiCodes::EX_AUTHENTICATION_EXCEPTION());
-    }
-
-    /**
-     * Process singe error and produce valid API response
-     *
-     * @param Exception $exception            Exception to be processed
-     * @param string    $exception_config_key Category of the exception
-     * @param integer   $fallback_api_code    API code to return
-     * @param integer   $fallback_http_code   HTTP code to return
-     *
-     * @return HttpResponse
-     */
-    protected static function error(Exception $exception, $exception_config_key, $fallback_api_code,
-                                    $fallback_http_code = ResponseBuilder::DEFAULT_HTTP_CODE_ERROR): HttpResponse
-    {
-        // common prefix for config key
-        $base_key = sprintf('%s.exception', ResponseBuilder::CONF_EXCEPTION_HANDLER_KEY);
-
-        // get API and HTTP codes from exception handler config or use fallback values if no such
-        // config fields are set.
-        $api_code = Config::get("{$base_key}.{$exception_config_key}.code", $fallback_api_code);
-        $http_code = Config::get("{$base_key}.{$exception_config_key}.http_code", $fallback_http_code);
-
-        // check if we now have valid HTTP error code for this case or need to make one up.
-        if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
-            // no code, let's try to get the exception status
-            $http_code = ($exception instanceof \Symfony\Component\HttpKernel\Exception\HttpException)
-                ? $exception->getStatusCode()
-                : $exception->getCode();
-        }
-
-        // can it be considered valid HTTP error code?
-        if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
-            $http_code = $fallback_http_code;
-        }
-
-        // let's figure out what event we are handling now
-        $known_codes = [
-            self::TYPE_HTTP_NOT_FOUND_KEY           => BaseApiCodes::EX_HTTP_NOT_FOUND(),
-            self::TYPE_HTTP_SERVICE_UNAVAILABLE_KEY => BaseApiCodes::EX_HTTP_SERVICE_UNAVAILABLE(),
-            self::TYPE_UNCAUGHT_EXCEPTION_KEY       => BaseApiCodes::EX_UNCAUGHT_EXCEPTION(),
-            self::TYPE_AUTHENTICATION_EXCEPTION_KEY => BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(),
-            self::TYPE_VALIDATION_EXCEPTION_KEY     => BaseApiCodes::EX_VALIDATION_EXCEPTION(),
-            self::TYPE_HTTP_EXCEPTION_KEY           => BaseApiCodes::EX_HTTP_EXCEPTION(),
-        ];
-        $base_api_code = BaseApiCodes::NO_ERROR_MESSAGE();
-        foreach ($known_codes as $item_config_key => $item_api_code) {
-            if ($api_code === Config::get("{$base_key}.{$item_config_key}.code", $item_api_code)) {
-                $base_api_code = $api_code;
-                break;
-            }
-        }
-
-        /** @var array|null $data Optional payload to return */
-        $data = null;
-        if ($api_code === Config::get("{$base_key}.validation_exception.code", BaseApiCodes::EX_VALIDATION_EXCEPTION())) {
-            /** @var ValidationException $exception */
-            $data = [ResponseBuilder::KEY_MESSAGES => $exception->validator->errors()->messages()];
-        }
-
-        $key = BaseApiCodes::getCodeMessageKey($api_code) ?? BaseApiCodes::getCodeMessageKey($base_api_code);
-
-        // let's build error error_message
-        $error_message = $exception->getMessage();
-
-        // if we do not have any error_message in the hand yet, we need to fall back to built-in string configured
-        // for this particular exception.
-        if ($error_message === '') {
-            $error_message = Lang::get($key, [
-                'api_code' => $api_code,
+	/**
+	 * Exception types
+	 */
+	public const TYPE_HTTP_NOT_FOUND_KEY           = 'http_not_found';
+	public const TYPE_HTTP_SERVICE_UNAVAILABLE_KEY = 'http_service_unavailable';
+	public const TYPE_HTTP_UNAUTHORIZED_KEY        = 'authentication_exception';
+	public const TYPE_HTTP_EXCEPTION_KEY           = 'http_exception';
+	public const TYPE_VALIDATION_EXCEPTION_KEY     = 'validation_exception';
+	public const TYPE_UNCAUGHT_EXCEPTION_KEY       = 'uncaught_exception';
+	public const TYPE_AUTHENTICATION_EXCEPTION_KEY = 'authentication_exception';
+
+	/**
+	 * Render an exception into valid API response.
+	 *
+	 * @param \Illuminate\Http\Request $request   Request object
+	 * @param \Exception               $exception Exception
+	 *
+	 * @return HttpResponse
+	 */
+	public static function render(/** @scrutinizer ignore-unused */ $request, Exception $exception): HttpResponse
+	{
+		$result = null;
+
+		if ($exception instanceof HttpException) {
+			switch ($exception->getStatusCode()) {
+				case HttpResponse::HTTP_NOT_FOUND:
+					$result = static::error($exception, static::TYPE_HTTP_NOT_FOUND_KEY,
+						BaseApiCodes::EX_HTTP_NOT_FOUND(), HttpResponse::HTTP_NOT_FOUND);
+					break;
+
+				case HttpResponse::HTTP_SERVICE_UNAVAILABLE:
+					$result = static::error($exception, static::TYPE_HTTP_SERVICE_UNAVAILABLE_KEY,
+						BaseApiCodes::EX_HTTP_SERVICE_UNAVAILABLE(), HttpResponse::HTTP_SERVICE_UNAVAILABLE);
+					break;
+
+				case HttpResponse::HTTP_UNAUTHORIZED:
+					$result = static::error($exception, static::TYPE_HTTP_UNAUTHORIZED_KEY,
+						BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(), HttpResponse::HTTP_UNAUTHORIZED);
+					break;
+
+				default:
+					$result = static::error($exception, static::TYPE_HTTP_EXCEPTION_KEY,
+						BaseApiCodes::EX_HTTP_EXCEPTION(), HttpResponse::HTTP_BAD_REQUEST);
+					break;
+			}
+		} elseif ($exception instanceof ValidationException) {
+			$result = static::error($exception, static::TYPE_VALIDATION_EXCEPTION_KEY,
+				BaseApiCodes::EX_VALIDATION_EXCEPTION(), HttpResponse::HTTP_BAD_REQUEST);
+		}
+
+		if ($result === null) {
+			$result = static::error($exception, static::TYPE_UNCAUGHT_EXCEPTION_KEY,
+				BaseApiCodes::EX_UNCAUGHT_EXCEPTION(), HttpResponse::HTTP_INTERNAL_SERVER_ERROR);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Convert an authentication exception into an unauthenticated response.
+	 *
+	 * @param \Illuminate\Http\Request                 $request
+	 * @param \Illuminate\Auth\AuthenticationException $exception
+	 *
+	 * @return HttpResponse
+	 */
+	protected function unauthenticated(/** @scrutinizer ignore-unused */ $request,
+																		 AuthenticationException $exception): HttpResponse
+	{
+		return static::error($exception, 'authentication_exception', BaseApiCodes::EX_AUTHENTICATION_EXCEPTION());
+	}
+
+	/**
+	 * Process singe error and produce valid API response
+	 *
+	 * @param Exception $exception            Exception to be processed
+	 * @param string    $exception_config_key Category of the exception
+	 * @param integer   $fallback_api_code    API code to return
+	 * @param integer   $fallback_http_code   HTTP code to return
+	 *
+	 * @return HttpResponse
+	 */
+	protected static function error(Exception $exception, $exception_config_key, $fallback_api_code,
+									$fallback_http_code = ResponseBuilder::DEFAULT_HTTP_CODE_ERROR): HttpResponse
+	{
+		// common prefix for config key
+		$base_key = sprintf('%s.exception', ResponseBuilder::CONF_EXCEPTION_HANDLER_KEY);
+
+		// get API and HTTP codes from exception handler config or use fallback values if no such
+		// config fields are set.
+		$api_code = Config::get("{$base_key}.{$exception_config_key}.code", $fallback_api_code);
+		$http_code = Config::get("{$base_key}.{$exception_config_key}.http_code", $fallback_http_code);
+
+		// check if we now have valid HTTP error code for this case or need to make one up.
+		if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
+			// no code, let's try to get the exception status
+			$http_code = ($exception instanceof \Symfony\Component\HttpKernel\Exception\HttpException)
+				? $exception->getStatusCode()
+				: $exception->getCode();
+		}
+
+		// can it be considered valid HTTP error code?
+		if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
+			$http_code = $fallback_http_code;
+		}
+
+		// let's figure out what event we are handling now
+		$known_codes = [
+			self::TYPE_HTTP_NOT_FOUND_KEY           => BaseApiCodes::EX_HTTP_NOT_FOUND(),
+			self::TYPE_HTTP_SERVICE_UNAVAILABLE_KEY => BaseApiCodes::EX_HTTP_SERVICE_UNAVAILABLE(),
+			self::TYPE_UNCAUGHT_EXCEPTION_KEY       => BaseApiCodes::EX_UNCAUGHT_EXCEPTION(),
+			self::TYPE_AUTHENTICATION_EXCEPTION_KEY => BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(),
+			self::TYPE_VALIDATION_EXCEPTION_KEY     => BaseApiCodes::EX_VALIDATION_EXCEPTION(),
+			self::TYPE_HTTP_EXCEPTION_KEY           => BaseApiCodes::EX_HTTP_EXCEPTION(),
+		];
+		$base_api_code = BaseApiCodes::NO_ERROR_MESSAGE();
+		foreach ($known_codes as $item_config_key => $item_api_code) {
+			if ($api_code === Config::get("{$base_key}.{$item_config_key}.code", $item_api_code)) {
+				$base_api_code = $api_code;
+				break;
+			}
+		}
+
+		/** @var array|null $data Optional payload to return */
+		$data = null;
+		if ($api_code === Config::get("{$base_key}.validation_exception.code", BaseApiCodes::EX_VALIDATION_EXCEPTION())) {
+			/** @var ValidationException $exception */
+			$data = [ResponseBuilder::KEY_MESSAGES => $exception->validator->errors()->messages()];
+		}
+
+		$key = BaseApiCodes::getCodeMessageKey($api_code) ?? BaseApiCodes::getCodeMessageKey($base_api_code);
+
+		// let's build error error_message
+		$error_message = $exception->getMessage();
+
+		// if we do not have any error_message in the hand yet, we need to fall back to built-in string configured
+		// for this particular exception.
+		if ($error_message === '') {
+			$error_message = Lang::get($key, [
+				'api_code' => $api_code,
 				'message'  => '???',
-            ]);
-        }
-
-        // if we have trace data debugging enabled, let's gather some debug
-        // info and add to the response.
-        $trace_data = null;
-        if (Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_ENABLED, false)) {
-            $trace_data = [
-                Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_KEY, ResponseBuilder::KEY_TRACE) => [
-                    ResponseBuilder::KEY_CLASS => get_class($exception),
-                    ResponseBuilder::KEY_FILE  => $exception->getFile(),
-                    ResponseBuilder::KEY_LINE  => $exception->getLine(),
-                ],
-            ];
-        }
-
-        return ResponseBuilder::errorWithMessageAndDataAndDebug($api_code, $error_message, $data,
-            $http_code, null, $trace_data);
-    }
+			]);
+		}
+
+		// if we have trace data debugging enabled, let's gather some debug
+		// info and add to the response.
+		$trace_data = null;
+		if (Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_ENABLED, false)) {
+			$trace_data = [
+				Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_KEY, ResponseBuilder::KEY_TRACE) => [
+					ResponseBuilder::KEY_CLASS => get_class($exception),
+					ResponseBuilder::KEY_FILE  => $exception->getFile(),
+					ResponseBuilder::KEY_LINE  => $exception->getLine(),
+				],
+			];
+		}
+
+		return ResponseBuilder::errorWithMessageAndDataAndDebug($api_code, $error_message, $data,
+			$http_code, null, $trace_data);
+	}
 
 }