Merge pull request #173 from MarcinOrlowski/dev

Release 9.0.3

Author: MarcinOrlowski

.github/stale.yml

@@ -1,5 +1,5 @@
 # Number of days of inactivity before an issue becomes stale
-daysUntilStale: 21
+daysUntilStale: 14
 # Number of days of inactivity before a stale issue is closed
 daysUntilClose: 7
 # Issues with these labels will never be considered stale

CHANGES.md

@@ -8,18 +8,22 @@ before doing major upgrade!
 
 ## CHANGE LOG ##
 
+* v9.0.3 (2020-10-27)
+   * `Validator` type related exceptions must now implement `InvalidTypeExceptionContract`.
+   * `converter` config `key` element now accepts `null` to indicate you want no key to be used.
+
 * v9.0.2 (2020-10-24)
    * Corrected tests to use regular ServiceProvider.
    * Corrected primitive converter tests.
-   * Presence of configuration "converter/classes" array is now mandatory (reported by Raja)
-   * Extensive documentation overhaul
+   * Presence of configuration "converter/classes" array is now mandatory (reported by Raja).
+   * Extensive documentation overhaul.
 
 * v9.0.1 (2020-10-22)
    * Fixed auto-discovery failing due to broken `ServiceProvider` (reported by Efriandika Pratama).
    * Corrected documentation and usage examples.
 
 * v9.0.0 (2020-10-17)
-   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md))
+   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md)).
    * [RB-156] Added logic to deal with directly returned objects or arrays.
    * [RB-158] Passing primitives as direct payload (i.e. `success(12.50);` is now supported for `array`, `boolean`,
      `double`, `integer` and `string` types, configurable via new `converter/primitives`.
@@ -28,7 +32,7 @@ before doing major upgrade!
 
 * v8.1.1 (2020-10-15)
    * [RB-155] Fixed `ResponseBuilder` internals preventing exdending class code from
-     being invoked, thus making response object structure manipulation ineffective (reported by krek95)
+     being invoked, thus making response object structure manipulation ineffective (reported by krek95).
 
 * v8.1.0 (2020-09-17)
    * Added logging (`.env` controllable) for payload Converter to help debugging inproper data conversion.
@@ -38,7 +42,7 @@ before doing major upgrade!
    * Removed `Util::printArray()` helper.
 
 * v8.0.0 (2020-07-14)
-   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md))
+   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md)).
    * Improved performance by using calls qualified references.
    * [RB-132] Reworked exception handler helper to support delegated handlers for better flexibility.
    * Reverted depreciation of `BaseApiCodes` reserved range codes.
@@ -47,30 +51,30 @@ before doing major upgrade!
    * Added German localization.
 
 * v7.1.2 (2020-07-12)
-   * [RB-141] Fixed `JsonSerializableConverter` to deal non-string return data (reported by Jonatan Fekete)
+   * [RB-141] Fixed `JsonSerializableConverter` to deal non-string return data (reported by Jonatan Fekete).
 
 * v7.1.1 (2020-07-11)
    * Added more tests.
    * Updated dependencies.
    * Switched away from deprecated Codacy coverage package.
 
 * v7.1.0 (2020-03-04)
-   * Added support for Laravel v7
+   * Added support for Laravel v7.
 
 * v7.0.3 (2019-12-30)
    * Fixed `composer.json` file.
 
 * v7.0.2 (2019-12-29)
-   * Updated Travis config to cover Laravel 6.5, 6.6, 6.7 and 6.8
-   * Updated Travis config to cover PHP 7.4
+   * Updated Travis config to cover Laravel 6.5, 6.6, 6.7 and 6.8.
+   * Updated Travis config to cover PHP 7.4.
 
 * v7.0.1 (2019-11-25)
    * Disabled Scrutinizer's "false positive" in Builder class.
    * Added more tests to improve overall coverage.
-   * Updated PHPDocs
+   * Updated PHPDocs.
 
 * v7.0.0 (2019-11-22)
-   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md))
+   * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md)).
    * New, flexible API based on `Builder` pattern (see [docs](docs/compatibility.md) for details).
    * Reworked `ExceptionHandlerHelper` configuration. Now, you will be able to easily configure every
      HttpException for each HTTP status code you want. Separate `ExceptionHandler::TYPE_HTTP_NOT_FOUND_KEY`

composer.json

@@ -2,7 +2,7 @@
   "name": "marcin-orlowski/laravel-api-response-builder",
   "description": "Helps building nice, normalized and easy to consume Laravel REST API.",
   "homepage": "https://github.com/MarcinOrlowski/laravel-api-response-builder",
