refactor: add draft for ResourceResolver

refs #8

Author: Thorsten Suckow-Homberg

src/JsonApi/Resource/Resource.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\JsonApi\Resource;
+
+use Conjoon\Net\Uri\Component\Path\Template;
+
+/**
+ * Interface for Resources that serve as conceptually representatives for discoverable entities.
+ */
+interface Resource
+{
+    /**
+     * Returns the URI template where this resource is located  found.
+     *
+     * @return Template
+     */
+    public function getUri(): Template;
+}

src/JsonApi/Resource/ResourceCollection.php

@@ -0,0 +1,37 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\JsonApi\Resource;
+
+/**
+ * Tagging interface for Resources that represent resource collections.
+ */
+interface ResourceCollection extends Resource
+{
+}

src/JsonApi/Resource/ResourceList.php

@@ -0,0 +1,92 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\JsonApi\Resource;
+
+use Conjoon\Core\AbstractList;
+use InvalidArgumentException;
+use OutOfBoundsException;
+use TypeError;
+
+/**
+ * An abstract list maintaining entities of the type Resource.
+ * This implementation makes sure that no URI duplicates may exist in a ResourceList-object.
+ *
+ * @extends AbstractList<Resource>
+ */
+class ResourceList extends AbstractList
+{
+    /**
+     * @inheritdoc
+     *
+     * @throws InvalidArgumentException|OutOfBoundsException|TypeError
+     */
+    public function offsetSet(mixed $offset, mixed $value): void
+    {
+        $this->assertTypeFor($value);
+
+        /**
+         * @var Resource $value
+         */
+        $value = $this->uriExists($value);
+
+        $this->doInsert($offset, $value);
+    }
+
+    /**
+     * Returns the Resource itself if its URI does not already exist in *this* ResourceList.
+     *
+     * @param Resource $resource
+     * @return Resource
+     *
+     * @throws InvalidArgumentException if the URI of the resource was already registered with
+     * this ResourceList.
+     */
+    private function uriExists(Resource $resource): Resource
+    {
+        $uri = $resource->getUri();
+
+        if (count(array_filter($this->data, fn ($res) => $res->getUri()->equals($uri))) > 0) {
+            throw new InvalidArgumentException(
+                "A resource for the URI \"" . $uri->toString() . "\" already exists"
+            );
+        }
+
+        return $resource;
+    }
+
+
+    /**
+     * @return string
+     */
+    public function getEntityType(): string
+    {
+        return Resource::class;
+    }
+}

src/JsonApi/Resource/ResourceResolver.php

@@ -0,0 +1,98 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Conjoon\JsonApi\Resource;
+
+use Conjoon\Net\Uri;
+
+/**
+ * Provides functionality for resolving URIs to an actual resource.
+ *
+ * @example
+ *
+ *    class EmployeeResource implements Resource {
+ *        public function getUri(): Template
+ *        {
+ *            return new Template("/directory/employees/{id}");
+ *        }
+ *    }
+ *
+ *    class EmployeeResourceCollection extends EmployeeResource implements ResourceCollection
+ *    {
+ *        public function getUri(): Template
+ *        {
+ *            return new Template("/directory/employees");
+ *        }
+ *    }
+ *
+ *    $resources = [
+ *       new EmployeeResource(),
+ *       new EmployeeResourceCollection()
+ *   ];
+ *
+ *   $resolver = new ResourceResolver(ResourceList::make(...$resources));
+ *   $resolver->resolve(Uri::make("https://localhost:8080/directory/employees/1")); // EmployeeResource
+ *   $resolver->resolve(Uri::make("https://localhost:8080/directory/employees")); // EmployeeResourceCollection
+ *   $resolver->resolve(Uri::make("https://localhost:8080/directory/shipments")); // null
+ *
+ */
+class ResourceResolver
+{
+    /**
+     * @var ResourceList
+     */
+    private ResourceList $locations;
+
+
+    /**
+     * @param ResourceList $locations
+     */
+    public function __construct(ResourceList $locations)
+    {
+        $this->locations = $locations;
+    }
+
+
+    /**
+     * Resolves the specified URI and returns the Resource that is located there.
+     * Returns null if the URI did not target a registered resource with this ResourceResolver.
+     *
+     * @param Uri $uri
+     * @return Resource|null
+     */
+    public function resolve(Uri $uri): ?Resource
+    {
+        foreach ($this->locations as $location) {
+            if ($location->getUri()->match($uri) !== null) {
+                return $location;
+            }
+        }
+        return null;
+    }
+}

tests/JsonApi/Resource/ResourceListTest.php

@@ -0,0 +1,99 @@
+<?php
+
+/**
+ * conjoon
+ * php-lib-conjoon
+ * Copyright (C) 2022 Thorsten Suckow-Homberg https://github.com/conjoon/php-lib-conjoon
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ * USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+declare(strict_types=1);
+
+namespace Tests\Conjoon\JsonApi\Resource;
+
+use Conjoon\Core\AbstractList;
+use Conjoon\JsonApi\Resource\Resource;
+use Conjoon\JsonApi\Resource\ResourceList;
+use Conjoon\Net\Uri\Component\Path\Template;
+use InvalidArgumentException;
+use PHPUnit\Framework\MockObject\MockObject;
+use Tests\TestCase;
+
+/**
+ * tests ResourceList
+ */
+class ResourceListTest extends TestCase
+{
+    /**
+     * Tests constructor
+     */
+    public function testClass(): void
+    {
+        $list = $this->createList();
+        $this->assertInstanceOf(AbstractList::class, $list);
+
+        $this->assertSame(Resource::class, $list->getEntityType());
+    }
+
+
+    /**
+     * tests offsetSet(), makes sure no URI duplicates may occur
+     * @return void
+     */
+    public function testOffsetSet(): void
+    {
+        $resource = function (string $uri): MockObject&Resource {
+            /**
+             * @var MockObject&Resource $res
+             */
+            $res = $this->createMockForAbstract(Resource::class, ["getUri"]);
+            $res->expects($this->any())->method("getUri")->willReturn(new Template($uri));
+            return $res;
+        };
+
+        $resourceList = new ResourceList();
+        $resourceList[] = $resource("/uri1");
+        $resourceList[] = $resource("/uri2");
+        $resourceList[] = $resource("/uri3");
+
+        try {
+            $resourceList[] = $resource("/uri2");
+            $this->fail();
+        } catch (InvalidArgumentException $e) {
+            $this->assertStringContainsString(
+                strtolower("a resource for the URI \"/uri2\" already exists"),
+                strtolower($e->getMessage())
+            );
+        }
+    }
+
+
+    /**
+     * @return ResourceList
+     */
+    protected function createList(): ResourceList
+    {
+        $list = new ResourceList();
+
+
+        return $list;
+    }
+}