Merge pull request #24 from MarcinOrlowski/rb-17-allow-api-codes-with…

…-success-methods-too

[RB-17] allow api codes with success methods. Closes #17

.travis.yml

@@ -13,23 +13,40 @@
 
 language: php
 
-# PHP versions to test package against
 php:
-  # using major version aliases
   - 5.5
   - 5.6
   - 7.0
   - 7.1
   - hhvm
 
+env:
+  - LARAVEL_VERSION="5.1"
+  - LARAVEL_VERSION="5.2"
+  - LARAVEL_VERSION="5.3"
+  - LARAVEL_VERSION="5.4"
+
+matrix:
+  exclude:
+    - php: 5.5
+      env: LARAVEL_VERSION="5.3"
+    - php: 5.5
+      env: LARAVEL_VERSION="5.4"
+
+cache:
+  directories:
+    - ${HOME}/.composer/cache/files
+
 before_script:
-#  - rm -f ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/xdebug.ini
-  - flags="--prefer-dist"
-  - composer install $flags
+#   Disable coverage (hhvm does not feature xdebug)
+  - if [ $TRAVIS_PHP_VERSION != hhvm ] ; then phpenv config-rm xdebug.ini ; fi
+  - cp -f "travis/composer-${LARAVEL_VERSION}.json" composer.json
+  - FLAGS="--prefer-dist"
+  - composer install ${FLAGS}
 
-# omitting "script:" will default to phpunit
 script:
-  - phpunit --configuration phpunit.xml --coverage-clover /tmp/coverage.xml
+  - vendor/bin/phpunit --configuration phpunit.xml --coverage-clover /tmp/coverage.xml
 
-after_script:
-  - vendor/bin/codacycoverage clover /tmp/coverage.xml
+after_success:
+#   IF coverage file is generated then upload it to Codacy
+  - if [ -f /tmp/coverage.xml ] ; then vendor/bin/codacycoverage clover /tmp/coverage.xml ; fi

CHANGES.md

@@ -1,16 +1,23 @@
 # API Response Builder for Laravel 5 #
 
+
+See [compatibility docs](docs/compatibility.md) for details about backward compatibility!
+
+
 ## CHANGE LOG ##
 
 * dev
-   * Corrected default config file having `use` entries
+   * **PARTIAL BACKWARD INCOMPATIBILITY**
+   * [RB-17] `success()` now allows to return api code as well
+   * Corrected default config file containing faulty and unneeded `use` entries
    * [RB-20] Renamed ErrorCode to ApiCodeBase
    * ApiCodeBase's `getMinCode()` and `getMaxCode()` are now `public`
    * Improved error messages to be even more informative
    * All exceptions due to misconfiguration have `CONFIG: ` message prefix now
    * Renamed error_code param to api_code in all method signatures
    * `:api_code` is now code placeholder in strings (`:error_code` is still supported for compatibility, but obsolete)
    * Default HTTP codes are now declared as constants `DEFAULT_HTTP_CODE_xxx` if you need to know them
+   * ApiCodeBase::getMap() now ensures `map` config entry of expected `array` type
 
 * v2.2.1 (2017-02-20)
    * Documentation split into separate files

README.md

@@ -3,11 +3,9 @@
 `ResponseBuilder` is Laravel5's helper designed to simplify building
 nice, normalized and easy to consume REST API responses.
 
