Merge pull request #167 from MarcinOrlowski/dev

Release v9.0.2

Author: MarcinOrlowski

.github/stale.yml

@@ -0,0 +1,19 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 21
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 7
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - pinned
+  - security
+# Label to use when marking an issue as stale
+staleLabel: wontfix
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity and will be closed soon as such.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: >
+  This stale issue has been automatically closed. Feel free to still comment
+  and even reopen the ticket if the problem is not solved or you think we
+  could go better. Thank you for your contributions.

CHANGES.md

@@ -2,12 +2,18 @@
 
 # REST API Response Builder for Laravel #
 
-This library follows [Semantic versioning](https://semver.org).  
+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.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
+
 * v9.0.1 (2020-10-22)
    * Fixed auto-discovery failing due to broken `ServiceProvider` (reported by Efriandika Pratama).
    * Corrected documentation and usage examples.

README.md

@@ -10,22 +10,13 @@
 [![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)
-
-[![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 ##
 
  * [Introduction](#introduction)
  * [Why should I use it?](#benefits)
- * [Usage examples](#usage-examples)
+ * [Usage examples](docs/examples.md#usage-examples)
  * [Features](#features)
- * [Documentation](docs/docs.md)
- * [Requirements](docs/docs.md#requirements)
- * [Installation and Configuration](docs/docs.md#installation-and-configuration)
+ * [Extensive documentation](docs/README.md)
  * [License](#license)
  * [Changelog](CHANGES.md)
 
@@ -35,8 +26,8 @@
 
 ## Introduction ##
 
- `ResponseBuilder` is a [Laravel](https://laravel.com/) helper designed to build nice, normalized and easy to consume REST API
- JSON responses.
+ `ResponseBuilder` is a [Laravel](https://laravel.com/) package, designed to help you build a nice, normalized and easy to consume
+ REST API JSON responses.
 
 ## Benefits ##
 
@@ -53,94 +44,17 @@
  Did I mention, you would also get 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 RB::success();
-```
-
- and your client will get nice JSON like
-
-```json
-{
-  "success": true,
-  "code": 0,
-  "locale": "en",
-  "message": "OK",
-  "data": null
-}
-```
-
- 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 RB::error(250);
-```
-
- The following JSON response will then be returned:
-
-```json
-{
-   "success": false,
-   "code": 250,
-   "locale": "en",
-   "message": "Your error message for code 250",
-   "data": null
-}
-```
-
- Nice and easy! And yes, `message` can be easily customized! Also there're **much, much more** you can do with
- rich `ResponseBuilder` API. See [library documentation](docs/docs.md) for details and more examples!
-
-----
-
 ## Features ##
 
- * Easy to use,
+ * [Easy to use](docs/README.md#usage-examples),
  * [Stable and production ready](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder),
- * On-the-fly data object conversion,
+ * [On-the-fly data object conversion](docs/conversion.md),
  * API chaining support,
- * Localization support,
+ * [Localization support](docs/docs.md#messages-and-localization),
  * 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.
 
-----
 
 ## License ##
 

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.1",
+  "version": "9.0.2",
   "keywords": [
     "laravel",
     "json",
@@ -46,7 +46,7 @@
   },
   "require-dev": {
     "marcin-orlowski/coding-standard": "^1.3",
-    "marcin-orlowski/phpunit-extra-asserts": "^1.1",
+    "marcin-orlowski/phpunit-extra-asserts": "^1.2.0",
     "orchestra/testbench": "^4.0",
     "phpunit/phpunit": "^8.0",
     "phpunit/php-code-coverage": "^7.0",

docs/README.md

@@ -0,0 +1,23 @@
+![REST API Response Builder for Laravel](docs/img/logo.png)
+
+# REST API Response Builder for Laravel #
+
+ `ResponseBuilder` is [Laravel](https://laravel.com/)'s helper designed to build
+ nice, normalized and easy to consume REST API JSON responses.
+
+## Table of contents ##
+
+ * [Fundamentals](docs.md)
+ * [Requirements](requirements.md)
+ * [Installation](installation.md)
+ * [Configuration](config.md)
+ * [On-the-fly data conversion](conversion.md)
+ * [Usage examples](examples.md)
+ * [Exposed methods](methods.md)
+ * [Manipulating response JSON object](response.md)
+ * [Exception Handling](exceptions.md)
+ * [Unit testing](testing.md)
+ * [Important incompatibile changes](compatibility.md)
+
+ **Upgrading from previous version? Check [compatibility docs](compatibility.md) prior altering your `composer.json`!**
+

docs/compatibility.md

@@ -1,9 +1,27 @@
 ![REST API Response Builder for Laravel](img/logo.png)
 
-# REST API Response Builder for Laravel #
+# Backward compatibility #
 
+ [« Documentation table of contents](README.md)
 
-### v9 ###
+ * [Important incompatibile changes](#incompatibility-notes)
+   * [Changes in v9](#v9)
+   * [Changes in v8](#v8)
+   * [Changes in v7](#v7)
+   * [Changes in v6](#v6)
+   * [Changes in v5](#v5)
+   * [Changes in v4](#v4)
+   * [Changes in v3](#v3)
+   * [Changes in v2](#v2)
+   * [Changes in v1](#v1)
+
+---
+
+# Incompatibility notes #
+
+Backward (in)compatibility notes. Pay attention if you are upgrading. 
+
+## v9 ##
 
  * `[BREAKING]` Due to introduction of primitives support as direct payload, structure of `converter` config entry changed.
  * `[BREAKING]` Due to introduction of primitives support as direct payload, the content of `data` object in the response may differ
@@ -16,14 +34,14 @@
  * `[Low]` For better error reporting and handling, `ResponseBuilder` throws own, more descriptive exceptions in majority of cases. See [src/Exceptions](../src/Exceptions).
 
 
-### v8 ###
+## v8 ##
 
  * `[BREAKING]` Due to introduction of exception handlers, `ExceptionHandler` configuration has been changed.
    See [configuration docs](config.md#exception_handler) for more information.
  * `[Very Low]` Removed `ResponseBuilderLegacy` class from the package.
 
 
-### v7 ###
+## v7 ##
 
  * `[BREAKING]` As the library API migrated to Builder type of implementation, all the former API methods are now removed from
    `ResponseBuilder` class (with exception for `success()` and `error()` methods. While it is strongly recommended to switch
@@ -41,7 +59,7 @@
    feature **AND** pass objects directly (i.e. not as part of collection nor array).
 
 
-### v6 ###
+## v6 ##
 
  * Requires Laravel 6.0+ and PHP 7.2+
  * `[BREAKING]` In previous versions built-in reserved codes were hardcoded and always in range of 1-63 which, in general
@@ -68,24 +86,24 @@
    library. From now one you need to stick to default names now (`success`, `code`, `message`, `locale`, `data`).
  * `[Very Low] (v6.2)` 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.
-   See [Data Conversion](docs.md#data-conversion) for details.
+   See [Data Conversion](conversion.md) for details.
  * `[BREAKING] (v6.3)` This is backward incompatible change in signature of `RB::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.
+   (see [Manipulating Response Object](response.md)). If you do not, then you are not affected.
 
 
-### v5 ###
+## v5 ##
 
  * No public release.
 
 
-### v4 ###
+## v4 ##
 
  * `ApiCodeBase` class is now `BaseApiCodes`
  * ExceptionHandler's debug trace no longer depends on `APP_DEBUG` value and can be enabled independently
 
 
-### v3 ###
+## v3 ##
 
  * `success()` now accepts (optional) `api_code` too, therefore signature of this method as well as and argument
    order changed. This makes it **partially** incompatible with what have been in v2, however in majority of uses