-  "version": "9.0.2",
+  "version": "9.0.3",
   "keywords": [
     "laravel",
     "json",

docs/config.md

@@ -83,12 +83,12 @@ php artisan vendor:publish
  Meaning of parameters:
 
  * `handler` (mandatory) specifies a full name of the class implementing `ConverterContract`. Object of that class will be
-   instantiated and conversion method will be invked with object given as argument. The `key` is a string that will be used
+   instantiated and conversion method will be invoked with object given as argument. The `key` is a string that will be used
    as the JSON response as key to array representation when object of that class is passed as direct payload
    (i.e. `success($object);`). Note, that `key` is not used otherwise, so if you have i.e. array of objects, they will be
    properly converted without `key` used.
- * `key` (mandatory) is a string, used by some converters when dealing with object of given class being returned directly
-   as response payload (i.e. `success($collection)`).
+ * `key` (mandatory) can be a string or `NULL`. A string is useful for some converters when dealing with an object of a given class being returned directly
+   as response payload (i.e. `success($collection)`). Otherwise  `NULL` can be used to tell `ResponseBuilder` to return object directly, which may be useful.
  * `pri` (optional) is an integer being entry's priority (default `0`). Entries with higher values will be matched first. If you got one
    class extending another and you want to support both of them with separate configuration, then you **must** ensure child
    class has higher priority than it's parent class.

src/Contracts/InvalidTypeExceptionContract.php

@@ -0,0 +1,19 @@
+<?php
+declare(strict_types=1);
+
+namespace MarcinOrlowski\ResponseBuilder\Contracts;
+
+/**
+ * Laravel API Response Builder
+ *
+ * @package   MarcinOrlowski\ResponseBuilder
+ *
+ * @author    Marcin Orlowski <mail (#) marcinOrlowski (.) com>
+ * @copyright 2016-2020 Marcin Orlowski
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      https://github.com/MarcinOrlowski/laravel-api-response-builder
+ */
+interface InvalidTypeExceptionContract
+{
+	public function __construct(string $var_name, string $type, array $allowed_types);
+}

src/Converter.php

@@ -90,7 +90,7 @@ protected function getClassMappingConfigOrThrow(object $data): array
 
 		// check for exact class name match...
 		$cls = \get_class($data);
-		if (\is_string($cls)) {
+		if ($cls !== false) {
 			if (\array_key_exists($cls, $this->classes)) {
 				$result = $this->classes[ $cls ];
 				$debug_result = 'exact config match';
@@ -121,9 +121,9 @@ protected function getClassMappingConfigOrThrow(object $data): array
 	/**
 	 * Main entry for data conversion
 	 *
-	 * @param object|array|null $data
+	 * @param mixed|null $data
 	 *
-	 * @return mixed|null
+	 * @return array|null
 	 */
 	public function convert($data = null): ?array
 	{
@@ -145,8 +145,9 @@ public function convert($data = null): ?array
 		if ($result === null && \is_object($data)) {
 			$cfg = $this->getClassMappingConfigOrThrow($data);
 			$worker = new $cfg[ RB::KEY_HANDLER ]();
-			$result = [$cfg[ RB::KEY_KEY ] => $worker->convert($data, $cfg)];
-		}
+			$result = $worker->convert($data, $cfg);
+			$result = $cfg[ RB::KEY_KEY ] === null ? $result : [$cfg[ RB::KEY_KEY ] => $result];
+        }
 
 		if ($result === null && \is_array($data)) {
 			$cfg = $this->getPrimitiveMappingConfigOrThrow($data);
@@ -210,19 +211,21 @@ protected static function getClassesMapping(): array
 
 		if (!empty($classes)) {
 			$mandatory_keys = [
-				RB::KEY_HANDLER,
-				RB::KEY_KEY,
+				RB::KEY_HANDLER => [TYPE::STRING],
+				RB::KEY_KEY => [TYPE::STRING, TYPE::NULL],
 			];
 			foreach ($classes as $class_name => $class_config) {
 				if (!\is_array($class_config)) {
 					throw new Ex\InvalidConfigurationElementException(
 						sprintf("Config for '{$class_name}' class must be an array (%s found).", \gettype($class_config)));
 				}
-				foreach ($mandatory_keys as $key_name) {
+				foreach ($mandatory_keys as $key_name => $allowed_types) {
 					if (!\array_key_exists($key_name, $class_config)) {
 						throw new Ex\IncompleteConfigurationException(
 							"Missing '{$key_name}' entry in '{$class_name}' class mapping config.");
 					}
+
+                    Validator::assertIsType(RB::KEY_KEY, $class_config[$key_name], $allowed_types);
 				}
 			}
 		}

src/Converters/ArrayableConverter.php

@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 
 namespace MarcinOrlowski\ResponseBuilder\Converters;
 
@@ -17,21 +18,24 @@
 use MarcinOrlowski\ResponseBuilder\Contracts\ConverterContract;
 use MarcinOrlowski\ResponseBuilder\Validator;
 
+/**
+ * Converter for Arrayable class type of objects.
+ */
 final 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(object $obj, /** @scrutinizer ignore-unused */ array $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(object $obj, /** @scrutinizer ignore-unused */ array $config): array
+	{
+		Validator::assertInstanceOf('obj', $obj, Arrayable::class);
 
-        return $obj->toArray();
-    }
+		return $obj->toArray();
+	}
 }

src/Converters/JsonSerializableConverter.php

@@ -18,6 +18,11 @@
 use MarcinOrlowski\ResponseBuilder\Validator;
 use MarcinOrlowski\ResponseBuilder\ResponseBuilder as RB;
 
+/**
+ * Converts JsonSerializable to array
+ *
+ * @package MarcinOrlowski\ResponseBuilder\Converters
+ */
 final class JsonSerializableConverter implements ConverterContract
 {
 	/**

src/Converters/ToArrayConverter.php

@@ -17,6 +17,9 @@
 use MarcinOrlowski\ResponseBuilder\Contracts\ConverterContract;
 use MarcinOrlowski\ResponseBuilder\Validator;
 
+/**
+ * Generic object-to-array array converter.
+ */
 final class ToArrayConverter implements ConverterContract
 {
     /**

src/ExceptionHandlerHelper.php

@@ -4,7 +4,7 @@
 namespace MarcinOrlowski\ResponseBuilder;
 
 /**
- * Exception handler using ResponseBuilder to return JSON even in such hard tines
+ * Laravel API Response Builder
  *
  * @package   MarcinOrlowski\ResponseBuilder
  *
@@ -25,7 +25,7 @@
 use MarcinOrlowski\ResponseBuilder\ResponseBuilder as RB;
 
 /**
- * Class ExceptionHandlerHelper
+ * Exception handler using ResponseBuilder to return JSON even in such hard tines
  */
 class ExceptionHandlerHelper
 {