v1.5 relationships filters (#31)

* feat: add filters support for relationships

* feat: add CLAUDE.md for project guidance and testing instructions

* fix: update parameter type hint for abilities in Relation.php

* break: drop support of laravel 9.0

* Revert "break: drop support of laravel 9.0"

This reverts commit 84ffb42.

* chore: fixup for backward compatibility

* fix: improve type hints and simplify data filtering in Filters.php

Author: Ark4ne

CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Testing
+- `vendor/bin/phpunit` - Run all tests
+- `vendor/bin/phpunit --coverage-clover coverage.xml` - Run tests with coverage
+- `vendor/bin/phpunit --configuration phpunit.php8.1.xml.dist` - Run tests for specific PHP version
+- `vendor/bin/phpunit tests/Unit` - Run only unit tests
+- `vendor/bin/phpunit tests/Feature` - Run only feature tests
+
+### Static Analysis
+- `vendor/bin/phpstan analyze` - Run PHPStan static analysis (level 6)
+
+### Dependencies
+- `composer install` - Install dependencies
+- `composer require laravel/framework ^9.0` - Install specific Laravel version for testing
+
+## Architecture
+
+This is a Laravel package that provides JSON:API compliant resource serialization. The core architecture follows these patterns:
+
+### Resource System
+- **JsonApiResource**: Main abstract class extending Laravel's JsonResource, implements JSON:API specification
+- **JsonApiCollection**: Handles collections of resources with proper JSON:API formatting
+- **Resourceable**: Interface defining resource contracts
+
+### Key Components
+
+#### Descriptors
+- **Values** (`src/Descriptors/Values`): Type descriptors for attributes (string, integer, float, date, enum, etc.)
+- **Relations** (`src/Descriptors/Relations`): Relationship descriptors (one, many)
+
+#### Resource Concerns
+- **Attributes**: Handles attribute serialization with field filtering
+- **Relationships**: Manages relationship loading and serialization with include support
+- **ConditionallyLoadsAttributes**: Laravel-style conditional attribute support
+- **Identifier**: Resource ID and type handling
+- **Links**: JSON:API links support
+- **Meta**: Meta information handling
+- **Schema**: Resource schema generation for validation
+- **ToResponse**: Response formatting
+
+#### Request Validation
+- **Rules/Includes**: Validates `include` parameter against resource schema
+- **Rules/Fields**: Validates `fields` parameter for sparse fieldsets
+
+### Key Features
+- **Include Support**: Dynamic relationship loading via `?include=` parameter
+- **Sparse Fieldsets**: Attribute filtering via `?fields[type]=` parameter  
+- **Described Notation**: Fluent API for defining attributes and relationships with type casting
+- **Laravel Compatibility**: Supports Laravel 9-12 and PHP 8.1-8.4
+
+### Configuration
+The package includes a config file (`config/jsonapi.php`) with settings for:
+- Nullable value handling
+- Date formatting
+- Float precision
+- Automatic whenHas conditions
+- Relationship loading behavior
+
+### Testing Structure
+- **Unit Tests**: Test individual components in isolation
+- **Feature Tests**: Test complete JSON:API response formatting
+- Uses Orchestra Testbench for Laravel package testing
+- SQLite in-memory database for testing

src/Descriptors/Relations/Relation.php

@@ -3,10 +3,12 @@
 namespace Ark4ne\JsonApi\Descriptors\Relations;
 
 use Ark4ne\JsonApi\Descriptors\Describer;
+use Ark4ne\JsonApi\Filters\Filters;
 use Ark4ne\JsonApi\Resources\Relationship;
 use Ark4ne\JsonApi\Support\Includes;
 use Ark4ne\JsonApi\Traits\HasRelationLoad;
 use Closure;
+use Illuminate\Contracts\Auth\Access\Gate;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Request;
 use Illuminate\Http\Resources\MissingValue;
@@ -23,6 +25,7 @@ abstract class Relation extends Describer
     protected ?Closure $links = null;
     protected ?Closure $meta = null;
     protected ?bool $whenIncluded = null;
+    protected ?Filters $filters = null;
 
     /**
      * @param class-string<\Ark4ne\JsonApi\Resources\JsonApiResource|\Ark4ne\JsonApi\Resources\JsonApiCollection> $related
@@ -63,6 +66,37 @@ public function meta(Closure $meta): static
         return $this;
     }
 
+    /**
+     * Set filters for the relationship
+     *
+     * @param Closure(Filters): Filters $filters Callback that receives (Filters $filters) and configures the filters
+     * @return static
+     */
+    public function filters(Closure $filters): static
+    {
+        $this->filters = $filters(new Filters);
+        return $this;
+    }
+
+    /**
+     * @param iterable<mixed>|string $abilities Abilities to check
+     * @param array<mixed> $arguments Arguments to pass to the policy method, the model is always the first argument
+     * @param string $gateClass Gate class to use, defaults to the default Gate implementation
+     * @param string|null $guard Guard to use, defaults to the default guard
+     * @return static
+     */
+    public function can(iterable|string $abilities, array $arguments = [], string $gateClass = Gate::class, ?string $guard = null): static
+    {
+        return $this->when(fn(
+            Request $request,
+            Model   $model,
+            string  $attribute
+        ) => app($gateClass)
+            ->forUser($request->user($guard))
+            ->allows($abilities, [$model, ...$arguments])
+        );
+    }
+
     /**
      * @param bool|null $whenIncluded
      * @return static
@@ -139,6 +173,10 @@ public function resolveFor(Request $request, mixed $model, string $attribute): R
             $relation->whenIncluded($this->whenIncluded);
         }
 
+        if ($this->filters !== null) {
+            $relation->withFilters($this->filters);
+        }
+
         return $relation;
     }
 

src/Filters/CallbackFilterRule.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Ark4ne\JsonApi\Filters;
+
+use Closure;
+use Illuminate\Http\Request;
+
+/**
+ * @template Resource
+ *
+ * @implements FilterRule<Resource>
+ */
+class CallbackFilterRule implements FilterRule
+{
+    /**
+     * @param Closure(Request, Resource): bool $callback
+     */
+    public function __construct(
+        protected Closure $callback
+    ) {
+    }
+
+    /**
+     * @param Request $request
+     * @param Resource $model
+     * @return bool
+     */
+    public function passes(Request $request, mixed $model): bool
+    {
+        return (bool) ($this->callback)($request, $model);
+    }
+}

src/Filters/FilterRule.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Ark4ne\JsonApi\Filters;
+
+use Illuminate\Http\Request;
+
+/**
+ * @template Resource
+ */
+interface FilterRule
+{
+    /**
+     * Determine if the filter rule passes for the given model
+     *
+     * @param Request $request
+     * @param Resource $model The model being filtered
+     * @return bool
+     */
+    public function passes(Request $request, mixed $model): bool;
+}

src/Filters/Filters.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace Ark4ne\JsonApi\Filters;
+
+use Ark4ne\JsonApi\Support\Values;
+use Closure;
+use Illuminate\Contracts\Auth\Access\Gate;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\MissingValue;
+use Illuminate\Http\Resources\PotentiallyMissing;
+use Illuminate\Support\Collection;
+
+/**
+ * @template Resource
+ */
+class Filters
+{
+    /** @var array<FilterRule<Resource>> */
+    protected array $rules = [];
+
+    /**
+     * Add a policy-based filter
+     *
+     * @param iterable<string>|string $abilities Abilities to check
+     * @param array<mixed> $arguments Arguments to pass to the policy method, the model is always the first argument
+     * @param string $gateClass Gate class to use, defaults to the default Gate implementation
+     * @param string|null $guard Guard to use, defaults to the default guard
+     * @return static
+     */
+    public function can(iterable|string $abilities, array $arguments = [], string $gateClass = Gate::class, ?string $guard = null): static
+    {
+        $this->rules[] = new PolicyFilterRule($abilities, $arguments, $gateClass, $guard);
+        return $this;
+    }
+
+    /**
+     * Add a custom filter rule
+     *
+     * @param Closure(Request, Resource): bool $callback Callback that receives (Request $request, Model $model) and returns bool
+     * @return static
+     */
+    public function when(Closure $callback): static
+    {
+        $this->rules[] = new CallbackFilterRule($callback);
+        return $this;
+    }
+
+    /**
+     * Apply all filters to the given data
+     *
+     * @param Request $request
+     * @param null|PotentiallyMissing|Resource|iterable<array-key, Resource> $data
+     * @return mixed
+     */
+    public function apply(Request $request, mixed $data): mixed
+    {
+        if ($data === null) {
+            return $data;
+        }
+        if (Values::isMissing($data)) {
+            return $data;
+        }
+
+        // If it's a collection/array, filter each item
+        if (is_iterable($data)) {
+            $filtered = (new Collection($data))
+                ->filter(fn($item) => $this->shouldInclude($request, $item));
+
+            // Preserve the original collection type
+            if ($data instanceof Collection) {
+                return $filtered;
+            }
+            
+            return $filtered->all();
+        }
+
+        // Single model - check if it should be included
+        return $this->shouldInclude($request, $data)
+            ? $data
+            : new MissingValue();
+    }
+
+    /**
+     * Check if a model should be included based on all filter rules
+     *
+     * @param Request $request
+     * @param Resource $model
+     * @return bool
+     */
+    protected function shouldInclude(Request $request, mixed $model): bool
+    {
+        // All rules must pass
+        foreach ($this->rules as $rule) {
+            if (!$rule->passes($request, $model)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

src/Filters/PolicyFilterRule.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Ark4ne\JsonApi\Filters;
+
+use Illuminate\Contracts\Auth\Access\Gate;
+use Illuminate\Http\Request;
+
+/**
+ * @template Resource
+ *
+ * @implements FilterRule<Resource>
+ */
+class PolicyFilterRule implements FilterRule
+{
+    /**
+     * @param iterable<string>|string $abilities
+     * @param array<mixed> $arguments
+     */
+    public function __construct(
+        protected iterable|string $abilities,
+        protected array $arguments = [],
+        protected string $gateClass = Gate::class,
+        protected ?string $guard = null
+    ) {
+    }
+
+    /**
+     * @param Request $request
+     * @param Resource $model
+     * @return bool
+     */
+    public function passes(Request $request, mixed $model): bool
+    {
+        return app($this->gateClass)
+            ->forUser($request->user($this->guard))
+            ->allows($this->abilities, [$model, ...$this->arguments]);
+    }
+}

src/Resources/Relationship.php

@@ -2,6 +2,7 @@
 
 namespace Ark4ne\JsonApi\Resources;
 
+use Ark4ne\JsonApi\Filters\Filters;
 use Ark4ne\JsonApi\Support\Values;
 use Ark4ne\JsonApi\Traits\HasRelationLoad;
 use Closure;
@@ -25,6 +26,8 @@ class Relationship implements Resourceable
 
     protected ?bool $whenIncluded = null;
 
+    protected ?Filters $filters = null;
+
     /**
      * @param class-string<T> $resource
      * @param Closure $value
@@ -111,6 +114,19 @@ public function whenIncluded(null|bool $whenIncluded = null): static
         return $this;
     }
 
+    /**
+     * Set filters for the relationship
+     *
+     * @param Filters $filters
+     * @return $this
+     */
+    public function withFilters(Filters $filters): static
+    {
+        $this->filters = $filters;
+
+        return $this;
+    }
+
     /**
      * Return class-string of resource
      *
@@ -148,6 +164,11 @@ public function toArray(mixed $request, bool $included = true): array
             : value($this->value);
         $value ??= new MissingValue;
 
+        // Apply filters if they are defined and we have data
+        if ($this->filters !== null && !Values::isMissing($value)) {
+            $value = $this->filters->apply($request, $value);
+        }
+
         if ($this->asCollection && !is_subclass_of($this->resource, ResourceCollection::class)) {
             $resource = $this->resource::collection($value);
         } else {