New Helper methods parseResponseBody(), isValidResponseBody(), isValidRequestBody()

CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- New method `Utils\Helper::parseResponseBody()` to parse a JSON API response body
+- New method `Utils\Helper::isValidResponseBody()` to validate a JSON API response body
+- New method `Utils\Helper::isValidRequestBody()` to validate a JSON API request body with optional item id
+
+### Deprecated
+
+- `Utils\Helper::parse()` will be removed in v1.0, use `Utils\Helper::parseResponseBody()` instead
+- `Utils\Helper::isValid()` will be removed in v1.0, use `Utils\Helper::isValidResponseBody()` instead
+
 ## [0.8.1] - 2017-06-01
 
 ### Fixed

README.md

@@ -68,7 +68,7 @@ JsonApiClient can be used as a validator for JSON API contents:
 ```php
 $wrong_jsonapi = '{"data":{},"meta":{"info":"This is wrong JSON API. `data` has to be `null` or containing at least `type` and `id`."}}';
 
-if ( \Art4\JsonApiClient\Utils\Helper::isValid($wrong_jsonapi) )
+if ( \Art4\JsonApiClient\Utils\Helper::isValidResponseBody($wrong_jsonapi) )
 {
 	echo 'string is valid.';
 }

composer.json

@@ -3,20 +3,20 @@
     "type": "library",
     "description": "JSON API client",
     "homepage": "https://github.com/Art4/json-api-client",
-    "keywords": ["json", "api", "json-api", "client", "reader", "validator"],
-    "license": "GPL2",
+    "keywords": ["json", "api", "json-api", "client", "reader", "validator", "parser"],
+    "license": "GPL3",
     "authors": [
         {
             "name": "Artur Weigandt",
             "email": "art4@wlabs.de",
-            "homepage": "http://wlabs.de"
+            "homepage": "https://wlabs.de"
         }
     ],
     "require": {
         "php": "^5.5 || ^7.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^4.8.35 || ^6.0"
+        "phpunit/phpunit": "^4.8.35 || ^5.4.3 || ^6.0"
     },
     "autoload": {
         "psr-4": {
@@ -27,5 +27,11 @@
         "psr-4": {
             "Art4\\JsonApiClient\\Tests\\": "tests"
         }
+    },
+    "config": {
+        "//platform": {
+            "php": "5.5"
+        },
+        "sort-packages": true
     }
 }

docs/exception-introduction.md

@@ -23,7 +23,7 @@ $wrong_jsonapi = '{"data":{},"meta":{"info":"This is wrong JSON API. `data` has
 
 try
 {
-	$document = \Art4\JsonApiClient\Utils\Helper::parse($wrong_jsonapi);
+	$document = \Art4\JsonApiClient\Utils\Helper::parseResponseBody($wrong_jsonapi);
 }
 catch (\Art4\JsonApiClient\Exception\ValidationException $e)
 {

docs/objects-document.md

@@ -29,7 +29,7 @@ You can check for all possible values using the `has()` method.
 ```php
 $jsonapi_string = '{"meta":{"info":"Testing the JsonApiClient library."}}';
 
-$document = \Art4\JsonApiClient\Utils\Helper::parse($jsonapi_string);
+$document = \Art4\JsonApiClient\Utils\Helper::parseResponseBody($jsonapi_string);
 
 var_dump($document->has('data'));
 var_dump($document->has('errors'));

docs/objects-introduction.md

@@ -54,7 +54,7 @@ You can check for all possible values using the `has()` method.
 ```php
 $jsonapi_string = '{"meta":{"info":"Testing the JsonApiClient library."}}';
 
-$document = \Art4\JsonApiClient\Utils\Helper::parse($jsonapi_string);
+$document = \Art4\JsonApiClient\Utils\Helper::parseResponseBody($jsonapi_string);
 
 var_dump($document->has('meta'));
 ```

docs/utils-helper.md

@@ -3,16 +3,16 @@
 
 The `Utils\Helper` provides some useful methods to deal with JSON.
 
-### Parse a JSON API body
+### Parse a JSON API response body
 
