MarcinOrlowski / laravel-api-response-builder

src/Converters/ArrayableConverter.php

Indentation +14 added lines, -14 removed lines

@@ -19,19 +19,19 @@
 
 class ArrayableConverter implements ConverterContract
 {
-    /**
-     * Returns array representation of the object implementing Arrayable interface
-     *
-     * @param Arrayable $obj    Object to be converted
-     * @param array     $config Converter config array to be used for this object (based on exact class
-     *                          name match or inheritance).
-     *
-     * @return array
-     */
-    public function convert($obj, array /** @scrutinizer ignore-unused */ $config): array
-    {
-        Validator::assertInstanceOf('obj', $obj, Arrayable::class);
+	/**
+	 * Returns array representation of the object implementing Arrayable interface
+	 *
+	 * @param Arrayable $obj    Object to be converted
+	 * @param array     $config Converter config array to be used for this object (based on exact class
+	 *                          name match or inheritance).
+	 *
+	 * @return array
+	 */
+	public function convert($obj, array /** @scrutinizer ignore-unused */ $config): array
+	{
+		Validator::assertInstanceOf('obj', $obj, Arrayable::class);
 
-        return $obj->toArray();
-    }
+		return $obj->toArray();
+	}
 }

src/Converters/JsonSerializableConverter.php

Indentation +14 added lines, -14 removed lines

@@ -19,19 +19,19 @@
 
 class JsonSerializableConverter implements ConverterContract
 {
-    /**
-     * Returns array representation of the object implementing \JsonSerializable interface.
-     *
-     * @param \JsonSerializable $obj    Object to be converted
-     * @param array             $config Converter config array to be used for this object (based on exact class
-     *                                  name match or inheritance).
-     *
-     * @return array
-     */
-    public function convert($obj, array /** @scrutinizer ignore-unused */ $config): array
-    {
-        Validator::assertInstanceOf('obj', $obj, \JsonSerializable::class);
+	/**
+	 * Returns array representation of the object implementing \JsonSerializable interface.
+	 *
+	 * @param \JsonSerializable $obj    Object to be converted
+	 * @param array             $config Converter config array to be used for this object (based on exact class
+	 *                                  name match or inheritance).
+	 *
+	 * @return array
+	 */
+	public function convert($obj, array /** @scrutinizer ignore-unused */ $config): array
+	{
+		Validator::assertInstanceOf('obj', $obj, \JsonSerializable::class);
 
-        return ['val' => json_decode($obj->jsonSerialize(), true)];
-    }
+		return ['val' => json_decode($obj->jsonSerialize(), true)];
+	}
 }

config/response_builder.php

Indentation +80 added lines, -80 removed lines

@@ -12,78 +12,78 @@ 
  */
 
 return [
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | Code range settings
     |-----------------------------------------------------------------------------------------------------------
     */
-    'min_code'          => 100,
-    'max_code'          => 1024,
+	'min_code'          => 100,
+	'max_code'          => 1024,
 
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | Error code to message mapping
     |-----------------------------------------------------------------------------------------------------------
     |
     */
-    'map'               => [
-        // YOUR_API_CODE => '<MESSAGE_KEY>',
-    ],
+	'map'               => [
+		// YOUR_API_CODE => '<MESSAGE_KEY>',
+	],
 
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | Response Builder data converter
     |-----------------------------------------------------------------------------------------------------------
     |
     */
-    'converter'         => [
-        \Illuminate\Database\Eloquent\Model::class          => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
-            // 'key'     => 'item',
-            'pri'     => 0,
-        ],
-        \Illuminate\Support\Collection::class               => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
-            // 'key'     => 'item',
-            'pri'     => 0,
-        ],
-        \Illuminate\Database\Eloquent\Collection::class     => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
-            // 'key'     => 'item',
-            'pri'     => 0,
-        ],
-        \Illuminate\Http\Resources\Json\JsonResource::class => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
-            // 'key'     => 'item',
-            'pri'     => 0,
-        ],
+	'converter'         => [
+		\Illuminate\Database\Eloquent\Model::class          => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+			// 'key'     => 'item',
+			'pri'     => 0,
+		],
+		\Illuminate\Support\Collection::class               => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+			// 'key'     => 'item',
+			'pri'     => 0,
+		],
+		\Illuminate\Database\Eloquent\Collection::class     => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+			// 'key'     => 'item',
+			'pri'     => 0,
+		],
+		\Illuminate\Http\Resources\Json\JsonResource::class => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+			// 'key'     => 'item',
+			'pri'     => 0,
+		],
 
-        /*
+		/*
         |-----------------------------------------------------------------------------------------------------------
         | Converters for generic classes should use lower priority to allow dedicated converters to be used.
         |-----------------------------------------------------------------------------------------------------------
         */
-        \JsonSerializable::class                            => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\JsonSerializableConverter::class,
-            // 'key'     => 'item',
-            'pri'     => -10,
-        ],
-        \Illuminate\Contracts\Support\Arrayable::class      => [
-            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ArrayableConverter::class,
-            // 'key'     => 'item',
-            'pri'     => -10,
-        ],
+		\JsonSerializable::class                            => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\JsonSerializableConverter::class,
+			// 'key'     => 'item',
+			'pri'     => -10,
+		],
+		\Illuminate\Contracts\Support\Arrayable::class      => [
+			'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ArrayableConverter::class,
+			// 'key'     => 'item',
+			'pri'     => -10,
+		],
 
-    ],
+	],
 
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | Exception handler error codes
     |-----------------------------------------------------------------------------------------------------------
     |
     */
