diff --git a/README.md b/README.md index c7153049..ffa8e3d5 100644 --- a/README.md +++ b/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. diff --git a/tests/objects/AttributesObjectTest.php b/tests/objects/AttributesObjectTest.php index deb6a619..047e3d1a 100644 --- a/tests/objects/AttributesObjectTest.php +++ b/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']); + } }