-Assuming you have get a response from a JSON API server. Use `parse()` to work with the data.
+Assuming you have get a response from a JSON API server. Use `parseResponseBody()` to work with the data.
 
 ```php
 
 // The Response body from a JSON API server
 $jsonapi_string = '{"meta":{"info":"Testing the JsonApiClient library."}}';
 
-$document = \Art4\JsonApiClient\Utils\Helper::parse($jsonapi_string);
+$document = \Art4\JsonApiClient\Utils\Helper::parseResponseBody($jsonapi_string);
 ```
 
 This returns a [Document](objects-document.md) object which provided all contents.
@@ -41,12 +41,12 @@ This returns a [Document](objects-document.md) object which provided all content
 
 ### Validate a JSON API response body
 
-JsonApiClient can be used as a validator:
+JsonApiClient can be used as a validator for a response body:
 
 ```php
 $wrong_jsonapi = '{"data":{},"meta":{"info":"This is wrong JSON API. `data` has to be `null` or containing at least `type` and `id`."}}';
 
-if ( \Art4\JsonApiClient\Utils\Helper::isValid($wrong_jsonapi) )
+if ( \Art4\JsonApiClient\Utils\Helper::isValidResponseBody($wrong_jsonapi) )
 {
 	echo 'string is valid.';
 }
@@ -57,3 +57,22 @@ else
 
 // echos 'string is invalid json api!'
 ```
+
+### Validate a JSON API request body
+
+JsonApiClient can also be used as a validator for a request body:
+
+```php
+$wrong_jsonapi = '{"data":{"type":"post","attributes":{"body":"The post body"}}}';
+
+if ( \Art4\JsonApiClient\Utils\Helper::isValidRequestBody($wrong_jsonapi) )
+{
+	echo 'string is valid.';
+}
+else
+{
+	echo 'string is invalid json api!';
+}
+
+// echos 'string is valid.'
+```

src/Utils/Helper.php

@@ -39,7 +39,7 @@ final class Helper
 	 *
 	 * @throws ValidationException
 	 */
-	public static function parse($json_string)
+	public static function parseResponseBody($json_string)
 	{
 		$data = static::decodeJson($json_string);
 
@@ -78,16 +78,53 @@ public static function parseRequestBody($json_string)
 	}
 
 	/**
-	 * Checks if a string is a valid JSON API
+	 *
+	 * @deprecated since version 0.9, to be removed in 1.0. Use parseResponseBody() instead
+	 *
+	 * @param string $json_string
+	 *
+	 * @return Document
+	 *
+	 * @throws ValidationException
+	 */
+	public static function parse($json_string)
+	{
+		@trigger_error(__METHOD__ . ' is deprecated since version 0.9 and will be removed in 1.0. Use parseResponseBody() instead', E_USER_DEPRECATED);
+
+		return static::parseResponseBody($json_string);
+	}
+
+	/**
+	 * Checks if a string is a valid JSON API response body
 	 *
 	 * @param string $json_string
 	 * @return bool true, if $json_string contains valid JSON API, else false
 	 */
-	public static function isValid($json_string)
+	public static function isValidResponseBody($json_string)
+	{
+		try
+		{
+			static::parseResponseBody($json_string);
+		}
+		catch ( Exception $e )
+		{
+			return false;
+		}
+
+		return true;
+	}
+
+	/**
+	 * Checks if a string is a valid JSON API request body
+	 *
+	 * @param string $json_string
+	 * @return bool true, if $json_string contains valid JSON API, else false
+	 */
+	public static function isValidRequestBody($json_string)
 	{
 		try
 		{
-			static::parse($json_string);
+			static::parseRequestBody($json_string);
 		}
 		catch ( Exception $e )
 		{
@@ -97,6 +134,21 @@ public static function isValid($json_string)
 		return true;
 	}
 
+	/**
+	 * Checks if a string is a valid JSON API
+	 *
+	 * @deprecated since version 0.9, to be removed in 1.0. Use isValidResponseBody() instead
+	 *
+	 * @param string $json_string
+	 * @return bool true, if $json_string contains valid JSON API, else false
+	 */
+	public static function isValid($json_string)
+	{
+		@trigger_error(__METHOD__ . ' is deprecated since version 0.9 and will be removed in 1.0. Use parseResponseBody() instead', E_USER_DEPRECATED);
+
+		return static::isValidResponseBody($json_string);
+	}
+
 	/**
 	 * Decodes a json string
 	 *

tests/Fixtures/TestCase.php

@@ -113,4 +113,19 @@ public function setExpectedException($exceptionName, $exceptionMessage = '', $ex
 			$this->expectExceptionCode($exceptionCode);
 		}
 	}
+
+	/**
+	 * Shim for PHPUnit 4
+	 *
+	 * @param mixed  $exceptionName
+	 */
+	public function expectException($exceptionName)
+	{
+		if (is_callable('parent::expectException'))
+		{
+			return parent::expectException($exceptionName);
+		}
+
+		$this->setExpectedException($exceptionName);
+	}
 }