-    'exception_handler' => [
-        /*
+	'exception_handler' => [
+		/*
          * The following options can be used for each entry specified:
          * `api_code`   : (int) mandatory api_code to be used for given exception
          * `http_code`  : (int) optional HTTP code. If not specified, exception's HTTP status code will be used.
@@ -96,8 +96,8 @@ 
          *                `msg_key` is set, or message referenced by `msg_key` completely ignoring exception
          *                message ($ex->getMessage()).
          */
-        'map' => [
-            /*
+		'map' => [
+			/*
              * HTTP Exceptions
              * ---------------
              * Configure how you want Http Exception to be handled based on its Http status code.
@@ -105,51 +105,51 @@ 
              * Additionally, you can specify `http_code` to be any valid 400-599 HTTP status code, otherwise
              * code set in the exception will be used.
              */
-            //            HttpException::class => [
-            //                // used by unauthenticated() to obtain api and http code for the exception
-            //                HttpResponse::HTTP_UNAUTHORIZED         => [
-            //                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_UNATHORIZED_EXCEPTION,
-            //                ],
-            //                // Required by ValidationException handler
-            //                HttpResponse::HTTP_UNPROCESSABLE_ENTITY => [
-            //                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_VALIDATION_EXCEPTION,
-            //                ],
-            //                // default handler is mandatory and MUST have both `api_code` and `http_code` set.
-            //                'default'                               => [
-            //                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_GENERIC_HTTP_EXCEPTION,
-            //                    'http_code' => HttpResponse::HTTP_BAD_REQUEST,
-            //                ],
-            //            ],
-            //            // This is final exception handler. If ex is not dealt with yet this is its last stop.
-            //            // default handler is mandatory and MUST have both `api_code` and `http_code` set.
-            //            'default'            => [
-            //                'api_code'  => ApiCodes::YOUR_API_CODE_FOR_UNHANDLED_EXCEPTION,
-            //                'http_code' => HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
-            //            ],
-            //        ],
-        ],
-    ],
+			//            HttpException::class => [
+			//                // used by unauthenticated() to obtain api and http code for the exception
+			//                HttpResponse::HTTP_UNAUTHORIZED         => [
+			//                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_UNATHORIZED_EXCEPTION,
+			//                ],
+			//                // Required by ValidationException handler
+			//                HttpResponse::HTTP_UNPROCESSABLE_ENTITY => [
+			//                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_VALIDATION_EXCEPTION,
+			//                ],
+			//                // default handler is mandatory and MUST have both `api_code` and `http_code` set.
+			//                'default'                               => [
+			//                    'api_code'  => ApiCodes::YOUR_API_CODE_FOR_GENERIC_HTTP_EXCEPTION,
+			//                    'http_code' => HttpResponse::HTTP_BAD_REQUEST,
+			//                ],
+			//            ],
+			//            // This is final exception handler. If ex is not dealt with yet this is its last stop.
+			//            // default handler is mandatory and MUST have both `api_code` and `http_code` set.
+			//            'default'            => [
+			//                'api_code'  => ApiCodes::YOUR_API_CODE_FOR_UNHANDLED_EXCEPTION,
+			//                'http_code' => HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+			//            ],
+			//        ],
+		],
+	],
 
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | data-to-json encoding options
     |-----------------------------------------------------------------------------------------------------------
     |
     */
-    'encoding_options'  => JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE,
+	'encoding_options'  => JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT | JSON_UNESCAPED_UNICODE,
 
-    /*
+	/*
     |-----------------------------------------------------------------------------------------------------------
     | Debug config
     |-----------------------------------------------------------------------------------------------------------
     |
     */
-    'debug'             => [
-        'debug_key'         => 'debug',
-        'exception_handler' => [
-            'trace_key'     => 'trace',
-            'trace_enabled' => env('APP_DEBUG', false),
-        ],
-    ],
+	'debug'             => [
+		'debug_key'         => 'debug',
+		'exception_handler' => [
+			'trace_key'     => 'trace',
+			'trace_enabled' => env('APP_DEBUG', false),
+		],
+	],
 
 ];

src/Converter.php

Indentation +169 added lines, -169 removed lines

