feat: add filters support for relationships

Author: Ark4ne

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|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,96 @@
+<?php
+
+namespace Ark4ne\JsonApi\Filters;
+
+use Closure;
+use Illuminate\Contracts\Auth\Access\Gate;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\MissingValue;
+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 $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 mixed $data
+     * @return mixed
+     */
+    public function apply(Request $request, mixed $data): mixed
+    {
+        if ($data instanceof MissingValue || $data === null) {
+            return $data;
+        }
+
+        // If it's a collection/array, filter each item
+        if (is_iterable($data)) {
+            $filtered = [];
+            foreach ($data as $key => $item) {
+                if ($this->shouldInclude($request, $item)) {
+                    $filtered[$key] = $item;
+                }
+            }
+            
+            // Preserve the original collection type
+            if ($data instanceof Collection) {
+                return new Collection($filtered);
+            }
+            
+            return $filtered;
+        }
+
+        // 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 mixed $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 {