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;