maize-tech / laravel-excludable
Laravel Excludable
Fund package maintenance!
maize-tech
Installs: 584
Dependents: 0
Suggesters: 0
Security: 0
Stars: 59
Watchers: 10
Forks: 8
Open Issues: 0
Requires
- php: ^8.0
- illuminate/database: ^9.0|^10.0|^11.0
- illuminate/support: ^9.0|^10.0|^11.0
- spatie/laravel-package-tools: ^1.14.1
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.5|^10.5
- vimeo/psalm: ^4.20|^5.22
README
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 returnfalse
, 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.