Pivot Filters

Overview

Pivot filters can be specified in two ways:

on Custom Intermediate Table Models (Pivot, MorphPivot).
on your main models (Model).

With Custom Intermediate Table Models

Added in 2.1.0

This is the recommended way

Define the allowed pivot filters once in the Custom Intermediate Table Model.
Not required to call ->pivot().
Caveat: Must call ->includeRelationFields() on Filter::relation().

If you are utilising Custom Intermediate Table Models, you may define filters on that model. Filters defined on this model will be applied to the intermediate table.

/*
 * User Model
 */
class User extends Model implements IsFilterable
{
    use Filterable;

    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class)->using(RoleUser::class);
    }

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::relation('roles', [FilterType::HAS])->includeRelationFields(),
        );
    }
}

/*
 * Role Model
 */
class Role extends Model implements IsFilterable
{
    use Filterable;

    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class)->using(RoleUser::class);
    }

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::relation('users', [FilterType::HAS])->includeRelationFields(),
        );
    }
}

/*
 * RoleUser Pivot Model
 */
class RoleUser extends Pivot implements IsFilterable
{
    use Filterable;

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::field('assigned_by', [FilterType::EQUAL]),
        );
    }
}

/*
 * Applying `assigned_by` pivot filter
 * within `roles` `$has` relation filter.
 */
User::filter([
    [
        'type'   => '$has',
        'target' => 'roles',
        'value'  => [
            [
                'type'   => '$eq',
                'target' => 'assigned_by',
                'value'  => 'admin',
            ]
        ]
    ]
]);

/*
 * Applying `assigned_by` pivot filter
 * within `users` `$has` relation filter.
 */
Role::filter([
    [
        'type'   => '$has',
        'target' => 'users',
        'value'  => [
            [
                'type'   => '$eq',
                'target' => 'assigned_by',
                'value'  => 'admin',
            ]
        ]
    ]
]);

Restricting Allowed Pivot Filters.

Sometimes you may only want the pivot filter to be allowed when filtering by relationship one way but not the other way. For example:

Allowed when filtering User $has Role.
Denied when filtering Role $has User.

To achieve this you can specify the allowed “from” model for the pivot filter.

/*
 * RoleUser Pivot Model
 */
class RoleUser extends Pivot implements IsFilterable
{
    use Filterable;

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::field('assigned_by', [FilterType::EQUAL])
                ->pivot(User::class),
        );
    }
}

Without Custom Intermediate Table Models

If you are NOT utilising Custom Intermediate Table Models, you may define pivot filters on your main models. Filter::field() filters can be marked as pivot filters if you want the filter to be applied to a column on the intermediate table linking the models. You must specify the parent model fqcn.

public function allowedFilters(): AllowedFilterList
{
    return Filter::only(
        Filter::field('tagged_by', [FilterType::EQUAL])
            ->pivot(Post::class),
    );
}

BelongsToMany

In the below example of class Post and class Tag.

The pivot filter is specified in the allowedFilters method of both classes.
The pivot filter can only be used when in the context of the posts or tags relationship.

class Post extends Model implements IsFilterable
{
    use Filterable;

    public function tags(): BelongsToMany
    {
        return $this->belongsToMany(Tag::class);
    }

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::field('tagged_by', [FilterType::EQUAL])->pivot(Tag::class),
            Filter::relation('tags', [FilterType::HAS])->includeRelationFields()
        );
    }
}

class Tag extends Model implements IsFilterable
{
    use Filterable;

    public function posts(): BelongsToMany
    {
        return $this->belongsToMany(Post::class);
    }

    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::field('tagged_by', [FilterType::EQUAL])->pivot(Post::class),
            Filter::relation('posts', [FilterType::HAS])->includeRelationFields()
        );
    }
}

Allowed

With the models setup as described above. The following filters are allowed.

/*
 * Applying `tagged_by` pivot filter
 * within `tags` `$has` relation filter.
 */
Post::filter([
    [
        'type'   => '$has',
        'target' => 'tags',
        'value'  => [
            [
                'type'   => '$eq',
                'target' => 'tagged_by',
                'value'  => 'admin',
            ]
        ]
    ]
]);

/*
 * Applying `tagged_by` pivot filter
 * within `posts` `$has` relation filter.
 */
Tag::filter([
    [
        'type'   => '$has',
        'target' => 'posts',
        'value'  => [
            [
                'type'   => '$eq',
                'target' => 'tagged_by',
                'value'  => 'admin',
            ]
        ]
    ]
]);

DeniedFilterException

With the models setup as described above. The following filters are denied.

/*
 * Applying `tagged_by` pivot filter
 * when not in context of `tags` `$has` relation filter.
 * throws DeniedFilterException.
 */
Post::filter([
    [
        'type'   => '$eq',
        'target' => 'tagged_by',
        'value'  => 'admin',
    ]
]);

/*
 * Applying `tagged_by` pivot filter
 * when not in context of `posts` `$has` relation filter.
 * throws DeniedFilterException.
 */
Tag::filter([
    [
        'type'   => '$eq',
        'target' => 'tagged_by',
        'value'  => 'admin',
    ]
]);

/*
 * Applying `tagged_by` pivot filter
 * when in context of another BelongsToMany relation
 * but User::class not defined in the ->pivot() method in the tags model.
 * throws DeniedFilterException.
 */
User::filter([
    [
        'type'   => '$has',
        'target' => 'tags',
        'value'  => [
            [
                'type'   => '$eq',
                'target' => 'tagged_by',
                'value'  => 'admin',
            ]
        ]
    ]
]);

MorphToMany (Polymorphic)

When defining a pivot filter for MorphToMany relations, you can specify a list of models in the ->pivot() method.

class Epic extends Model implements IsFilterable
{
    // ...
    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::relation('labels', [FilterType::HAS])->includeRelationFields()
        );
    }
}

class Issue extends Model implements IsFilterable
{
    // ...
    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::relation('labels', [FilterType::HAS])->includeRelationFields()
        );
    }
}

class Label extends Model implements IsFilterable
{
    // ...
    public function allowedFilters(): AllowedFilterList
    {
        return Filter::only(
            Filter::field('labeled_by', [FilterType::EQUAL])
                ->pivot(Epic::class, Issue::class)
        );
    }
}

Introduction

Basics

Available Filters

Digging Deeper

Sorting

Overview

With Custom Intermediate Table Models

Restricting Allowed Pivot Filters.

Without Custom Intermediate Table Models

BelongsToMany

Allowed

DeniedFilterException

MorphToMany (Polymorphic)

​Overview

​With Custom Intermediate Table Models

​Restricting Allowed Pivot Filters.

​Without Custom Intermediate Table Models

​BelongsToMany

​Allowed

​DeniedFilterException

​MorphToMany (Polymorphic)

Overview

With Custom Intermediate Table Models

Restricting Allowed Pivot Filters.

Without Custom Intermediate Table Models

BelongsToMany

Allowed

DeniedFilterException

MorphToMany (Polymorphic)