@@ -22,173 +22,173 @@
  */
 class Converter
 {
-    /**
-     * @var array
-     */
-    protected $classes = [];
-
-    /**
-     * Converter constructor.
-     *
-     * @throws \RuntimeException
-     */
-    public function __construct()
-    {
-        $this->classes = static::getClassesMapping() ?? [];
-    }
-
-    /**
-     * 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->getClasses()) 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;
-        }
-
-        Validator::assertIsType('data', $data, [Validator::TYPE_ARRAY,
-                                                Validator::TYPE_OBJECT]);
-
-        if (is_object($data)) {
-            $cfg = $this->getClassMappingConfigOrThrow($data);
-            $worker = new $cfg[ ResponseBuilder::KEY_HANDLER ]();
-            $data = $worker->convert($data, $cfg);
-        } else {
-            $data = $this->convertArray($data);
-        }
-
-        return $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)) {
-                $cfg = $this->getClassMappingConfigOrThrow($val);
-                $worker = new $cfg[ ResponseBuilder::KEY_HANDLER ]();
-                $converted_data = $worker->convert($val, $cfg);
-                $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_CONVERTER);
-
-        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_HANDLER,
-            ];
-            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()
+	{
+		$this->classes = static::getClassesMapping() ?? [];
+	}
+
+	/**
+	 * 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->getClasses()) 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;
+		}
+
+		Validator::assertIsType('data', $data, [Validator::TYPE_ARRAY,
+												Validator::TYPE_OBJECT]);
+
+		if (is_object($data)) {
+			$cfg = $this->getClassMappingConfigOrThrow($data);
+			$worker = new $cfg[ ResponseBuilder::KEY_HANDLER ]();
+			$data = $worker->convert($data, $cfg);
+		} else {
+			$data = $this->convertArray($data);
+		}
+
+		return $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)) {
+				$cfg = $this->getClassMappingConfigOrThrow($val);
+				$worker = new $cfg[ ResponseBuilder::KEY_HANDLER ]();
+				$converted_data = $worker->convert($val, $cfg);
+				$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_CONVERTER);
+
+		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_HANDLER,
+			];
+			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/ExceptionHandlerHelper.php

Indentation +219 added lines, -219 removed lines

@@ -27,224 +27,224 @@
  */
 class ExceptionHandlerHelper
 {
-    /**
-     * Render an exception into valid API response.
-     *
-     * @param \Illuminate\Http\Request $request Request object
-     * @param \Exception               $ex      Exception
-     *
-     * @return HttpResponse
-     */
-    public static function render(/** @scrutinizer ignore-unused */ $request, Exception $ex): HttpResponse
-    {
-        $result = null;
-        $cfg = static::getExceptionHandlerConfig()['map'];
-
-        if ($ex instanceof HttpException) {
-            // Check if we have any exception configuration for this particular Http status code.
-            // This confing entry is guaranted to exist (at least 'default'). Enforced by tests.
-            $http_code = $ex->getStatusCode();
-            $ex_cfg = $cfg[ HttpException::class ][ $http_code ] ?? null;
-            $ex_cfg = $ex_cfg ?? $cfg[ HttpException::class ]['default'];
-            $result = self::processException($ex, $ex_cfg, $http_code);
-        } elseif ($ex instanceof ValidationException) {
-            // This entry is guaranted to exist. Enforced by tests.
-            $http_code = HttpResponse::HTTP_UNPROCESSABLE_ENTITY;
-            $ex_cfg = $cfg[ HttpException::class ][ $http_code ];
-            $result = self::processException($ex, $ex_cfg, $http_code);
-        }
-
-        if ($result === null) {
-            // This entry is guaranted to exist. Enforced by tests.
-            $http_code = HttpResponse::HTTP_INTERNAL_SERVER_ERROR;
-            $ex_cfg = $cfg['default'];
-            $result = self::processException($ex, $ex_cfg, $http_code);
-        }
-
-        return $result;
-    }
-
-    protected static function processException(\Exception $ex, array $ex_cfg, int $http_code)
-    {
-        $api_code = $ex_cfg['api_code'];
-        $http_code = $ex_cfg['http_code'] ?? $http_code;
-        $msg_key = $ex_cfg['msg_key'] ?? null;
-        $msg_enforce = $ex_cfg['msg_enforce'] ?? false;
-
-        // No message key, let's get exception message and if there's nothing useful, fallback to built-in one.
-        $error_message = $ex->getMessage();
-        $placeholders = [
-            'api_code' => $api_code,
-            'message'  => ($error_message !== '') ? $error_message : '???',
-        ];
-
-        // shall we enforce error message?
-        if ($msg_enforce) {
-            // yes, please.
-            if ($msg_key === null) {
-                // there's no msg_key configured for this exact code, so let's obtain our default message
-                $error_message = ($msg_key === null) ? static::getErrorMessageForException($ex, $http_code, $placeholders) : Lang::get($msg_key, $placeholders);
-            }
-        } else {
-            // nothing enforced, handling pipeline: ex_message -> user_defined msg -> http_ex -> default
-            if ($error_message === '') {
-                $error_message = ($msg_key === null) ? static::getErrorMessageForException($ex, $http_code, $placeholders) : Lang::get($msg_key, $placeholders);
-            }
-        }
-
-        // Lets' try to build the error response with what we have now
-        $result = static::error($ex, $api_code, $http_code, $error_message);
-
-        if ($result === null) {
-            $ex_cfg = $cfg[ HttpException::class ][ $http_code ];
-            $api_code = $ex_cfg['api_code'] ?? BaseApiCodes::EX_VALIDATION_EXCEPTION();
-            $http_code = $ex_cfg['http_code'] ?? $http_code;
-            $result = static::error($ex, $api_code, $http_code, $error_message);
-        }
-
-        return $result;
-    }
-
-    /**
-     * Returns error message for given exception. If exception message is empty, then falls back to
-     * `default` handler either for HttpException (if $ex is instance of it), or generic `default`
-     * config.
-     *
-     * @param \Exception $ex
-     * @param int        $http_code
-     * @param array      $placeholders
-     *
-     * @return string
-     */
-    protected static function getErrorMessageForException(\Exception $ex, int $http_code, array $placeholders): string
-    {
-        // exception message is uselss, lets go deeper
-        if ($ex instanceof HttpException) {
-            $error_message = Lang::get("response-builder::builder.http_{$http_code}", $placeholders);
-        } else {
-            // Still got nothing? Fall back to built-in generic message for this type of exception.
-            $key = BaseApiCodes::getCodeMessageKey(($ex instanceof HttpException)
-                ? BaseApiCodes::EX_HTTP_EXCEPTION() : BaseApiCodes::NO_ERROR_MESSAGE());
-            $error_message = Lang::get($key, $placeholders);
-        }
-
-        return $error_message;
-    }
-
-    /**
-     * 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,
-                                                                         AuthException $exception): HttpResponse
-    {
-        // This entry is guaranted to exist. Enforced by tests.
-        $http_code = HttpResponse::HTTP_UNAUTHORIZED;
-        $cfg = static::getExceptionHandlerConfig()['map'][ HttpException::class ][ $http_code ];
-
-        return static::processException($exception, $cfg, $http_code);
-    }
-
-    /**
-     * Process single error and produce valid API response.
-     *
-     * @param Exception $ex Exception to be handled.
-     * @param integer   $api_code
-     * @param integer   $http_code
-     *
-     * @return HttpResponse
-     */
-    protected static function error(Exception $ex,
-                                    int $api_code, int $http_code = null, string $error_message): HttpResponse
-    {
-        $ex_http_code = ($ex instanceof HttpException) ? $ex->getStatusCode() : $ex->getCode();
-        $http_code = $http_code ?? $ex_http_code;
-
-        // Check if we now have valid HTTP error code for this case or need to make one up.
-        // We cannot throw any exception if codes are invalid because we are in Exception Handler already.
-        if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
-            // Not a valid code, let's try to get the exception status.
-            $http_code = $ex_http_code;
-        }
-        // Can it be considered a valid HTTP error code?
-        if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
-            // We now handle uncaught exception, so we cannot throw another one if there's
-            // something wrong with the configuration, so we try to recover and use built-in
-            // codes instead.
-            // FIXME: We should log this event as (warning or error?)
-            $http_code = ResponseBuilder::DEFAULT_HTTP_CODE_ERROR;
-        }
-
-        // If we have trace data debugging enabled, let's gather some debug info and add to the response.
-        $debug_data = null;
-        if (Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_ENABLED, false)) {
-            $debug_data = [
-                Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_KEY, ResponseBuilder::KEY_TRACE) => [
-                    ResponseBuilder::KEY_CLASS => get_class($ex),
-                    ResponseBuilder::KEY_FILE  => $ex->getFile(),
-                    ResponseBuilder::KEY_LINE  => $ex->getLine(),
-                ],
-            ];
-        }
-
-        // If this is ValidationException, add all the messages from MessageBag to the data node.
-        $data = null;
-        if ($ex instanceof ValidationException) {
-            /** @var ValidationException $ex */
-            $data = [ResponseBuilder::KEY_MESSAGES => $ex->validator->errors()->messages()];
-        }
-
-        return ResponseBuilder::asError($api_code)
-            ->withMessage($error_message)
-            ->withHttpCode($http_code)
-            ->withData($data)
-            ->withDebugData($debug_data)
-            ->build();
-    }
-
-    protected
-    static function getExceptionHandlerDefaultConfig(): array
-    {
-        return [
-            'map' => [
-                HttpException::class => [
-                    // used by unauthenticated() to obtain api and http code for the exception
-                    HttpResponse::HTTP_UNAUTHORIZED         => [
-                        'api_code' => BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(),
-                    ],
-                    // Required by ValidationException handler
-                    HttpResponse::HTTP_UNPROCESSABLE_ENTITY => [
-                        'api_code' => BaseApiCodes::EX_VALIDATION_EXCEPTION(),
-                    ],
-                    // default handler is mandatory. `default` entry MUST have both `api_code` and `http_code` set.
-                    'default'                               => [
-                        'api_code'  => BaseApiCodes::EX_HTTP_EXCEPTION(),
-                        'http_code' => HttpResponse::HTTP_BAD_REQUEST,
-                    ],
-                ],
-                // default handler is mandatory. `default` entry MUST have both `api_code` and `http_code` set.
-                'default'            => [
-                    'api_code'  => BaseApiCodes::EX_UNCAUGHT_EXCEPTION(),
-                    'http_code' => HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
-                ],
-            ],
-        ];
-    }
-
-    /**
-     * Returns ExceptionHandlerHelper configration array with user configuration merged into built-in defaults.
-     *
-     * @return array
-     */
-    protected
-    static function getExceptionHandlerConfig(): array
-    {
-        return Util::mergeConfig(static::getExceptionHandlerDefaultConfig(),
-            \Config::get(ResponseBuilder::CONF_KEY_EXCEPTION_HANDLER, []));
-    }
+	/**
+	 * Render an exception into valid API response.
+	 *
+	 * @param \Illuminate\Http\Request $request Request object
+	 * @param \Exception               $ex      Exception
+	 *
+	 * @return HttpResponse
+	 */
+	public static function render(/** @scrutinizer ignore-unused */ $request, Exception $ex): HttpResponse
+	{
+		$result = null;
+		$cfg = static::getExceptionHandlerConfig()['map'];
+
+		if ($ex instanceof HttpException) {
+			// Check if we have any exception configuration for this particular Http status code.
+			// This confing entry is guaranted to exist (at least 'default'). Enforced by tests.
+			$http_code = $ex->getStatusCode();
+			$ex_cfg = $cfg[ HttpException::class ][ $http_code ] ?? null;
+			$ex_cfg = $ex_cfg ?? $cfg[ HttpException::class ]['default'];
+			$result = self::processException($ex, $ex_cfg, $http_code);
+		} elseif ($ex instanceof ValidationException) {
+			// This entry is guaranted to exist. Enforced by tests.
+			$http_code = HttpResponse::HTTP_UNPROCESSABLE_ENTITY;
+			$ex_cfg = $cfg[ HttpException::class ][ $http_code ];
+			$result = self::processException($ex, $ex_cfg, $http_code);
+		}
+
+		if ($result === null) {
+			// This entry is guaranted to exist. Enforced by tests.
+			$http_code = HttpResponse::HTTP_INTERNAL_SERVER_ERROR;
+			$ex_cfg = $cfg['default'];
+			$result = self::processException($ex, $ex_cfg, $http_code);
+		}
+
+		return $result;
+	}
+
+	protected static function processException(\Exception $ex, array $ex_cfg, int $http_code)
+	{
+		$api_code = $ex_cfg['api_code'];
+		$http_code = $ex_cfg['http_code'] ?? $http_code;
+		$msg_key = $ex_cfg['msg_key'] ?? null;
+		$msg_enforce = $ex_cfg['msg_enforce'] ?? false;
+
+		// No message key, let's get exception message and if there's nothing useful, fallback to built-in one.
+		$error_message = $ex->getMessage();
+		$placeholders = [
+			'api_code' => $api_code,
+			'message'  => ($error_message !== '') ? $error_message : '???',
+		];
+
+		// shall we enforce error message?
+		if ($msg_enforce) {
+			// yes, please.
+			if ($msg_key === null) {
+				// there's no msg_key configured for this exact code, so let's obtain our default message
+				$error_message = ($msg_key === null) ? static::getErrorMessageForException($ex, $http_code, $placeholders) : Lang::get($msg_key, $placeholders);
+			}
+		} else {
+			// nothing enforced, handling pipeline: ex_message -> user_defined msg -> http_ex -> default
+			if ($error_message === '') {
+				$error_message = ($msg_key === null) ? static::getErrorMessageForException($ex, $http_code, $placeholders) : Lang::get($msg_key, $placeholders);
+			}
+		}
+
+		// Lets' try to build the error response with what we have now
+		$result = static::error($ex, $api_code, $http_code, $error_message);
+
+		if ($result === null) {
+			$ex_cfg = $cfg[ HttpException::class ][ $http_code ];
+			$api_code = $ex_cfg['api_code'] ?? BaseApiCodes::EX_VALIDATION_EXCEPTION();
+			$http_code = $ex_cfg['http_code'] ?? $http_code;
+			$result = static::error($ex, $api_code, $http_code, $error_message);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Returns error message for given exception. If exception message is empty, then falls back to
+	 * `default` handler either for HttpException (if $ex is instance of it), or generic `default`
+	 * config.
+	 *
+	 * @param \Exception $ex
+	 * @param int        $http_code
+	 * @param array      $placeholders
+	 *
+	 * @return string
+	 */
+	protected static function getErrorMessageForException(\Exception $ex, int $http_code, array $placeholders): string
+	{
+		// exception message is uselss, lets go deeper
+		if ($ex instanceof HttpException) {
+			$error_message = Lang::get("response-builder::builder.http_{$http_code}", $placeholders);
+		} else {
+			// Still got nothing? Fall back to built-in generic message for this type of exception.
+			$key = BaseApiCodes::getCodeMessageKey(($ex instanceof HttpException)
+				? BaseApiCodes::EX_HTTP_EXCEPTION() : BaseApiCodes::NO_ERROR_MESSAGE());
+			$error_message = Lang::get($key, $placeholders);
+		}
+
+		return $error_message;
+	}
+
+	/**
+	 * 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,
+																		 AuthException $exception): HttpResponse
+	{
+		// This entry is guaranted to exist. Enforced by tests.
+		$http_code = HttpResponse::HTTP_UNAUTHORIZED;
+		$cfg = static::getExceptionHandlerConfig()['map'][ HttpException::class ][ $http_code ];
+
+		return static::processException($exception, $cfg, $http_code);
+	}
+
+	/**
+	 * Process single error and produce valid API response.
+	 *
+	 * @param Exception $ex Exception to be handled.
+	 * @param integer   $api_code
+	 * @param integer   $http_code
+	 *
+	 * @return HttpResponse
+	 */
+	protected static function error(Exception $ex,
+									int $api_code, int $http_code = null, string $error_message): HttpResponse
+	{
+		$ex_http_code = ($ex instanceof HttpException) ? $ex->getStatusCode() : $ex->getCode();
+		$http_code = $http_code ?? $ex_http_code;
+
+		// Check if we now have valid HTTP error code for this case or need to make one up.
+		// We cannot throw any exception if codes are invalid because we are in Exception Handler already.
+		if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
+			// Not a valid code, let's try to get the exception status.
+			$http_code = $ex_http_code;
+		}
+		// Can it be considered a valid HTTP error code?
+		if ($http_code < ResponseBuilder::ERROR_HTTP_CODE_MIN) {
+			// We now handle uncaught exception, so we cannot throw another one if there's
+			// something wrong with the configuration, so we try to recover and use built-in
+			// codes instead.
+			// FIXME: We should log this event as (warning or error?)
+			$http_code = ResponseBuilder::DEFAULT_HTTP_CODE_ERROR;
+		}
+
+		// If we have trace data debugging enabled, let's gather some debug info and add to the response.
+		$debug_data = null;
+		if (Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_ENABLED, false)) {
+			$debug_data = [
+				Config::get(ResponseBuilder::CONF_KEY_DEBUG_EX_TRACE_KEY, ResponseBuilder::KEY_TRACE) => [
+					ResponseBuilder::KEY_CLASS => get_class($ex),
+					ResponseBuilder::KEY_FILE  => $ex->getFile(),
+					ResponseBuilder::KEY_LINE  => $ex->getLine(),
+				],
+			];
+		}
+
+		// If this is ValidationException, add all the messages from MessageBag to the data node.
+		$data = null;
+		if ($ex instanceof ValidationException) {
+			/** @var ValidationException $ex */
+			$data = [ResponseBuilder::KEY_MESSAGES => $ex->validator->errors()->messages()];
+		}
+
+		return ResponseBuilder::asError($api_code)
+			->withMessage($error_message)
+			->withHttpCode($http_code)
+			->withData($data)
+			->withDebugData($debug_data)
+			->build();
+	}
+
+	protected
+	static function getExceptionHandlerDefaultConfig(): array
+	{
+		return [
+			'map' => [
+				HttpException::class => [
+					// used by unauthenticated() to obtain api and http code for the exception
+					HttpResponse::HTTP_UNAUTHORIZED         => [
+						'api_code' => BaseApiCodes::EX_AUTHENTICATION_EXCEPTION(),
+					],
+					// Required by ValidationException handler
+					HttpResponse::HTTP_UNPROCESSABLE_ENTITY => [
+						'api_code' => BaseApiCodes::EX_VALIDATION_EXCEPTION(),
+					],
+					// default handler is mandatory. `default` entry MUST have both `api_code` and `http_code` set.
+					'default'                               => [
+						'api_code'  => BaseApiCodes::EX_HTTP_EXCEPTION(),
+						'http_code' => HttpResponse::HTTP_BAD_REQUEST,
+					],
+				],
+				// default handler is mandatory. `default` entry MUST have both `api_code` and `http_code` set.
+				'default'            => [
+					'api_code'  => BaseApiCodes::EX_UNCAUGHT_EXCEPTION(),
+					'http_code' => HttpResponse::HTTP_INTERNAL_SERVER_ERROR,
+				],
+			],
+		];
+	}
+
+	/**
+	 * Returns ExceptionHandlerHelper configration array with user configuration merged into built-in defaults.
+	 *
+	 * @return array
+	 */
+	protected
+	static function getExceptionHandlerConfig(): array
+	{
+		return Util::mergeConfig(static::getExceptionHandlerDefaultConfig(),
+			\Config::get(ResponseBuilder::CONF_KEY_EXCEPTION_HANDLER, []));
+	}
 
 }

