Improve documentation and tests for extensions

README.md

@@ -166,6 +166,57 @@ Which will result in:
 
 This can be useful for development. For production usage, you can better construct an `ErrorsDocument` with only specific values.
 
+#### Using extensions and profiles
+
+The [Atomic Operations extension](https://jsonapi.org/ext/atomic/) and the [Cursor Pagination profile](https://jsonapi.org/profiles/ethanresnick/cursor-pagination/) come packaged along. Any 3rd party of self-made extension can be applied with:
+
+```php
+use alsvanzelf\jsonapi\ResourceDocument;
+use alsvanzelf\jsonapi\interfaces\ExtensionInterface;
+
+class ExampleExtension implements ExtensionInterface {
+	public function getOfficialLink() {
+		return 'https://example.org/extension-documentation';
+	}
+
+	public function getNamespace() {
+		return 'foo';
+	}
+}
+
+$document = new ResourceDocument('user', 42);
+$document->add('name', 'Zaphod Beeblebrox');
+
+$extension = new ExampleExtension();
+$document->applyExtension($extension);
+$document->addExtensionMember($extension, 'bar', 'baz');
+
+$document->sendResponse();
+```
+
+Which will result in:
+
+```json
+{
+    "foo:bar": "baz",
+    "jsonapi": {
+        "version": "1.1",
+        "ext": [
+            "https://example.org/extension-documentation"
+        ]
+    },
+    "data": {
+        "type": "user",
+        "id": "42",
+        "attributes": {
+            "name": "Zaphod Beeblebrox"
+        }
+    }
+}
+```
+
+A similar flow can be used for profiles.
+
 #### Other examples
 
 Examples for all kind of responses are in the [/examples](/examples) directory.

tests/objects/AttributesObjectTest.php

@@ -2,7 +2,9 @@
 
 namespace alsvanzelf\jsonapiTests\objects;
 
+use alsvanzelf\jsonapi\exceptions\InputException;
 use alsvanzelf\jsonapi\objects\AttributesObject;
+use alsvanzelf\jsonapiTests\extensions\TestExtension;
 use PHPUnit\Framework\TestCase;
 
 class AttributesObjectTest extends TestCase {
@@ -46,4 +48,38 @@ public function testAdd_WithObject() {
 		$this->assertArrayHasKey('bar', $array['foo']);
 		$this->assertSame('baz', $array['foo']['bar']);
 	}
+
+	/**
+	 * @group Extensions
+	 */
+	public function testAdd_BlocksExtensionMembersViaRegularAdd() {
+		$attributesObject = new AttributesObject();
+		$extension        = new TestExtension();
+		$extension->setNamespace('test');
+
+		$this->assertSame([], $attributesObject->toArray());
+
+		$this->expectException(InputException::class);
+		$this->expectExceptionMessage('invalid member name "test:foo"');
+
+		$attributesObject->add('test:foo', 'bar');
+	}
+
+	/**
+	 * @group Extensions
+	 */
+	public function testAddExtensionMember_HappyPath() {
+		$attributesObject = new AttributesObject();
+		$extension        = new TestExtension();
+		$extension->setNamespace('test');
+
+		$this->assertSame([], $attributesObject->toArray());
+
+		$attributesObject->addExtensionMember($extension, 'foo', 'bar');
+
+		$array = $attributesObject->toArray();
+
+		$this->assertArrayHasKey('test:foo', $array);
+		$this->assertSame('bar', $array['test:foo']);
+	}
 }