Add support for JSON:API relationship URLs

This release adds comprehensive support for JSON:API relationship URLs,
including fetching relationships, related resources, and relationship
mutations.

New features:
- GET /resources/{id}/relationships/{name} - Fetch relationship linkage
- GET /resources/{id}/{name} - Fetch related resources with full
  filtering, sorting, and pagination support for to-many relationships
- PATCH /resources/{id}/relationships/{name} - Replace relationships
- POST /resources/{id}/relationships/{name} - Add to to-many relationships
- DELETE /resources/{id}/relationships/{name} - Remove from to-many relationships
- Attachable contract for custom relationship mutation handling
- Automatic self and related links on relationship fields
- RelatedListable interface for queryable to-many relationships

BREAKING CHANGES:

1. Listable interface now requires defaultSort() and pagination() methods
   - Previously configured on Index endpoint, now on the resource
   - Allows pagination/sorting to be reused for related resources
   - Migration: Implement these methods, return null for no defaults

2. Paginatable::paginate() now returns Page instead of mutating query
   - Change signature to return new Page($results, $isLastPage)
   - Update custom Pagination implementations accordingly

3. Context now uses documentMeta and documentLinks (ArrayObject)
   - Replace usage of old meta/links properties
   - Allows callbacks to add document-level metadata

4. Serializer API changed - no longer accepts Context in constructor
   - Pass context to addPrimary() and addIncluded() instead
   - Affects custom code directly using Serializer

Documentation has been reorganized with dedicated pages for filtering,
sorting, and pagination. OpenAPI schema generation updated to include
relationship endpoint schemas.

Author: tobyzerner

CHANGELOG.md

@@ -10,24 +10,37 @@ and this project adheres to
 
 ### ⚠️ Breaking Changes
 
-- Change `Resource\Paginatable::paginate()` to accept the resolved offset and
-  limit integers (plus the request context) and return the page of results
-  instead of mutating the query in place
+- Change `Resource\Paginatable::paginate()` signature to accept the resolved
+  offset and limit integers (plus the request context) and return the page of
+  results instead of mutating the query in place
 - New contract for custom `Pagination` implementations:
-    - Return results from the `paginate(object $query, Context $context): Page`
-    - Add `meta` and `links` via the `Context` object
+    - Add `paginate(object $query, Context $context): Page` method which should
+      return a page of results
+    - Remove `meta` and `links` methods; set this data in `paginate` via the
+      `Context` object
+- `Resource\\Listable` implementations must now provide `defaultSort()` and
+  `pagination()` methods so defaults can be reused when listing related data
+- Refactor `Serializer` so it is instantiated without a `Context` and expects
+  the resource context to be provided to `addPrimary()` / `addIncluded()`
 
 ### Added
 
 - Add cursor pagination support via `Endpoint\Index::cursorPaginate()` and the
   `Resource\CursorPaginatable` contract, following the
-  `ethanresnick/cursor-pagination` profile
-- Introduce `MaxPageSizeExceededException` and
-  `RangePaginationNotSupportedException` with JSON:API profile links for cursor
-  pagination errors
+  `ethanresnick/cursor-pagination` JSON:API profile
 - Allow exceptions to attach `meta` and `links` members to the error response
-- Add `Context::$meta` and `Context::$links` as `ArrayObject` instances to allow
-  callbacks to add meta information to the response document
+- Add `Context::$documentMeta` and `Context::$documentLinks` as `ArrayObject`
+  instances to allow callbacks to add meta information to the response document
+- Support JSON:API relationship URLs via the `Show` endpoint, adding automatic
+  `self` / `related` links, and paginated/filterable/sortable to-many responses
+  when the related resource is `Listable`
+- Allow the `Update` endpoint to handle `PATCH` / `POST` / `DELETE` requests to
+  relationship URLs and return the updated relationship document
+- Implement the `Resource\Attachable` contract and add `ToMany::attachable()`,
+  `validateAttach()`, and `validateDetach()` helpers for controlling
+  relationship mutation endpoints with attach/detach hooks
+- Introduce `Endpoint\ResourceEndpoint` and `Endpoint\RelationshipEndpoint` so
+  endpoints can contribute relationship and resource links during serialization
 
 ## [1.0.0-beta.5] - 2025-09-27
 

docs/.vitepress/config.ts

