Merge pull request #161 from MarcinOrlowski/dev

Release 9.0.0

Author: MarcinOrlowski

.gitignore

@@ -1,5 +1,4 @@
 .idea/
 vendor/
 composer.lock
-.phpunit.result.cache
-.php_cs.cache
+.*.cache

CHANGES.md

@@ -2,10 +2,20 @@
 
 # REST API Response Builder for Laravel #
 
-See [compatibility docs](docs/compatibility.md) for details about backward compatibility!
+This library follows [Semantic versioning](https://semver.org).  
+See [compatibility docs](docs/compatibility.md) for details about backward compatibility
+before doing major upgrade!
 
 ## CHANGE LOG ##
 
+* v9.0.0 (2020-10-17)
+   * **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`.
+   * Removed hadrcoded `val` key used by `JsonSerializable` converter.
+   * Introduced own exceptions for better error reporting. See [src/Exceptions](src/Exceptions) for more info.
+
 * 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)
@@ -62,7 +72,7 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
    * Data converter now handles objects implementing `JsonSerializable` and `Arrayable` contracts as well.
 
 * v6.3.2 (2019-11-07)
-   * Added `ResponseBuilder::successWithMessage()` method.
+   * Added `RB::successWithMessage()` method.
    * Entries in `classes` config array can now have `pri` (default 0) to enforce order while
      merging config with a built-in configuration.
    * Persian translation (Thanks to @FaridAghili).
@@ -75,8 +85,8 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
 
 * v6.3.0 (2019-11-02)
    * **BACKWARD INCOMPATIBLE CHANGES** ([more info](docs/compatibility.md))
-   * Signature of `ResponseBuilder::buildResponse()` changed to allow customization of final `message` entry (@hawezo).
-   * Moved all code that produces messages for API codes to `ResponseBuilder::getMessageForApiCode()`.
+   * Signature of `RB::buildResponse()` changed to allow customization of final `message` entry (@hawezo).
+   * Moved all code that produces messages for API codes to `RB::getMessageForApiCode()`.
    * Added `Validator::assertType()` helper method that validates var against set of allowed types.
    * Added `Validator::assertString()` helper.
 
@@ -125,20 +135,20 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
    * Reserved codes reduced to 19 (from former 63).
    * Added type hints to all method arguments and return values
    * `ExceptionHandler` responses use exception specific HTTP code.
-   * Fixed `ResponseBuilder::errorWithMessageAndData()` not passing data properly.
+   * Fixed `RB::errorWithMessageAndData()` not passing data properly.
    * Fixed exception message thrown by `ApiCodesHelpers::getMaxCode()`.
    * Corrected test cases list in `testSuccess_DataAndHttpCode()`.
    * Fixed error code fallback in `testRender_HttpException()` test.
    * Fixed `testError_DebugTrace()` not containing any asserts.
    * Reformatted code to not exceed 132 columns, for better on-line readability.
-   * `ResponseBuilder::errorWithDataAndHttpCode()` accepts now `null` as http code.
-   * `ResponseBuilder::errorWithHttpCode()` accepts now `null` as http code.
+   * `RB::errorWithDataAndHttpCode()` accepts now `null` as http code.
+   * `RB::errorWithHttpCode()` accepts now `null` as http code.
    * Fixed `ExceptionHandlerHelper` replacing HTTP codes above 499 with 400.
    * Changed default message for `HTTP_NOT_FOUND` error.
    * `ExceptionHandler` now falls back to `EX_UNCAUGHT_EXCEPTION` for all the cases.
    * Simplified `ExceptionHandlerHelperTest::testRender_HttpException()` test.
    * Removed `exception_handler.use_exception_message_first` feature.
-   * Removed `ResponseBuilder::DEFAULT_API_CODE_OK` constant.
+   * Removed `RB::DEFAULT_API_CODE_OK` constant.
    * Removed `getReservedMinCode()`, `getReservedMinCode()`, `getReservedMessageKey()` methods.
    * Removed internal API code constants. Use corresponding methods to get proper code value.
    * Reimplemented Laravel config merger to support multi-dimensional configuration arrays too.
@@ -150,7 +160,7 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
 
 * v4.1.9 (2019-08-08)
    * Fixed `ApiCodesHelpers::getMaxCode()` exception message
-   * Fixed `ResponseBuilder::errorWithMessageAndData()` not passing args properly
+   * Fixed `RB::errorWithMessageAndData()` not passing args properly
 
 * v4.1.8 (2019-08-07)
    * Added Laravel 6 to testing setup
@@ -199,7 +209,7 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
    * `[RB-59]` Added option to remap response JSON keys to user provided values
    * `[RB-54]` Debug data no longer pollutes `data` leaf. Instead, it adds `debug` dictionary to root data structure.
    * `[RB-37]` Added support for Laravel 5.3+ `unauthenticated()` in Exception Handler. See new config keys defaults
-   * `[RB-47]` Exception Handler now supports `FormRequests` and returns all messages in `ResponseBuilder::KEY_MESSAGES`
+   * `[RB-47]` Exception Handler now supports `FormRequests` and returns all messages in `RB::KEY_MESSAGES`
    * Uncaught `HttpResponse::HTTP_UNAUTHORIZED` exception is now handled same way `authentication_exception` is
    * `[RB-56]` Added configurable key for debug trace added to returned JSON response (if enabled)
    * Added traits to help testing your config and ApiCodes with ease. See `Unit Testing your ApiCodes` docs for details

CONTRIBUTING.md

@@ -26,7 +26,6 @@
  * [Documentation](docs/docs.md)
  * [Requirements](docs/docs.md#requirements)
  * [Installation and Configuration](docs/docs.md#installation-and-configuration)
- * [Bugs reports and pull requests](CONTRIBUTING.md)
  * [License](#license)
  * [Changelog](CHANGES.md)
 
@@ -36,34 +35,33 @@
 
 ## Introduction ##
 
- `ResponseBuilder` is a [Laravel](https://laravel.com/) helper designed to build nice, normalized and easy to consume REST API 
+ `ResponseBuilder` is a [Laravel](https://laravel.com/) helper designed to build nice, normalized and easy to consume REST API
  JSON responses.
 
 ## Benefits ##
 
- `ResponseBuilder` is written for REST API developers by REST API developer and is based on my long lasting experience on both
- "sides" (API dev and API consumer) of variety of REST APIs. Lightweight, with simple to use public methods, covering multiple 
- potential use-cases, on-the-fly data conversion, localization support, automatic error message building, support
- for chained APIs and (hopefully) exhaustive documentation. But that's not all! The JSON structure produced by `ResponseBuilder` 
- is designed with **users of your API** in mind, which helps them easily deal with your API with ease. They get simple, well
- defined and predictable JSON structure responses with all the fields needed to consume it without any unnecessary a hassle nor 
- other trickery. 
- 
- Android developers can use [ApiResponse](https://github.com/MarcinOrlowski/ApiResponse) library to handle `ResponseBuilder` 
- responses produced in their mobile applications.   
- 
- You are even covered in a case of emergency as provided Exception Handler ensures your API keeps talking JSON (and 
- not HTML) to its clients if case of any unexpected and unhandled exception.
- 
- Did I mention, you also get testing traits that would automatically cover your whole `ResponseBuilder` related code with 
- unit tests with just a few lines of code?
+ `ResponseBuilder` is written for REST API developers by REST API developer and is based on my long-lasting experience on both
+ "sides" as API dev and API consumer, of variety of REST APIs. It's lightweight, extensively tested, simple to use yet
+ flexible and powerful, withon-the-fly data conversion, localization support, automatic error message building, support
+ for chained APIs and (hopefully) exhaustive documentation. But that's not all! The JSON structure produced by `ResponseBuilder`
+ is designed with **users of your API** in mind, to make dealing with your API a breeze. Simple JSON response, with well-defined
+ and predictable structure, easy to consume without a hassle nor trickery.
+
+ As a bonus, Android developers can use [ApiResponse](https://github.com/MarcinOrlowski/ApiResponse) library in their apps
+ to handle `ResponseBuilder` responses.
+
+ You are even covered in a case of emergency, as provided Exception Handler helper, ensures your API keeps talking JSON (and
+ not HTML) to its clients even in case of unexpected and unhandled exception.
+
+ Did I mention, you would also get free testing traits that automatically unit test your whole `ResponseBuilder` related code
+ and configuration with just a few lines of code?
 
 ## Usage examples ##
- 
+
  Operation successful? Conclude your controller method with:
 
 ```php
-return ResponseBuilder::success();
+return RB::success();
 ```
 
  and your client will get nice JSON like
@@ -78,10 +76,43 @@ return ResponseBuilder::success();
 }
 ```
 
- Something went wrong? Just type:
+ Need to additionally return extra payload with the response? Pass it as
+ argument to `success()`:
+
+```php
+$flight = App\Flight::where(...)->get();
+return RB::success($flight); 
+```
+
+ and your client will get that data in `data` node of your response:
+
+```json
+{
+  "success": true,
+  "code": 0,
+  "locale": "en",
+  "message": "OK",
+  "data": {
+     "items": [
+        {
+          "airline": "lot",
+          "flight_number": "lo123",
+          ...
+       },
+       {
+          "airline": "american",
+          "flight_number": "am456",
+          ...
+       }
+    ]
+  }
+}
+```
+
+ Something went wrong and you want to tell the clinet about that? Just do:
 
 ```php
-return ResponseBuilder::error(250);
+return RB::error(250);
 ```
 
  The following JSON response will then be returned:

README.md

@@ -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": "8.1.1",
+  "version": "9.0.0",
   "keywords": [
     "laravel",
     "json",

composer.json

@@ -37,41 +37,63 @@
     |
     */
     '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,
-        ],
+	    'primitives' => [
+		    /* Configuration for primitives used when such data is passed directly as payload (i.e. `success(15)`;) */
+		    'array'   => [
+			    'key' => 'values',
+		    ],
+		    'boolean' => [
+			    'key' => 'value',
+		    ],
+		    'double'  => [
+			    'key' => 'value',
+		    ],
+		    'integer' => [
+			    'key' => 'value',
+		    ],
+		    'string'  => [
+			    'key' => 'value',
+		    ],
+	    ],
 
-        /*
-        |-----------------------------------------------------------------------------------------------------------
-        | Generic converters should have lower pri to allow dedicated ones to kick in first when class matches
-        |-----------------------------------------------------------------------------------------------------------
-        */
-        \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,
+	    /* Object converters configuration for supported classes */
+    	'classes' => [
+	        \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'     => 'items',
+	            'pri'     => 0,
+	        ],
+	        \Illuminate\Database\Eloquent\Collection::class     => [
+	            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+	            'key'     => 'items',
+	            'pri'     => 0,
+	        ],
+	        \Illuminate\Http\Resources\Json\JsonResource::class => [
+	            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ToArrayConverter::class,
+	            'key'     => 'item',
+	            'pri'     => 0,
+	        ],
+
+	        /*
+	        |-----------------------------------------------------------------------------------------------------------
+	        | Generic converters should have lower pri to allow dedicated ones to kick in first when class matches
+	        |-----------------------------------------------------------------------------------------------------------
+	        */
+	        \JsonSerializable::class                            => [
+	            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\JsonSerializableConverter::class,
+	             'key'     => 'item',
+	            'pri'     => -10,
+	        ],
+	        \Illuminate\Contracts\Support\Arrayable::class      => [
+	            'handler' => \MarcinOrlowski\ResponseBuilder\Converters\ArrayableConverter::class,
+	            'key'     => 'items',
+	            'pri'     => -10,
+	        ],
         ],
 
     ],