Support for spec 1.1 RC 2 & 3

README.md

@@ -181,17 +181,18 @@ It has support for generating & sending documents with:
 - resource collections
 - to-one and to-many relationships
 - errors (easily turning exceptions into jsonapi output)
-- v1.1 extensions via profiles
+- v1.1 extensions and 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:
+Next to custom extensions/profiles, the following [official extensions/profiles](https://jsonapi.org/extensions/) are included:
 
-- Cursor Pagination ([example code](/examples/cursor_pagination_profile.php), [specification](https://jsonapi.org/profiles/ethanresnick/cursor-pagination/))
+- Atomic Operations extension ([example code](/examples/atomic_operations_extension.php), [specification](https://jsonapi.org/ext/atomic/))
+- Cursor Pagination profile ([example code](/examples/cursor_pagination_profile.php), [specification](https://jsonapi.org/profiles/ethanresnick/cursor-pagination/))
 
 Plans for the future include:
 

examples/atomic_operations_extension.php

@@ -0,0 +1,33 @@
+<?php
+
+use alsvanzelf\jsonapi\objects\ResourceObject;
+use alsvanzelf\jsonapi\extensions\AtomicOperationsDocument;
+
+require 'bootstrap_examples.php';
+
+/**
+ * use the atomic operations extension as extension to the document
+ */
+
+$document = new AtomicOperationsDocument();
+
+$user1  = new ResourceObject('user', 1);
+$user2  = new ResourceObject('user', 2);
+$user42 = new ResourceObject('user', 42);
+
+$user1->add('name',  'Ford');
+$user2->add('name',  'Arthur');
+$user42->add('name', 'Zaphod');
+
+$document->addResults($user1);
+$document->addResults($user2);
+$document->addResults($user42);
+
+/**
+ * get the json
+ */
+
+$options = [
+	'prettyPrint' => true,
+];
+echo '<pre>'.$document->toJson($options);

examples/bootstrap_examples.php

@@ -2,7 +2,7 @@
 
 use alsvanzelf\jsonapi\Document;
 use alsvanzelf\jsonapi\ResourceDocument;
-use alsvanzelf\jsonapi\helpers\ProfileAliasManager;
+use alsvanzelf\jsonapi\interfaces\ExtensionInterface;
 use alsvanzelf\jsonapi\interfaces\ProfileInterface;
 use alsvanzelf\jsonapi\interfaces\ResourceInterface;
 
@@ -102,29 +102,59 @@ function getCurrentLocation() {
 	}
 }
 
-class ExampleVersionProfile extends ProfileAliasManager implements ProfileInterface {
+class ExampleVersionExtension implements ExtensionInterface {
 	/**
-	 * the required methods (next to extending ProfileAliasManager)
+	 * the required method
 	 */
 
 	public function getOfficialLink() {
-		return 'https://jsonapi.org/format/1.1/#profile-keywords-and-aliases';
+		return 'https://jsonapi.org/format/1.1/#extension-rules';
 	}
 
-	public function getOfficialKeywords() {
-		return ['version'];
+	public function getNamespace() {
+		return 'version';
 	}
 
 	/**
-	 * optionally helpers for the specific profile
+	 * optionally helpers for the specific extension
 	 */
 
 	public function setVersion(ResourceInterface $resource, $version) {
 		if ($resource instanceof ResourceDocument) {
-			$resource->addMeta($this->getKeyword('version'), $version, $level=Document::LEVEL_RESOURCE);
+			$resource->getResource()->addExtensionMember($this, 'id', $version);
 		}
 		else {
-			$resource->addMeta($this->getKeyword('version'), $version);
+			$resource->addExtensionMember($this, 'id', $version);
 		}
 	}
 }
+
+class ExampleTimestampsProfile implements ProfileInterface {
+	/**
+	 * the required method
+	 */
+
+	public function getOfficialLink() {
+		return 'https://jsonapi.org/recommendations/#authoring-profiles';
+	}
+
+	/**
+	 * optionally helpers for the specific profile
+	 */
+
+	public function setTimestamps(ResourceInterface $resource, \DateTimeInterface $created=null, \DateTimeInterface $updated=null) {
+		if ($resource instanceof ResourceIdentifierObject) {
+			throw new Exception('cannot add attributes to identifier objects');
+		}
+
+		$timestamps = [];
+		if ($created !== null) {
+			$timestamps['created'] = $created->format(\DateTime::ISO8601);
+		}
+		if ($updated !== null) {
+			$timestamps['updated'] = $updated->format(\DateTime::ISO8601);
+		}
+
+		$resource->add('timestamps', $timestamps);
+	}
+}

examples/errors_all_options.php

@@ -38,7 +38,7 @@
 $errorSpecApi->setHumanTitle($genericTitle='Too much options');
 $errorSpecApi->setHumanDetails($specificDetails='Please, choose a bit less. Consult your ...');
 $errorSpecApi->setAboutLink($specificAboutLink='https://www.example.com/explanation.html', ['foo'=>'bar']);
-$errorSpecApi->appendTypeLink($genericTypeLink='https://www.example.com/documentation.html', ['foo'=>'bar']);
+$errorSpecApi->setTypeLink($genericTypeLink='https://www.example.com/documentation.html', ['foo'=>'bar']);
 
 /**
  * prepare multiple error objects for the errors response

examples/extension.php

@@ -0,0 +1,37 @@
+<?php
+
+use alsvanzelf\jsonapi\Document;
+use alsvanzelf\jsonapi\ResourceDocument;
+use alsvanzelf\jsonapi\helpers\Converter;
+
+require 'bootstrap_examples.php';
+
+/**
+ * use an extension extend the document with new members
+ */
+
+$extension = new ExampleVersionExtension();
+
+$document = new ResourceDocument('user', 42);
+$document->applyExtension($extension);
+
+$document->add('foo', 'bar');
+
+/**
+ * you can apply the rules of the extension manually
+ * or use methods of the extension if provided
+ */
+
+$extension->setVersion($document, '2019');
+
+/**
+ * get the json
+ */
+
+$contentType = Converter::prepareContentType(Document::CONTENT_TYPE_OFFICIAL, [$extension], []);
+echo '<code>Content-Type: '.$contentType.'</code>'.PHP_EOL;
+
+$options = [
+	'prettyPrint' => true,
+];
+echo '<pre>'.$document->toJson($options);

examples/index.html

@@ -49,7 +49,9 @@ <h3>Misc</h3>
 		<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>
-		<li><a href="example_profile.php">Example profile</a></li>
+		<li><a href="extension.php">Example extension</a></li>
+		<li><a href="atomic_operations_extension.php">Atomic operations extension</a></li>
+		<li><a href="profile.php">Example profile</a></li>
 		<li><a href="cursor_pagination_profile.php">Cursor pagination profile</a></li>
 		<li><a href="output.php">Different ways to output</a></li>
 	</ul>

examples/profile.php

@@ -0,0 +1,39 @@
+<?php
+
+use alsvanzelf\jsonapi\Document;
+use alsvanzelf\jsonapi\ResourceDocument;
+use alsvanzelf\jsonapi\helpers\Converter;
+
+require 'bootstrap_examples.php';
+
+/**
+ * use a profile to define rules for members
+ */
+
+$profile = new ExampleTimestampsProfile();
+
+$document = new ResourceDocument('user', 42);
+$document->applyProfile($profile);
+
+$document->add('foo', 'bar');
+
+/**
+ * you can apply the rules of the profile manually
+ * or use methods of the profile if provided
+ */
+
+$created = new \DateTime('-1 year');
+$updated = new \DateTime('-1 month');
+$profile->setTimestamps($document, $created, $updated);
+
+/**
+ * get the json
+ */
+
+$contentType = Converter::prepareContentType(Document::CONTENT_TYPE_OFFICIAL, [], [$profile]);
+echo '<code>Content-Type: '.$contentType.'</code>'.PHP_EOL;
+
+$options = [
+	'prettyPrint' => true,
+];
+echo '<pre>'.$document->toJson($options);