fix: add missing resource link functionality (#644)

Closes #643

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file. This projec
 ### Fixed
 
 - [#642](https://github.com/cloudcreativity/laravel-json-api/pull/642) Add missing resource meta functionality.
+- [#643](https://github.com/cloudcreativity/laravel-json-api/issues/643) Add missing resource link functionality.
 
 ## [6.0.0] - 2023-02-14
 

docs/basics/schemas.md

@@ -384,20 +384,35 @@ By default all resource objects will be encoded with their `self` link, e.g.:
 }
 ```
 
-You can change this behaviour by overloading the `getResourceLinks` or `getIncludedResourceLinks` methods.
-For example:
+You can change this behaviour by implementing the `getResourceLinks` method. For example, if you do not want any links
+to be serialized:
 
 ```php
 class Schema extends SchemaProvider
 {
     // ...
 
-    public function getResourceLinks($resource)
+    public function getResourceLinks($resource): ?array
     {
-        $links = parent::getResourceLinks($resource);
-        $links['foo'] = $this->createLink('posts/foo');
+        return null;
+    }
+}
+```
+
+If you return an array without any `self` key in it, the `self` link will be automatically added. If you do not want
+the `self` link to be set, set the array key `self` to `false`.
+
+```php
+class Schema extends SchemaProvider
+{
+    // ...
 
-        return $links;
+    public function getResourceLinks($resource): array
+    {
+        return [
+            // "self" will automatically be added as it is not set to false.
+            'foo' => $this->createLink('posts/foo'),
+        ];
     }
 
 }
@@ -423,9 +438,6 @@ This would result in the following resource object:
 > The `createLink` method allows you to pass in link meta and set whether the URI is relative to the API or an
 absolute path.
 
-If you want to only change the links when the resource is appearing in the `included` section of the JSON API
-document, overload the `getIncludedResourceLinks()` method instead.
-
 ## Meta
 
 You can add top-level `meta` to your resource object using the `getResourceMeta()` method

src/Schema/Schema.php

@@ -102,6 +102,30 @@ public function getRelationships($resource, ContextInterface $context): iterable
         }
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getLinks($resource): iterable
+    {
+        $links = [];
+
+        if (method_exists($this->provider, 'getResourceLinks')) {
+            $links = $this->provider->getResourceLinks($resource);
+        }
+
+        if ($links === null) {
+            return [];
+        }
+
+        $self = $links[LinkInterface::SELF] ?? null;
+
+        if (!$self instanceof LinkInterface && $self !== false) {
+            $links[LinkInterface::SELF] = $this->getSelfLink($resource);
+        }
+
+        return $links;
+    }
+
     /**
      * @inheritDoc
      */

src/Schema/SchemaProvider.php

@@ -30,7 +30,7 @@
 abstract class SchemaProvider implements SchemaProviderInterface
 {
     /**
-     * @var string|null
+     * @var string
      */
     protected string $resourceType = '';
 
@@ -134,10 +134,8 @@ public function getSelfSubUrl(object $resource = null): string
      */
     public function getSelfSubLink(object $resource): LinkInterface
     {
-        return $this->factory->createLink(
-            true,
+        return $this->createLink(
             $this->getSelfSubUrl($resource),
-            false,
         );
     }
 
@@ -146,12 +144,8 @@ public function getSelfSubLink(object $resource): LinkInterface
      */
     public function getRelationshipSelfLink(object $resource, string $field): LinkInterface
     {
-        $url = $this->getRelationshipSelfUrl($resource, $field);
-
-        return $this->factory->createLink(
-            true,
-            $url,
-            false,
+        return $this->createLink(
+            $this->getRelationshipSelfUrl($resource, $field),
         );
     }
 
@@ -160,12 +154,8 @@ public function getRelationshipSelfLink(object $resource, string $field): LinkIn
      */
     public function getRelationshipRelatedLink(object $resource, string $field): LinkInterface
     {
-        $url = $this->getRelationshipRelatedUrl($resource, $field);
-
-        return $this->factory->createLink(
-            true,
-            $url,
-            false,
+        return $this->createLink(
+            $this->getRelationshipRelatedUrl($resource, $field),
         );
     }
 
@@ -210,6 +200,21 @@ protected function getContext(): ContextInterface
             return $this->context;
         }
 
-        throw new RuntimeException('No currenct context set.');
+        throw new RuntimeException('No current context set.');
+    }
+
+    /**
+     * Create a link.
+     *
+     * This method was on the v1 schema provider, so is provided here for backwards compatibility.
+     *
+     * @param string $subHref
+     * @param null|mixed $meta
+     * @param bool $treatAsHref
+     * @return LinkInterface
+     */
+    protected function createLink(string $subHref, array $meta = null, bool $treatAsHref = false): LinkInterface
+    {
+        return $this->factory->createLink(!$treatAsHref, $subHref, !empty($meta), $meta);
     }
 }