Social Card of Laravel Excludable

Laravel Excludable

Easily exclude model entities from eloquent queries.

This package allows you to define a subset of model entities that should be excluded from eloquent queries. You will be able to override the default Exclusion model and its associated migration, so you can eventually restrict the exclusion context by defining the entity that should effectively exclude the subset.

An example usage could be an application with a multi tenant scenario and a set of global entities. While those entities should be accessible by all tenants, some of them might want to hide a subset of those entities for their users. You can find an example in the Usage section.

Installation

You can install the package via composer:

composer require maize-tech/laravel-excludable

You can publish and run the migrations with:

php artisan vendor:publish --provider="Maize\Excludable\ExcludableServiceProvider" --tag="excludable-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --provider="Maize\Excludable\ExcludableServiceProvider" --tag="excludable-config"

This is the content of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | Exclusion model
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the exclusion model.
    |
    */

    'exclusion_model' => Maize\Excludable\Models\Exclusion::class,
    
    /*
    |--------------------------------------------------------------------------
    | Has exclusion query
    |--------------------------------------------------------------------------
    |
    | Here you may specify the fully qualified class name of the exclusion query.
    |
    */

    'has_exclusion_query' => Maize\Excludable\Queries\HasExclusionQuery::class,
];

Usage

Basic

To use the package, add the Maize\Excludable\Excludable trait to all models you want to make excludable.

Here's an example model including the Excludable trait:

<?php

namespace App\Models;

use Maize\Excludable\Excludable;

class Article extends Model
{
    use Excludable;

    protected $fillable = [
        'title',
        'body',
    ];
}

Now you can just query for a specific article entity and mark it as excluded.

use App\Models\Article;

$article = Article::query()->findOrFail(1)

$article->addToExclusion();

$article->excluded(); // returns true

That's all!

The package will add the given entity to the exclusions table, so all article related queries will exclude it.

use App\Models\Article;

Article::findOrFail(1); // throws Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Exclude all model entities

To exclude all entities of a specific model you can use the excludeAllModels method:

use App\Models\Article;

Article::excludeAllModels();

Article::query()->count(); // returns 0

The given method will create an Exclusion entity with a wildcard, which means all newly created entities will be excluded too.

You can also provide a subset of entities which should not be excluded:

use App\Models\Article;

$article = Article::query()->find(1);

Article::excludeAllModels($article); // passing a model entity

Article::query()->count(); // returns 1

use App\Models\Article;

Article::excludeAllModels([1,2,3]); // passing the model keys

Article::query()->count(); // returns 3

To check whether a specific model has a wildcard or not you can use the hasExclusionWildcard method:

use App\Models\Article;

Article::excludeAllModels();

$hasWildcard = Article::hasExclusionWildcard(); // returns true

Include all model entities

To re-include all entities of a specific model you can use the includeAllModels method:

use App\Models\Article;

Article::includeAllModels();

Article::query()->count(); // returns 0

The given method will delete all Exclusion entities related to the Article model.

Include excluded entities

use App\Models\Article;

Article::withExcluded()->get(); // queries all models, including those marked as excluded

Only show excluded entities

use App\Models\Article;

Article::onlyExcluded()->get(); // queries only excluded entities

Event handling

The package automatically throws two separate events when excluding an entity:

excluding which is thrown before the entity is actually excluded. This could be useful, for example, with an observer which listens to this event and does some sort of 'validation' to the related entity. If the given validation does not succeed, you can just return false, and the entity will not be excluded;
excluded which is thrown right after the entity has been marked as excluded.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.