Merge pull request #56 from lode/request-helper

Author: lode

README.md

@@ -150,14 +150,19 @@ It has support for generating & sending documents with:
 - v1.1 extensions via profiles
 - v1.1 @-members for JSON-LD and others
 
+Also there's tools to help processing of incoming requests:
+
+- parse request options (include paths, sparse fieldsets, sort fields, pagination, filtering)
+- parse request documents for creating, updating and deleting resources and relationships
+
 Next to custom extensions, the following [official extensions](https://jsonapi.org/extensions/) are included:
 
 - Cursor Pagination ([example code](/examples/cursor_pagination_profile.php), [specification](https://jsonapi.org/profiles/ethanresnick/cursor-pagination/))
 
 Plans for the future include:
 
-- parse request options: sparse fields, sorting, pagination, filtering ([#44](https://github.com/lode/jsonapi/issues/44))
-- parse requests for creating, updating and deleting resources and relationships ([#5](https://github.com/lode/jsonapi/issues/5))
+- validate request options ([#58](https://github.com/lode/jsonapi/issues/58))
+- validate request documents ([#57](https://github.com/lode/jsonapi/issues/57))
 
 
 ## Contributing

composer.json

@@ -22,6 +22,10 @@
 		}
 	},
 	"require-dev": {
-		"phpunit/phpunit": "^5.7|^6.5|^7.5|^8.0"
+		"phpunit/phpunit": "^5.7|^6.5|^7.5|^8.0",
+		"psr/http-message": "^1.0"
+	},
+	"suggests": {
+		"psr/http-message": "Allows constructing requests from Psr RequestInterface"
 	}
 }

composer.lock

@@ -45,6 +45,7 @@ <h3>Relationship responses</h3>
 
 	<h3>Misc</h3>
 	<ul>
+		<li><a href="request_superglobals.php">Processing query parameters and request documents</a></li>
 		<li><a href="null_values.php">Null values if explicitly not available</a></li>
 		<li><a href="meta_only.php">Meta-only use-cases</a></li>
 		<li><a href="status_only.php">Status-only</a></li>

examples/index.html

@@ -0,0 +1,88 @@
+<?php
+
+use alsvanzelf\jsonapi\Document;
+use alsvanzelf\jsonapi\helpers\RequestParser;
+
+require 'bootstrap_examples.php';
+
+/**
+ * preparing request data in superglobals from a webserver
+ */
+$_GET = [
+	'include' => 'ship,ship.wing',
+	'fields' => [
+		'user' => 'name,location',
+	],
+	'sort' => 'name,-location',
+	'page' => [
+		'number' => '2',
+		'size'   => '10',
+	],
+	'filter' => '42',
+];
+$_POST = [
+	'data' => [
+		'type'       => 'user',
+		'id'         => '42',
+		'attributes' => [
+			'name' => 'Foo',
+		],
+		'relationships' => [
+			'ship' => [
+				'data' => [
+					'type' => 'ship',
+					'id'   => '42',
+				],
+			],
+		],
+	],
+	'meta' => [
+		'lock' => true,
+	],
+];
+
+$_SERVER['REQUEST_SCHEME'] = 'https';
+$_SERVER['HTTP_HOST']      = 'example.org';
+$_SERVER['REQUEST_URI']    = '/user/42?'.http_build_query($_GET);
+$_SERVER['CONTENT_TYPE']   = Document::CONTENT_TYPE_OFFICIAL;
+
+/**
+ * parsing the request
+ * 
+ * if you have a PSR request object you can use `$requestParser = RequestParser::fromPsrRequest($request);`
+ */
+$requestParser = RequestParser::fromSuperglobals();
+
+/**
+ * now you can check for certain query parameters and document values in an easy way
+ */
+
+// useful for filling a self link in responses
+var_dump($requestParser->getSelfLink());
+
+// useful for determining how to process the request (list/get/create/update)
+var_dump($requestParser->hasIncludePaths());
+var_dump($requestParser->hasSparseFieldset('user'));
+var_dump($requestParser->hasSortFields());
+var_dump($requestParser->hasPagination());
+var_dump($requestParser->hasFilter());
+
+// these methods often return arrays where comma separated query parameter values are processed for ease of use
+var_dump($requestParser->getIncludePaths());
+var_dump($requestParser->getSparseFieldset('user'));
+var_dump($requestParser->getSortFields());
+var_dump($requestParser->getPagination());
+var_dump($requestParser->getFilter());
+
+// use for determinging whether keys were given without having to dive deep into the POST data yourself
+var_dump($requestParser->hasAttribute('name'));
+var_dump($requestParser->hasRelationship('ship'));
+var_dump($requestParser->hasMeta('lock'));
+
+// get the raw data from the document, this doesn't (yet) return specific objects
+var_dump($requestParser->getAttribute('name'));
+var_dump($requestParser->getRelationship('ship'));
+var_dump($requestParser->getMeta('lock'));
+
+// get the full document for custom processing
+var_dump($requestParser->getDocument());