Merge pull request #104 from MarcinOrlowski/dev

Release v6.3.0

Author: MarcinOrlowski

CHANGES.md

@@ -6,6 +6,13 @@ See [compatibility docs](docs/compatibility.md) for details about backward compa
 
 ## CHANGE LOG ##
 
+* 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()`.
+   * Added `Validator::assertType()` helper method that validates var against set of allowed types.
+   * Added `Validator::assertString()` helper.
+
 * v6.2.3 (2019-10-31)
    * Added Laravel 6.4 to Travis-CI unit tests.
    * Corrected example in "Manipulating Response Object" docs.

CODE_OF_CONDUCT.md

@@ -1,3 +1,4 @@
-If you need to be told how to behave, then something went wrong during your childhood.
-Other than that you are responsible for your actions and the possible consequences
-(which actually should be nothing new to any grown up human being). Amen.
+ If you need to be told how to behave, then something went wrong during your
+ childhood, otherwise you already know that you are solely responsible for 
+ your actions and the possible consequences (which actually should be nothing
+ new to any grown up human being). Amen.

README.md

@@ -4,18 +4,18 @@
 
 [![Latest Stable Version](https://poser.pugx.org/marcin-orlowski/laravel-api-response-builder/v/stable)](https://packagist.org/packages/marcin-orlowski/laravel-api-response-builder)
 [![Build Status](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder.svg?branch=master)](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=master)
-[![Scrutinizer Code Coverage](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=dev)
-[![Codacy Grade Badge](https://api.codacy.com/project/badge/Grade/44f427e872e2480597bde0242417a2a7)](https://www.codacy.com/app/MarcinOrlowski/laravel-api-response-builder?utm_source=github.com&utm_medium=referral&utm_content=MarcinOrlowski/laravel-api-response-builder&utm_campaign=Badge_Grade)
+[![Code Quality](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=master)
+[![Code Coverage](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=master)
+[![Codacy Grade Badge](https://api.codacy.com/project/badge/Grade/44f427e872e2480597bde0242417a2a7)](https://www.codacy.com/app/MarcinOrlowski/laravel-api-response-builder)
 [![Monthly Downloads](https://poser.pugx.org/marcin-orlowski/laravel-api-response-builder/d/monthly)](https://packagist.org/packages/marcin-orlowski/laravel-api-response-builder)
 [![License](https://poser.pugx.org/marcin-orlowski/laravel-api-response-builder/license)](https://packagist.org/packages/marcin-orlowski/laravel-api-response-builder)
 
 [![SensioLabs Insight](https://insight.sensiolabs.com/projects/5c5f4dc1-41d5-49f9-b4ba-6268aa3fea00/big.png)](https://insight.sensiolabs.com/projects/5c5f4dc1-41d5-49f9-b4ba-6268aa3fea00)
 
-[![Latest Unstable Version](https://poser.pugx.org/marcin-orlowski/laravel-api-response-builder/v/unstable)](https://packagist.org/packages/marcin-orlowski/laravel-api-response-builder)
-[![Build Status](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder.svg?branch=dev)](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/quality-score.png?b=dev)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=dev)
-[![Scrutinizer Code Coverage](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/coverage.png?b=dev)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=dev)
+[![Unstable Version](https://poser.pugx.org/marcin-orlowski/laravel-api-response-builder/v/unstable)](https://packagist.org/packages/marcin-orlowski/laravel-api-response-builder)
+[![Unstable Build Status](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder.svg?branch=dev)](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder)
+[![Ustable Code Quality](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/quality-score.png?b=dev)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=dev)
+[![Unstble Code Coverage](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/badges/coverage.png?b=dev)](https://scrutinizer-ci.com/g/MarcinOrlowski/laravel-api-response-builder/?branch=dev)
 
 ## Table of contents ##
 
@@ -30,7 +30,7 @@
  * [License](#license)
  * [Changelog](CHANGES.md)
 
- **Upgrading from previous version? Ensure you read [compatibility docs](docs/compatibility.md) prior altering your `composer.json`!**
+ **Upgrading from previous version? Check [compatibility docs](docs/compatibility.md) prior altering your `composer.json`!**
 
 ----
 
@@ -97,15 +97,12 @@
 
  * Easy to use,
  * [Stable and production ready](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder),
- * Laravel compatibility: v6.x (see [legacy support](docs/legacy.md) if you use older Laravel version),
- * Supports Laravel [auto-discovery](https://medium.com/@taylorotwell/package-auto-discovery-in-laravel-5-5-ea9e3ab20518),
- * Configurable (with ready-to-use defaults),
+ * On-the-fly data object conversion,
+ * API chaining support,
  * Localization support,
- * Automatic object conversion with custom mapping,
- * API chaining/cascading support,
- * Includes traits to help [unit test your API code](docs/testing.md),
- * Provides own [exception handler helper](docs/exceptions.md) to ensure your API stays consumable even in case of unexpected,
- * No extra dependencies.
+ * Provides traits to help [unit test your API code](docs/testing.md),
+ * Comes with [exception handler helper](docs/exceptions.md) to ensure your API stays consumable even in case of unexpected,
+ * No additional dependencies.
 
 ----
 

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": "6.2.3",
+  "version": "6.3.0",
   "keywords": [
     "laravel",
     "json",

docs/compatibility.md

@@ -2,11 +2,13 @@
 
 # REST API Response Builder for Laravel #
 
- `ResponseBuilder` follows [Semantic Versioning](http://semver.org/).
-
-
 ### v6 ###
 
+#### v6.3 ####
+ * `[BREAKING]` This is backward incompatible change in signature of `ResponseBuilder::buildResponse()`, but it only affects
+   you if you extend `ResponseBuilder` and provide own implementation to manipulate response object
+   (see [Manipulating Response Object](docs.md#manipulating-response-object)). If you do not, then you are not affected.
+
 #### v6.2 ####
  * `[Very Low]` Data conversion logic changed slightly. Now it checks if we have configuration entry matching **exactly** the
   object's class name. If not, then we'd try to find if we have any configuration for its parent class.

docs/docs.md

@@ -25,9 +25,9 @@
 
 ## Response structure ##
 
- Predictability, simplicity and no special-case is the key of the `ResponseBuilder` design. I wanted to make my life easier not
- only when I develop the API itself, but also when I'd try to use it i.e. in mobile applications, therefore all responses created
- by this package **guarantee** consistent JSON structure by design.
+ Predictability, simplicity and no special-case is the key of the `ResponseBuilder` design. I wanted to make my life
+ easier not only when I develop the API itself, but also when I'd try to use it i.e. in mobile applications, 
+ therefore all responses created by this package **guarantee** consistent JSON structure by design.
 
  By default response always contain at least the following elements:
 
@@ -45,18 +45,23 @@
 
   * `success` (**boolean**) indicates API method failure or success,
   * `code` (**int**) is your own return code (usually used when returning error message or other failure),
-  * `locale` (**string**) represents locale used for returned error message (obtained automatically via `\App::getLocale()`). This helps processing the response if you support multiple languages,
-  * `message` (**string**) human readable message that is ready to display and explains human readable explanation of the `code` value,
-  * `data` (**object**|**array**|**null**) if you return any additional data with your reply, it would end here. If no extra data is needed, that key still be present in the response with `null` value.
+  * `locale` (**string**) represents locale used for returned error message (obtained automatically via 
+    `\App::getLocale()`). This helps processing the response if you support multiple languages,
+  * `message` (**string**) human readable message that is ready to display and explains human readable explanation 
+    of the `code` value,
+  * `data` (**object**|**array**|**null**) if you return any additional data with your reply, it would end here.
+    If no extra data is needed, that key still be present in the response with `null` value.
 
- **NOTE:** If you need to return other/different elements in the above structure (not in your `data`), see [Manipulating Response Object](#manipulating-response-object) chapter for detailed information about how to achieve this.
+ **NOTE:** If you need to return other/different elements in the above structure (not in your `data`),
+ see [Manipulating Response Object](#manipulating-response-object) chapter for detailed information about how
+ to achieve this.
 
 ----
 
 ## Usage examples ##
 
- The following examples assume `ResponseBuilder` is properly installed and available to your Laravel application. Installation
- steps are described in details in further chapters, if help is needed.
+ The following examples assume `ResponseBuilder` is properly installed and available to your Laravel application.
+ Installation steps are described in details in further chapters, if help is needed.
 
 #### Success ####
 
@@ -438,30 +443,34 @@ $data = [
 
  Minimum requirements:
 
-  * PHP 7.2+
-  * Laravel 6.*
-
- The following PHP extensions are optional but strongly recommended:
-
-   * iconv
-   * mb_string
+  * PHP 7.2+ with [json extension](https://www.php.net/manual/en/book.json.php),
+  * Laravel v6.x (see [legacy](docs/legacy.md) for Laravel 5.x support).
 
 ----
 
 ## Installation and Configuration ##
 
  To install `ResponseBuilder` all you need to do is to open your shell/cmd and do:
 
-    composer require marcin-orlowski/laravel-api-response-builder
+    composer require marcin-orlowski/laravel-api-response-builder:<VERSION>
+
+ Where `<VERSION>` string consists of `MAJOR` and `MINOR` release numbers. For
+ example if current relase is 6.4.13, you need to invoke:
+
+    composer require marcin-orlowski/laravel-api-response-builder:6.3
+
+ which will add  the dependency at the release 6.3 + all the bugfixing releses
+ (`6.3.*`) but won't automatically pull 6.4 even if available, unless
+ `composer.json` is updated manually.
 
  If you want to use different configuration than `ResponseBuilder` defaults,
  publish and edit configuration file as described in [Configuration file](config.md)
  documentation.
 
 #### Setup ####
 
- `ResponseBuilder` supports Laravel's auto-discovery feature and it's ready to use once
- installed with default configuration.
+ `ResponseBuilder` supports Laravel's auto-discovery feature and it's ready to use once 
+ installed.
 
 #### ApiCodes class ####
 
@@ -546,6 +555,8 @@ class ApiCode {
  If you need to return more fields in response object you can simply extend `ResponseBuilder` class
  and override `buildResponse()` method.
 
+### Custom response structure ###
+
  For example, you want to get rid of `locale` field and add server time and timezone to returned
  responses. First, create `MyResponseBuilder.php` file in `app/` folder (both location and class
  name can be anything you wish, just remember to adjust the namespace too) and override
@@ -559,11 +570,12 @@ namespace App;
 
 class MyResponseBuilder extends MarcinOrlowski\ResponseBuilder\ResponseBuilder
 {
-   protected static function buildResponse(bool $success, int $api_code, string $message,
+   protected static function buildResponse(bool $success, int $api_code, 
+                                           $message_or_api_code, array $lang_args = null,
                                            $data = null, array $debug_data = null): array
    {
       // tell ResponseBuilder to do all the heavy lifting first
-      $response = parent::buildResponse($code, $message, $data);
+      $response = parent::buildResponse($success, $api_code, $message_or_api_code, $lang_args, $data, $debug_data);
 
       // then do all the tweaks you need
       $date = new DateTime();
@@ -575,13 +587,14 @@ class MyResponseBuilder extends MarcinOrlowski\ResponseBuilder\ResponseBuilder
       // finally, return what $response holds
       return $response;
    }
+
 }
 ```
 
  and from now on use `MyResponseBuilder` class instead of `ResponseBuilder`. As all responses are
  always produced with use of `buildResponse()` internally, your **all** responses will be affected
  the same way. For example:
-
+ 
 ```php
 MyResponseBuilder::success();
 ```
@@ -621,6 +634,28 @@ return MyResponseBuilder::errorWithData(ApiCode::SOMETHING_WENT_WRONG, $data);
 }
 ```
 
+### Overriding code to message conversion ###
+
+`ResponseBuilder` automatically provides human readable error messages for each API code used but if for any
+reason you want to take control on this, you can now provide own implementation of `ResponseBuilder::getMessageForApiCode()`.
+
+```php
+<?php
+
+namespace App;
+
+class MyResponseBuilder extends MarcinOrlowski\ResponseBuilder\ResponseBuilder
+{
+   protected static function getMessageForApiCode(bool $success, int $api_code, array $lang_args = null): string
+   {
+       return "My cool message for code {$api_code}";
+   }
+}
+```
+
+Please see current implementation for `getMessageForApiCode()` for details how to correctly obtain localization string key etc.
+
+
 ----
 
 ## Overriding built-in messages ##

docs/exceptions.md

@@ -142,9 +142,10 @@ public const VALIDATION_EXCEPTION = ...;
  `ResponseBuilder`'s handler which usually lead to one (or another) handler not being executed
  at all.
 
- For example if your API delegates OAuth2 related tasks to popular [lucadegasperi/oauth2-server-laravel](https://packagist.org/packages/lucadegasperi/oauth2-server-laravel)
- package, then you must **NOT** use its `OAuthExceptionHandlerMiddleware` class and ensure it is not set,
- by inspecting `app/Kernel.php` file and ensuring the following line (if present) is removed or commented out:
+ For example if your API delegates OAuth2 related tasks to popular
+ [lucadegasperi/oauth2-server-laravel](https://packagist.org/packages/lucadegasperi/oauth2-server-laravel) package, then you
+ must **NOT** use its `OAuthExceptionHandlerMiddleware` class and ensure it is not set, by inspecting `app/Kernel.php` file
+ and ensuring the following line (if present) is removed or commented out:
 
 ```php
 // remove or comment out