@@ -21,9 +21,12 @@ export default defineConfig({
                 text: 'Resources',
                 items: [
                     { text: 'Defining Resources', link: '/resources' },
-                    { text: 'Defining Fields', link: '/fields' },
+                    { text: 'Fields', link: '/fields' },
                     { text: 'Attributes', link: '/attributes' },
                     { text: 'Relationships', link: '/relationships' },
+                    { text: 'Filtering', link: '/filtering' },
+                    { text: 'Sorting', link: '/sorting' },
+                    { text: 'Pagination', link: '/pagination' },
                 ],
             },
             {

docs/collections.md

@@ -10,8 +10,8 @@ also used for defining
 
 ## Defining Collections
 
-To define a heterogeneous collection, create a new class that implements the
-`Tobyz\JsonApi\Resource\Collection` interface:
+To define a heterogeneous collection, create a new class that extends
+`Tobyz\JsonApi\Resource\AbstractCollection`, and implement the required methods:
 
 ```php
 use Tobyz\JsonApiServer\Resource\Collection;

docs/context.md

@@ -41,6 +41,12 @@ class Context
     // that are included
     public ?array $include = null;
 
+    // Data to be returned in the document's meta object
+    public ArrayObject $documentMeta;
+
+    // Links to be returned in the document's links object
+    public ArrayObject $documentLinks;
+
     // Get the request method
     public function method(): string;
 

docs/fields.md

@@ -1,4 +1,4 @@
-# Defining Fields
+# Fields
 
 A resource object's attributes and relationships are collectively called its
 "fields".

docs/filtering.md

@@ -0,0 +1,116 @@
+# Filtering
+
+The JSON:API specification reserves the `filter` query parameter for
+[filtering resources](https://jsonapi.org/format/#fetching-filtering).
+
+To define filters that can be used in this query parameter, add them to your
+`Listable` resource's `filters` method:
+
+```php
+class PostsResource extends Resource implements Listable
+{
+    // ...
+
+    public function filters(): array
+    {
+        return [
+            ExampleFilter::make('example'), // [!code ++]
+        ];
+    }
+}
+```
+
+::: tip Laravel Integration  
+For Eloquent-backed resources, a number of [filters](laravel.md#filters) are
+provided to make it easy to implement filtering on your resource.  
+:::
+
+## Inline Filters
+
+The easiest way to define a filter is to use the `CustomFilter` class, which
+accepts the name of the filter parameter and a callback to apply the filter to
+the query. The value received by a filter can be a string or an array, so you
+will need to handle both:
+
+```php
+use Tobyz\JsonApiServer\Schema\CustomFilter;
+
+CustomFilter::make('name', function (
+    $query,
+    string|array $value,
+    Context $context,
+) {
+    $query->whereIn('name', (array) $value);
+});
+```
+
+Now the filter can be applied like so:
+
+```http
+GET /posts?filter[name]=Toby
+GET /posts?filter[name][]=Toby&filter[name][]=Franz
+```
+
+## Boolean Filters
+
+By default it is assumed that each filter applied to the query will be combined
+with a logical `AND`. When a resource implements
+`Tobyz\JsonApiServer\Resource\SupportsBooleanFilters` you can express more
+complex logic with `AND`, `OR`, and `NOT` groups.
+
+Boolean groups are expressed by nesting objects under the `filter` parameter.
+You may use either associative objects or indexed lists of clauses. Each clause
+can be another filter or another boolean group.
+
+```http
+GET /posts
+  ?filter[and][0][status]=published
+  &filter[and][1][or][0][views][gt]=100
+  &filter[and][1][or][1][not][status]=archived
+```
+
+In this request every result must be published, and it must also either have
+more than 100 views or it is not archived.
+
+```http
+GET /posts
+  ?filter[or][0][status]=draft
+  &filter[or][1][status]=published
+  &filter[or][1][not][comments]=0
+```
+
+This request returns drafts, or posts that are published and have comments. The
+second example also shows that in certain cases you can omit `[and]` groups and
+numeric indices; sibling filters at the same level default to `AND` behaviour.
+
+## Writing Filters
+
+To create your own filter class, extend the `Tobyz\JsonApiServer\Schema\Filter`
+class and implement the `apply` method:
+
+```php
+use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Schema\Filter;
+
+class WhereIn extends Filter
+{
+    public function apply(
+        object $query,
+        string|array $value,
+        Context $context,
+    ): void {
+        $query->whereIn($this->name, $value);
+    }
+}
+```
+
+## Visibility
+
+If you want to restrict the ability to use a filter, use the `visible` or
+`hidden` method, passing a closure that returns a boolean value:
+
+```php
+WhereIn::make('example')->visible(
+    fn(Context $context) => $context->request->getAttribute('isAdmin'),
+);
+```

docs/index.md

@@ -17,6 +17,8 @@ support for:
 - **Creating** resources (`POST /articles`)
 - **Updating** resources (`PATCH /articles/1`)
 - **Deleting** resources (`DELETE /articles/1`)
+- **Related resource** URLs (`GET /articles/1/author`)
+- **Relationship** URLs (`/articles/1/relationships/author`)
 - **Content negotiation**
 - **Error handling**
 - **Extensions** including Atomic Operations
@@ -63,7 +65,7 @@ class UsersResource extends EloquentResource
     {
         return [
             Endpoint\Show::make(),
-            Endpoint\Index::make()->paginate(),
+            Endpoint\Index::make(),
             Endpoint\Create::make()->visible(Laravel\can('create')),
             Endpoint\Update::make()->visible(Laravel\can('update')),
             Endpoint\Delete::make()->visible(Laravel\can('delete')),