tests/Integration/DotNotationTest.php

@@ -32,7 +32,7 @@ class DotNotationTest extends \Art4\JsonApiClient\Tests\Fixtures\TestCase
 	public function testCompleteResourceObjectWithMultipleRelationships()
 	{
 		$string = $this->getJsonString('04_complete_document_with_multiple_relationships.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 
@@ -197,7 +197,7 @@ public function testCompleteResourceObjectWithMultipleRelationships()
 	public function testGetNotExistentValueThrowsException()
 	{
 		$string = $this->getJsonString('05_simple_meta_object.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		// Test 3 segments, segment 2 don't exists
 		$this->assertFalse($document->has('meta.foobar.zap'));

tests/Integration/ErrorParsingTest.php

@@ -32,7 +32,7 @@ class ErrorParsingTest extends \Art4\JsonApiClient\Tests\Fixtures\TestCase
 	public function testParseErrors()
 	{
 		$string = $this->getJsonString('09_errors.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertTrue($document->has('errors'));
@@ -107,7 +107,7 @@ public function testParseErrors()
 	public function testParseErrorWithLinks()
 	{
 		$string = $this->getJsonString('10_error_with_links.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertTrue($document->has('errors'));

tests/Integration/ParsingTest.php

@@ -32,7 +32,7 @@ class ParsingTest extends \Art4\JsonApiClient\Tests\Fixtures\TestCase
 	public function testParseSimpleResource()
 	{
 		$string = $this->getJsonString('01_simple_resource.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -63,7 +63,7 @@ public function testParseSimpleResource()
 	public function testParseSimpleResourceIdentifier()
 	{
 		$string = $this->getJsonString('02_simple_resource_identifier.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -90,7 +90,7 @@ public function testParseSimpleResourceIdentifier()
 	public function testParseResourceObject()
 	{
 		$string = $this->getJsonString('03_resource_object.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -161,7 +161,7 @@ public function testParseResourceObject()
 	public function testParseCompleteResourceObjectWithMultipleRelationships()
 	{
 		$string = $this->getJsonString('04_complete_document_with_multiple_relationships.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -339,7 +339,7 @@ public function testParseCompleteResourceObjectWithMultipleRelationships()
 	public function testParsePaginationExample()
 	{
 		$string = $this->getJsonString('06_pagination_example.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertTrue($document->has('data'));
@@ -396,7 +396,7 @@ public function testParsePaginationExample()
 	public function testParseRelationshipExample()
 	{
 		$string = $this->getJsonString('07_relationship_example_without_data.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertTrue($document->has('data'));
@@ -465,7 +465,7 @@ public function testParseRelationshipExample()
 	public function testParseObjectLinksExample()
 	{
 		$string = $this->getJsonString('08_object_links.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertTrue($document->has('links'));
@@ -511,7 +511,7 @@ public function testParseObjectLinksExample()
 	public function testParseResourceIdentifierWithMeta()
 	{
 		$string = $this->getJsonString('11_resource_identifier_with_meta.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -540,7 +540,7 @@ public function testParseResourceIdentifierWithMeta()
 	public function testParseNullResource()
 	{
 		$string = $this->getJsonString('12_null_resource.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));
@@ -564,7 +564,7 @@ public function testParseNullResource()
 	public function testParseResourceIdentifierCollectionWithMeta()
 	{
 		$string = $this->getJsonString('13_collection_with_resource_identifier_with_meta.json');
-		$document = Helper::parse($string);
+		$document = Helper::parseResponseBody($string);
 
 		$this->assertInstanceOf('Art4\JsonApiClient\Document', $document);
 		$this->assertFalse($document->has('errors'));