Add self link to Index endpoint document

Author: tobyzerner

CHANGELOG.md

@@ -24,6 +24,9 @@ and this project adheres to
     - Add `JsonApi::setTranslator()` method for providing custom translator
       implementations
     - Add `Context::translate()` method for accessing the translation system
+- Add `Context::currentUrl()` method for building the current URL with query
+  parameter overrides
+- Add `self` link to `Index` endpoint document
 - Add `Id` field class for customizing resource ID behavior, including type
   constraints, client-generated IDs via `writableOnCreate()`, and validation
 - Add `linkageMeta()` method to relationship fields for adding meta to resource
@@ -39,6 +42,11 @@ and this project adheres to
 - Improve OpenAPI schema generation to properly handle ID field constraints and
   avoid redundant properties
 
+### Removed
+
+- Remove `Pagination\Concerns\BuildsUrls` trait (replaced by
+  `Context::currentUrl()`)
+
 ## [1.0.0-beta.6] - 2025-10-02
 
 ### ⚠️ Breaking Changes

docs/context.md

@@ -59,6 +59,9 @@ class Context
     // Translate a message using the API's translator
     public function translate(string $key, array $replacements = []): string;
 
+    // Get the URL of the current request, optionally with query parameter overrides
+    public function currentUrl(array $queryParams = []): string;
+
     // Get the parsed JSON:API payload
     public function body(): ?array;
 

src/Context.php

@@ -81,6 +81,29 @@ public function path(): string
         );
     }
 
+    /**
+     * Get the URL of the current request, optionally with query parameter overrides.
+     */
+    public function currentUrl(array $queryParams = []): string
+    {
+        $queryParams = array_replace_recursive($this->request->getQueryParams(), $queryParams);
+
+        if (isset($queryParams['filter'])) {
+            foreach ($queryParams['filter'] as &$v) {
+                $v = $v === null ? '' : $v;
+            }
+        }
+
+        ksort($queryParams);
+
+        $queryString = http_build_query($queryParams, '', '&', PHP_QUERY_RFC3986);
+
+        return $this->api->basePath .
+            '/' .
+            $this->path() .
+            ($queryString ? '?' . $queryString : '');
+    }
+
     /**
      * Get the parsed JSON:API payload.
      */

src/Endpoint/Index.php

@@ -91,7 +91,11 @@ public function handle(Context $context): ?Response
             $this->pagination,
         );
 
-        return json_api_response($this->buildResourceDocument($models, $context));
+        $document = $this->buildResourceDocument($models, $context);
+
+        $document['links']['self'] ??= $context->currentUrl();
+
+        return json_api_response($document);
     }
 
     public function getOpenApiPaths(Collection $collection, JsonApi $api): array

src/Pagination/Concerns/BuildsUrls.php

@@ -6,13 +6,11 @@
 use Tobyz\JsonApiServer\Context;
 use Tobyz\JsonApiServer\Exception\BadRequestException;
 use Tobyz\JsonApiServer\Exception\Sourceable;
-use Tobyz\JsonApiServer\Pagination\Concerns\BuildsUrls;
 use Tobyz\JsonApiServer\Pagination\Concerns\HasSizeParameter;
 use Tobyz\JsonApiServer\Resource\CursorPaginatable;
 
 class CursorPagination implements Pagination
 {
-    use BuildsUrls;
     use HasSizeParameter;
 
     public readonly int $size;
@@ -51,27 +49,21 @@ public function paginate(object $query, Context $context): array
         }
 
         if ($page->results && !$page->isFirstPage) {
-            $context->documentLinks['prev'] = $this->buildUrl(
-                [
-                    'page' => [
-                        'after' => null,
-                        'before' => $collection->itemCursor($page->results[0], $query, $context),
-                    ],
+            $context->documentLinks['prev'] = $context->currentUrl([
+                'page' => [
+                    'after' => null,
+                    'before' => $collection->itemCursor($page->results[0], $query, $context),
                 ],
-                $context,
-            );
+            ]);
         }
 
         if ($page->results && !$page->isLastPage) {
-            $context->documentLinks['next'] = $this->buildUrl(
-                [
-                    'page' => [
-                        'before' => null,
-                        'after' => $collection->itemCursor(end($page->results), $query, $context),
-                    ],
+            $context->documentLinks['next'] = $context->currentUrl([
+                'page' => [
+                    'before' => null,
+                    'after' => $collection->itemCursor(end($page->results), $query, $context),
                 ],
-                $context,
-            );
+            ]);
         }
 
         return $page->results;

src/Pagination/CursorPagination.php

@@ -5,14 +5,12 @@
 use RuntimeException;
 use Tobyz\JsonApiServer\Context;
 use Tobyz\JsonApiServer\Exception\BadRequestException;
-use Tobyz\JsonApiServer\Pagination\Concerns\BuildsUrls;
 use Tobyz\JsonApiServer\Pagination\Concerns\HasSizeParameter;
 use Tobyz\JsonApiServer\Resource\Paginatable;
 
 class OffsetPagination implements Pagination
 {
     use HasSizeParameter;
-    use BuildsUrls;
 
     public function __construct(int $defaultLimit = 20, ?int $maxLimit = 50)
     {
@@ -35,10 +33,7 @@ public function paginate(object $query, Context $context): array
         $page = $collection->paginate($query, $offset, $limit, $context);
 
         if ($page->isFirstPage !== true && $offset > 0) {
-            $context->documentLinks['first'] = $this->buildUrl(
-                ['page' => ['offset' => null]],
-                $context,
-            );
+            $context->documentLinks['first'] = $context->currentUrl(['page' => ['offset' => null]]);
 
             $prevOffset = $offset - $limit;
 
@@ -48,23 +43,21 @@ public function paginate(object $query, Context $context): array
                 $params = ['page' => ['offset' => max(0, $prevOffset) ?: null]];
             }
 
-            $context->documentLinks['prev'] = $this->buildUrl($params, $context);
+            $context->documentLinks['prev'] = $context->currentUrl($params);
         }
 
         $total = $context->documentMeta['page']['total'] ?? null;
 
         if ($total !== null && $limit && $offset + $limit < $total) {
-            $context->documentLinks['last'] = $this->buildUrl(
-                ['page' => ['offset' => floor(($total - 1) / $limit) * $limit ?: null]],
-                $context,
-            );
+            $context->documentLinks['last'] = $context->currentUrl([
+                'page' => ['offset' => floor(($total - 1) / $limit) * $limit ?: null],
+            ]);
         }
 
         if (!$page->isLastPage) {
-            $context->documentLinks['next'] = $this->buildUrl(
-                ['page' => ['offset' => $offset + $limit]],
-                $context,
-            );
+            $context->documentLinks['next'] = $context->currentUrl([
+                'page' => ['offset' => $offset + $limit],
+            ]);
         }
 
         return $page->results;