src/ResponseBuilderBase.php

Indentation +70 added lines, -70 removed lines

@@ -19,81 +19,81 @@
 
 abstract class ResponseBuilderBase
 {
-    /**
-     * 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 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;
+	/**
+	 * 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;
+	/**
+	 * 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;
+	/**
+	 * Max allowed HTTP code for errorXXX()
+	 *
+	 * @var int
+	 */
+	public const ERROR_HTTP_CODE_MAX = 599;
 
-    /**
-     * Configuration keys
-     */
-    public const CONF_CONFIG                     = 'response_builder';
-    public const CONF_KEY_DEBUG_DEBUG_KEY        = self::CONF_CONFIG . '.debug.debug_key';
-    public const CONF_KEY_DEBUG_EX_TRACE_ENABLED = self::CONF_CONFIG . '.debug.exception_handler.trace_enabled';
-    public const CONF_KEY_DEBUG_EX_TRACE_KEY     = self::CONF_CONFIG . '.debug.exception_handler.trace_key';
-    public const CONF_KEY_MAP                    = self::CONF_CONFIG . '.map';
-    public const CONF_KEY_ENCODING_OPTIONS       = self::CONF_CONFIG . '.encoding_options';
-    public const CONF_KEY_CONVERTER              = self::CONF_CONFIG . '.converter';
-    public const CONF_KEY_MIN_CODE               = self::CONF_CONFIG . '.min_code';
-    public const CONF_KEY_MAX_CODE               = self::CONF_CONFIG . '.max_code';
-    public const CONF_KEY_EXCEPTION_HANDLER      = self::CONF_CONFIG . '.exception_handler';
+	/**
+	 * Configuration keys
+	 */
+	public const CONF_CONFIG                     = 'response_builder';
+	public const CONF_KEY_DEBUG_DEBUG_KEY        = self::CONF_CONFIG . '.debug.debug_key';
+	public const CONF_KEY_DEBUG_EX_TRACE_ENABLED = self::CONF_CONFIG . '.debug.exception_handler.trace_enabled';
+	public const CONF_KEY_DEBUG_EX_TRACE_KEY     = self::CONF_CONFIG . '.debug.exception_handler.trace_key';
+	public const CONF_KEY_MAP                    = self::CONF_CONFIG . '.map';
+	public const CONF_KEY_ENCODING_OPTIONS       = self::CONF_CONFIG . '.encoding_options';
+	public const CONF_KEY_CONVERTER              = self::CONF_CONFIG . '.converter';
+	public const CONF_KEY_MIN_CODE               = self::CONF_CONFIG . '.min_code';
+	public const CONF_KEY_MAX_CODE               = self::CONF_CONFIG . '.max_code';
+	public const CONF_KEY_EXCEPTION_HANDLER      = self::CONF_CONFIG . '.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_PRI     = 'pri';
-    public const KEY_HANDLER = 'handler';
-    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 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_PRI     = 'pri';
+	public const KEY_HANDLER = 'handler';
+	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 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;
+	/**
+	 * 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;
 }

src/ResponseBuilder.php

Indentation +330 added lines, -330 removed lines

@@ -25,338 +25,338 @@
 class ResponseBuilder extends ResponseBuilderBase
 {
 
-    /** @var bool */
-    protected $success = false;
-
-    /** @var int|null */
-    protected $api_code = null;
-
-    /** @var int|null */
-    protected $http_code = null;
-
-    /** @var mixed */
-    protected $data = null;
-
-    /** @var string */
-    protected $message = null;
-
-    /** @var array */
-    protected $placeholders = [];
-
-    /** @var int|null */
-    protected $json_opts = null;
-
-    /** @var array */
-    protected $debug_data = [];
-
-    /** @var array */
-    protected $http_headers = [];
-
-    // -----------------------------------------------------------------------------------------------------------
-
-    /**
-     * Private constructor. Use asSuccess() and asError() static methods to obtain instance of Builder.
-     *
-     * @param bool $success
-     * @param int  $api_code
-     */
-    protected function __construct(bool $success, int $api_code)
-    {
-        $this->success = $success;
-        $this->api_code = $api_code;
-    }
-
-    // -----------------------------------------------------------------------------------------------------------
-
-    /**
-     * 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 ResponseBuilder::asSuccess($api_code)
-            ->withData($data)
-            ->withPlaceholders($placeholders)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
-
-    /**
-     * 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 $json_opts = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withPlaceholders($placeholders)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/** @var bool */
+	protected $success = false;
+
+	/** @var int|null */
+	protected $api_code = null;
+
+	/** @var int|null */
+	protected $http_code = null;
+
+	/** @var mixed */
+	protected $data = null;
+
+	/** @var string */
+	protected $message = null;
+
+	/** @var array */
+	protected $placeholders = [];
+
+	/** @var int|null */
+	protected $json_opts = null;
+
+	/** @var array */
+	protected $debug_data = [];
+
+	/** @var array */
+	protected $http_headers = [];
+
+	// -----------------------------------------------------------------------------------------------------------
+
+	/**
+	 * Private constructor. Use asSuccess() and asError() static methods to obtain instance of Builder.
+	 *
+	 * @param bool $success
+	 * @param int  $api_code
+	 */
+	protected function __construct(bool $success, int $api_code)
+	{
+		$this->success = $success;
+		$this->api_code = $api_code;
+	}
+
+	// -----------------------------------------------------------------------------------------------------------
+
+	/**
+	 * 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 ResponseBuilder::asSuccess($api_code)
+			->withData($data)
+			->withPlaceholders($placeholders)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->build();
+	}
+
+	/**
+	 * 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 $json_opts = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withPlaceholders($placeholders)
+			->withData($data)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
 // -----------------------------------------------------------------------------------------------------------
 
-    public static function asSuccess(int $api_code = null): self
-    {
-        return new self(true, $api_code ?? BaseApiCodes::OK());
-    }
+	public static function asSuccess(int $api_code = null): self
+	{
+		return new self(true, $api_code ?? BaseApiCodes::OK());
+	}
 
-    public static function asError(int $api_code): self
-    {
-        $code_ok = BaseApiCodes::OK();
-        if ($api_code !== $code_ok) {
-            Validator::assertIsIntRange('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");
-        }
-
-        return new self(false, $api_code);
-    }
-
-    public function withHttpCode(int $http_code = null): self
-    {
-        Validator::assertIsType('http_code', $http_code, [Validator::TYPE_INTEGER,
-                                                          Validator::TYPE_NULL]);
-        $this->http_code = $http_code;
-
-        return $this;
-    }
-
-    public function withData($data = null): self
-    {
-        Validator::assertIsType('data', $data, [Validator::TYPE_ARRAY,
-                                                Validator::TYPE_OBJECT,
-                                                Validator::TYPE_NULL]);
-        $this->data = $data;
-
-        return $this;
-    }
-
-    public function withJsonOptions(int $json_opts = null): self
-    {
-        Validator::assertIsType('json_opts', $json_opts, [Validator::TYPE_INTEGER,
-                                                          Validator::TYPE_NULL]);
-        $this->json_opts = $json_opts;
-
-        return $this;
-    }
-
-    public function withDebugData(array $debug_data = null): self
-    {
-        Validator::assertIsType('$debug_data', $debug_data, [Validator::TYPE_ARRAY,
-                                                             Validator::TYPE_NULL]);
-        $this->debug_data = $debug_data;
-
-        return $this;
-    }
-
-    public function withMessage(string $msg = null): self
-    {
-        Validator::assertIsType('message', $msg, [Validator::TYPE_STRING,
-                                                  Validator::TYPE_NULL]);
-        $this->message = $msg;
-
-        return $this;
-    }
-
-    public function withPlaceholders(array $placeholders = null): self
-    {
-        $this->placeholders = $placeholders;
-
-        return $this;
-    }
-
-    public function withHttpHeaders(array $http_headers = null): self
-    {
-        $this->http_headers = $http_headers ?? [];
-
-        return $this;
-    }
-
-    public function build(): HttpResponse
-    {
-        $api_code = $this->api_code;
-        Validator::assertIsInt('api_code', $api_code);
-
-        $msg_or_api_code = $this->message ?? $api_code;
-        $http_headers = $this->http_headers ?? [];
-
-        if ($this->success) {
-            $api_code = $api_code ?? BaseApiCodes::OK();
-            $http_code = $this->http_code ?? ResponseBuilder::DEFAULT_HTTP_CODE_OK;
-
-            Validator::assertOkHttpCode($http_code);
-
-            $result = $this->make($this->success, $api_code, $msg_or_api_code, $this->data, $http_code,
-                $this->placeholders, $http_headers, $this->json_opts);
-        } else {
-            $http_code = $this->http_code ?? ResponseBuilder::DEFAULT_HTTP_CODE_ERROR;
-
-            Validator::assertErrorHttpCode($http_code);
-
-            $result = $this->make(false, $api_code, $msg_or_api_code, $this->data, $http_code,
-                $this->placeholders, $this->http_headers, $this->json_opts, $this->debug_data);
-
-        }
-
-        return $result;
-    }
-
-
-    /**
-     * @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        $http_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 function make(bool $success, int $api_code, $msg_or_api_code, $data = null,
-                            int $http_code = null, array $placeholders = null, array $http_headers = null,
-                            int $json_opts = null, array $debug_data = null): HttpResponse
-    {
-        $http_headers = $http_headers ?? [];
-        $http_code = $http_code ?? ($success ? ResponseBuilder::DEFAULT_HTTP_CODE_OK : ResponseBuilder::DEFAULT_HTTP_CODE_ERROR);
-        $json_opts = $json_opts ?? Config::get(ResponseBuilder::CONF_KEY_ENCODING_OPTIONS, ResponseBuilder::DEFAULT_ENCODING_OPTIONS);
-
-        Validator::assertIsInt('encoding_options', $json_opts);
-
-        Validator::assertIsInt('api_code', $api_code);
-        if (!BaseApiCodes::isCodeValid($api_code)) {
-            Validator::assertIsIntRange('api_code', $api_code, BaseApiCodes::getMinCode(), BaseApiCodes::getMaxCode());
-        }
-
-        return Response::json(
-            $this->buildResponse($success, $api_code, $msg_or_api_code, $placeholders, $data, $debug_data),
-            $http_code, $http_headers, $json_opts);
-    }
-
-    /**
-     * 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 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.
-        $data = (new 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 = $this->getMessageForApiCode($success, $msg_or_api_code, $placeholders);
-        } else {
-            Validator::assertIsString('message', $msg_or_api_code);
-            $message = $msg_or_api_code;
-        }
-
-        /** @noinspection PhpUndefinedClassInspection */
-        $response = [
-            ResponseBuilder::KEY_SUCCESS => $success,
-            ResponseBuilder::KEY_CODE    => $api_code,
-            ResponseBuilder::KEY_LOCALE  => \App::getLocale(),
-            ResponseBuilder::KEY_MESSAGE => $message,
-            ResponseBuilder::KEY_DATA    => $data,
-        ];
-
-        if ($debug_data !== null) {
-            $debug_key = Config::get(ResponseBuilder::CONF_KEY_DEBUG_DEBUG_KEY, ResponseBuilder::KEY_DEBUG);
-            $response[ $debug_key ] = $debug_data;
-        }
-
-        return $response;
-    }
-
-    /**
-     * 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 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);
-    }
+	public static function asError(int $api_code): self
+	{
+		$code_ok = BaseApiCodes::OK();
+		if ($api_code !== $code_ok) {
+			Validator::assertIsIntRange('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");
+		}
+
+		return new self(false, $api_code);
+	}
+
+	public function withHttpCode(int $http_code = null): self
+	{
+		Validator::assertIsType('http_code', $http_code, [Validator::TYPE_INTEGER,
+														  Validator::TYPE_NULL]);
+		$this->http_code = $http_code;
+
+		return $this;
+	}
+
+	public function withData($data = null): self
+	{
+		Validator::assertIsType('data', $data, [Validator::TYPE_ARRAY,
+												Validator::TYPE_OBJECT,
+												Validator::TYPE_NULL]);
+		$this->data = $data;
+
+		return $this;
+	}
+
+	public function withJsonOptions(int $json_opts = null): self
+	{
+		Validator::assertIsType('json_opts', $json_opts, [Validator::TYPE_INTEGER,
+														  Validator::TYPE_NULL]);
+		$this->json_opts = $json_opts;
+
+		return $this;
+	}
+
+	public function withDebugData(array $debug_data = null): self
+	{
+		Validator::assertIsType('$debug_data', $debug_data, [Validator::TYPE_ARRAY,
+															 Validator::TYPE_NULL]);
+		$this->debug_data = $debug_data;
+
+		return $this;
+	}
+
+	public function withMessage(string $msg = null): self
+	{
+		Validator::assertIsType('message', $msg, [Validator::TYPE_STRING,
+												  Validator::TYPE_NULL]);
+		$this->message = $msg;
+
+		return $this;
+	}
+
+	public function withPlaceholders(array $placeholders = null): self
+	{
+		$this->placeholders = $placeholders;
+
+		return $this;
+	}
+
+	public function withHttpHeaders(array $http_headers = null): self
+	{
+		$this->http_headers = $http_headers ?? [];
+
+		return $this;
+	}
+
+	public function build(): HttpResponse
+	{
+		$api_code = $this->api_code;
+		Validator::assertIsInt('api_code', $api_code);
+
+		$msg_or_api_code = $this->message ?? $api_code;
+		$http_headers = $this->http_headers ?? [];
+
+		if ($this->success) {
+			$api_code = $api_code ?? BaseApiCodes::OK();
+			$http_code = $this->http_code ?? ResponseBuilder::DEFAULT_HTTP_CODE_OK;
+
+			Validator::assertOkHttpCode($http_code);
+
+			$result = $this->make($this->success, $api_code, $msg_or_api_code, $this->data, $http_code,
+				$this->placeholders, $http_headers, $this->json_opts);
+		} else {
+			$http_code = $this->http_code ?? ResponseBuilder::DEFAULT_HTTP_CODE_ERROR;
+
+			Validator::assertErrorHttpCode($http_code);
+
+			$result = $this->make(false, $api_code, $msg_or_api_code, $this->data, $http_code,
+				$this->placeholders, $this->http_headers, $this->json_opts, $this->debug_data);
+
+		}
+
+		return $result;
+	}
+
+
+	/**
+	 * @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        $http_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 function make(bool $success, int $api_code, $msg_or_api_code, $data = null,
+							int $http_code = null, array $placeholders = null, array $http_headers = null,
+							int $json_opts = null, array $debug_data = null): HttpResponse
+	{
+		$http_headers = $http_headers ?? [];
+		$http_code = $http_code ?? ($success ? ResponseBuilder::DEFAULT_HTTP_CODE_OK : ResponseBuilder::DEFAULT_HTTP_CODE_ERROR);
+		$json_opts = $json_opts ?? Config::get(ResponseBuilder::CONF_KEY_ENCODING_OPTIONS, ResponseBuilder::DEFAULT_ENCODING_OPTIONS);
+
+		Validator::assertIsInt('encoding_options', $json_opts);
+
+		Validator::assertIsInt('api_code', $api_code);
+		if (!BaseApiCodes::isCodeValid($api_code)) {
+			Validator::assertIsIntRange('api_code', $api_code, BaseApiCodes::getMinCode(), BaseApiCodes::getMaxCode());
+		}
+
+		return Response::json(
+			$this->buildResponse($success, $api_code, $msg_or_api_code, $placeholders, $data, $debug_data),
+			$http_code, $http_headers, $json_opts);
+	}
+
+	/**
+	 * 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 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.
+		$data = (new 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 = $this->getMessageForApiCode($success, $msg_or_api_code, $placeholders);
+		} else {
+			Validator::assertIsString('message', $msg_or_api_code);
+			$message = $msg_or_api_code;
+		}
+
+		/** @noinspection PhpUndefinedClassInspection */
+		$response = [
+			ResponseBuilder::KEY_SUCCESS => $success,
+			ResponseBuilder::KEY_CODE    => $api_code,
+			ResponseBuilder::KEY_LOCALE  => \App::getLocale(),
+			ResponseBuilder::KEY_MESSAGE => $message,
+			ResponseBuilder::KEY_DATA    => $data,
+		];
+
+		if ($debug_data !== null) {
+			$debug_key = Config::get(ResponseBuilder::CONF_KEY_DEBUG_DEBUG_KEY, ResponseBuilder::KEY_DEBUG);
+			$response[ $debug_key ] = $debug_data;
+		}
+
+		return $response;
+	}
+
+	/**
+	 * 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 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);
+	}
 }

src/ResponseBuilderLegacy.php

Indentation +257 added lines, -257 removed lines

@@ -24,272 +24,272 @@
  */
 class ResponseBuilderLegacy extends ResponseBuilderBase
 {
-    /**
-     * 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 ResponseBuilder::asSuccess($api_code)
-            ->withData($data)
-            ->withPlaceholders($placeholders)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/**
+	 * 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 ResponseBuilder::asSuccess($api_code)
+			->withData($data)
+			->withPlaceholders($placeholders)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
-    /**
-     * 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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function successWithCode(int $api_code = null, array $placeholders = null,
-                                           int $http_code = null): HttpResponse
-    {
-        return ResponseBuilder::asSuccess($api_code)
-            ->withPlaceholders($placeholders)
-            ->withHttpCode($http_code)
-            ->build();
-    }
+	/**
+	 * 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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function successWithCode(int $api_code = null, array $placeholders = null,
+										   int $http_code = null): HttpResponse
+	{
+		return ResponseBuilder::asSuccess($api_code)
+			->withPlaceholders($placeholders)
+			->withHttpCode($http_code)
+			->build();
+	}
 
-    /**
-     * @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 HttpResponse
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function successWithMessage(string $message, $data = null, int $api_code = null,
-                                              int $http_code = null): HttpResponse
-    {
-        return ResponseBuilder::asSuccess($api_code)
-            ->withMessage($message)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->build();
-    }
+	/**
+	 * @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 HttpResponse
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function successWithMessage(string $message, $data = null, int $api_code = null,
+											  int $http_code = null): HttpResponse
+	{
+		return ResponseBuilder::asSuccess($api_code)
+			->withMessage($message)
+			->withData($data)
+			->withHttpCode($http_code)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function successWithHttpCode(int $http_code = null): HttpResponse
-    {
-        return ResponseBuilder::asSuccess()
-            ->withHttpCode($http_code)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function successWithHttpCode(int $http_code = null): HttpResponse
+	{
+		return ResponseBuilder::asSuccess()
+			->withHttpCode($http_code)
+			->build();
+	}
 
-    /**
-     * 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 $json_opts = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withPlaceholders($placeholders)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/**
+	 * 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 $json_opts = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withPlaceholders($placeholders)
+			->withData($data)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithData(int $api_code, $data, array $placeholders = null,
-                                         int $json_opts = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withData($data)
-            ->withPlaceholders($placeholders)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithData(int $api_code, $data, array $placeholders = null,
+										 int $json_opts = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withData($data)
+			->withPlaceholders($placeholders)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithDataAndHttpCode(int $api_code, $data, int $http_code, array $placeholders = null,
-                                                    int $json_opts = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->withPlaceholders($placeholders)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithDataAndHttpCode(int $api_code, $data, int $http_code, array $placeholders = null,
+													int $json_opts = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withData($data)
+			->withHttpCode($http_code)
+			->withPlaceholders($placeholders)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithHttpCode(int $api_code, int $http_code, array $placeholders = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withHttpCode($http_code)
-            ->withPlaceholders($placeholders)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithHttpCode(int $api_code, int $http_code, array $placeholders = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withHttpCode($http_code)
+			->withPlaceholders($placeholders)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithMessageAndData(int $api_code, string $message, $data,
-                                                   int $http_code = null, int $json_opts = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withMessage($message)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithMessageAndData(int $api_code, string $message, $data,
+												   int $http_code = null, int $json_opts = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withMessage($message)
+			->withData($data)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithMessageAndDataAndDebug(int $api_code, string $message, $data,
-                                                           int $http_code = null, int $json_opts = null,
-                                                           array $debug_data = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withMessage($message)
-            ->withData($data)
-            ->withHttpCode($http_code)
-            ->withJsonOptions($json_opts)
-            ->withDebugData($debug_data)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithMessageAndDataAndDebug(int $api_code, string $message, $data,
+														   int $http_code = null, int $json_opts = null,
+														   array $debug_data = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withMessage($message)
+			->withData($data)
+			->withHttpCode($http_code)
+			->withJsonOptions($json_opts)
+			->withDebugData($debug_data)
+			->build();
+	}
 
-    /**
-     * @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
-     *
-     * @deprecated Please use Builder class.
-     */
-    public static function errorWithMessage(int $api_code, string $message, int $http_code = null): HttpResponse
-    {
-        return ResponseBuilder::asError($api_code)
-            ->withMessage($message)
-            ->withHttpCode($http_code)
-            ->build();
-    }
+	/**
+	 * @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
+	 *
+	 * @deprecated Please use Builder class.
+	 */
+	public static function errorWithMessage(int $api_code, string $message, int $http_code = null): HttpResponse
+	{
+		return ResponseBuilder::asError($api_code)
+			->withMessage($message)
+			->withHttpCode($http_code)
+			->build();
+	}
 
 }