-
 [![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)
-[![Codacy 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)
-[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/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_Coverage)
+[![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)
 [![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)
 
@@ -17,12 +15,14 @@ nice, normalized and easy to consume REST API responses.
 [![Build Status](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder.svg?branch=dev)](https://travis-ci.org/MarcinOrlowski/laravel-api-response-builder)
 
 ## Table of contents ##
+
+ **Upgrading from previous version? Ensure you read [compatibility docs](docs/compatibility.md) prior altering your `composer.json`!**
 
  * [Features](#features)
  * [Documentation](docs/docs.md)
  * [Bugs reports and pull requests](#contributing)
  * [License](#license)
- * [Changelog](#changelog)
+ * [Changelog](CHANGES.md)
 
 ----
 
@@ -73,15 +73,3 @@ Thanks in advance!
 
 * Written and copyrighted &copy;2016-2017 by Marcin Orlowski <mail (#) marcinorlowski (.) com>
 * ResponseBuilder is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)
-
-----
-
-## Notes ##
-
-* `ResponseBuilder` is **not** compatible with Lumen framework, mainly due to lack of Lang class. If you would like to help making `ResponseBuilder` usable with Lumen, speak up or (better) send pull request!
-
-----
-
-## Changelog ##
-
- See [CHANGES.md](CHANGES.md) for detailed revision history.

composer.json

@@ -2,7 +2,7 @@
   "name": "marcin-orlowski/laravel-api-response-builder",
   "description": "Helps building nice, normalized and easy to consume REST API responses.",
   "homepage": "https://github.com/MarcinOrlowski/laravel-api-response-builder",
-  "version": "2.2.1",
+  "version": "3.0.0",
   "keywords": [
     "laravel",
     "json",
@@ -39,10 +39,10 @@
   "require-dev": {
     "marcin-orlowski/coding-standard": "^1.1",
     "phpunit/phpunit": "^4.8",
+    "phpunit/php-code-coverage": "^2.2.4",
     "mockery/mockery": "^0.9.8",
     "orchestra/testbench": "~3.1",
-    "laravel/framework": ">=5.1.45 <5.2",
-    "phpunit/php-code-coverage": "^2.2.4",
+    "laravel/framework": "^5.1",
     "codacy/coverage": "^1.0"
   }
 }

docs/compatibility.md

@@ -0,0 +1,21 @@
+# API Response Builder for Laravel 5 #
+
+ `ResponseBuilder` follows [Semantic Versioning](http://semver.org/).
+
+ You need to worry about backward compatibility if you are upgrading from previous major version of the package.
+
+### 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
+ this change should pose no threat at all. If you were just calling `success()` or `success($data)` (which is 
+ 99,9% of use cases) then you are all fine and no change is needed. But if you were setting own 
+ `http_code` or `lang_args` when calling `success()` then you need to update your code. 
+
+### v2 ###
+
+ * First public release.
+
+### v1 ###
+
+ * Initial (internal) release

docs/docs.md

@@ -18,7 +18,7 @@ nice, normalized and easy to consume REST API responses.
  * [Overriding built-in messages](#overriding-built-in-messages)
  * [License](#license)
  * [Notes](#notes)
- * [Changelog](#changelog)
+ * [Changelog](CHANGES.md)
 
 ----
 
@@ -266,7 +266,7 @@ See [W3 specs page](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) for
 
 #### Reporting Success ####
 
-    success($data = null, $http_code = HttpResponse::HTTP_OK, array $lang_args = []);
+    success($data = null, $api_code = null, array $lang_args = [], $http_code = null);
     successWithHttpCode($http_code);
 
 Usage restrictions:
@@ -562,9 +562,3 @@ You can use `:api_code` placeholder in the message and it will be substituted ac
 ## Notes ##
 
 * `ResponseBuilder` is **not** compatible with Lumen framework, mainly due to lack of Lang class. If you would like to help making `ResponseBuilder` usable with Lumen, speak up or (better) send pull request!
-
-----
-
-## Changelog ##
-
- See [CHANGES.md](CHANGES.md) for detailed revision history.

src/ApiCodeBase.php

@@ -101,7 +101,7 @@ public static function getMaxCode()
 		$max_code = Config::get('response_builder.max_code', null);
 
 		if ($max_code === null) {
-			throw new \RuntimeException('CONFIG: Missing "min_code" key');
+			throw new \RuntimeException('CONFIG: Missing "max_code" key');
 		}
 
 		return $max_code;
@@ -153,13 +153,18 @@ public static function getMap()
 			throw new \RuntimeException('CONFIG: Missing "map" key');
 		}
 
+		if (!is_array($map)) {
+			throw new \RuntimeException('CONFIG: "map" must be an array');
+		}
+
+		/** @noinspection AdditionOperationOnArraysInspection */
 		return $map + static::$base_map;
 	}
 
 	/**
-	 * Returns locale mappings for given base error code or null if there's no mapping
+	 * Returns locale mappings for given base error code or @null if there's no mapping
 	 *
-	 * @param integer $code Base (built-in) code to look for string mapping for.
+	 * @param integer $code Base (built-in) code to look for mapped message for.
 	 *
 	 * @return string|null
 	 *
@@ -168,33 +173,37 @@ public static function getMap()
 	public static function getBaseMapping($code)
 	{
 		if (($code < ApiCodeBase::RESERVED_MIN_API_CODE) || ($code > ApiCodeBase::RESERVED_MAX_API_CODE)) {
-			throw new \InvalidArgumentException("Base message code {$code} is out of allowed reserved range");
+			throw new \InvalidArgumentException(
+				sprintf('Base code value (%d) is out of allowed reserved range %d-%d',
+					$code, ApiCodeBase::RESERVED_MIN_API_CODE, ApiCodeBase::RESERVED_MAX_API_CODE));
 		}
 
-		return array_key_exists($code, static::$base_map) ? static::$base_map[ $code ] : null;
+		return array_key_exists($code, static::$base_map)
+			? static::$base_map[ $code ]
+			: null;
 	}
 
 
 	/**
-	 * Returns locale mappings for given error code or null if there's no mapping
+	 * Returns locale mappings for given error code or @null if there's no mapping
 	 *
-	 * @param integer $code Code to look for string mapping for.
+	 * @param integer $api_code Api code to look for mapped message for.
 	 *
 	 * @return string|null
 	 *
 	 * @throws \InvalidArgumentException If $code is not in allowed range.
 	 */
-	public static function getMapping($code)
+	public static function getMapping($api_code)
 	{
-		if (!static::isCodeValid($code)) {
-			$msg = sprintf("API code value ({$code}) is out of allowed range %d-%d",
-				static::getMinCode(), static::getMaxCode());
+		if (!static::isCodeValid($api_code)) {
+			$msg = sprintf('API code value (%d) is out of allowed range %d-%d',
+				$api_code, static::getMinCode(), static::getMaxCode());
 			throw new \InvalidArgumentException($msg);
 		}
 
 		$map = static::getMap();
 
-		return array_key_exists($code, $map) ? $map[ $code ] : null;
+		return array_key_exists($api_code, $map) ? $map[ $api_code ] : null;
 	}
 
 	/**

src/ExceptionHandlerHelper.php

@@ -44,13 +44,8 @@ public static function render($request, Exception $exception)
 					break;
 
 				default:
-					$msg = trim($exception->getMessage());
-					if ($msg === '') {
-						$msg = 'Exception code #' . $exception->getStatusCode();
-					}
-
 					$result = static::error($exception, 'http_exception', ApiCodeBase::EX_HTTP_EXCEPTION,
-						HttpResponse::HTTP_BAD_REQUEST, ['message' => $msg]);
+						HttpResponse::HTTP_BAD_REQUEST);
 					break;
 			}
 		} else {