Weave Code
Laravel Excludable Laravel Package
h-farm/laravel-excludable
Laravel Excludable adds a lightweight trait to Eloquent models so specific records can be excluded from queries by default and included only when needed. Ideal for hiding archived or inactive rows without soft deletes or custom scopes, keeping filtered results clean and relationships predictable.
Easily exclude model entities from eloquent queries
Frequently asked questions about Laravel Excludable
- What is Laravel Excludable used for?
- Laravel Excludable is a lightweight Eloquent trait package for excluding specific model records from queries by default and including them only when needed. It is useful for hiding archived, inactive, or otherwise hidden rows without using soft deletes or writing custom local scopes for every query. The trait is opt-in per model, so you can adopt it incrementally.
- How do I install h-farm/laravel-excludable in a Laravel app?
- Install it with Composer using composer require h-farm/laravel-excludable, then add the Excludable trait to the Eloquent models you want to filter. You also need to add the package's exclusion column, typically a boolean or timestamp, through a migration. After that, excluded records should be hidden from normal queries unless you explicitly include them.
- Which Laravel versions does laravel-excludable support?
- Version 4.1.0 adds Laravel 11.x compatibility, which removes the main blocker for apps on Laravel 11. Earlier 4.0.x releases are the line to check for Laravel 10 services that have not been upgraded yet. Always confirm the exact PHP and Laravel constraints in the package's composer.json before pinning it in production.
- How does the Excludable trait change existing Eloquent queries?
- Once applied, the trait adds a global query scope that excludes records flagged as excluded, so normal model queries, relationships, and aggregates inherit the behavior silently. This shifts visibility logic from explicit call sites into the model layer, which is powerful but can make missing rows harder to debug. Adopt it model by model and compare query logs before and after.
- Can I customize the exclusion column name in laravel-excludable?
- The package uses a boolean or timestamp column convention, and the technical evaluation flags per-model configurability as a question to confirm with the maintainer. Check the trait source and README for an overridable column property or method before writing migrations. If it is not configurable, plan your schema around the default convention or fork the trait.
- Does laravel-excludable work with SoftDeletes and other global scopes?
- It can coexist with SoftDeletes because both rely on Eloquent's global scope mechanism, but two overlapping visibility scopes on the same model are easy to confuse. Define a clear precedence rule and document how withoutGlobalScope escape hatches work for your team. Run a spike early to confirm ordering and behavior with withTrashed-style queries.
- Does exclusion apply to count(), exists(), and eager-loaded relationships?
- Because Laravel Excludable is implemented as an Eloquent global scope, exclusion should apply to top-level queries as well as aggregates like count and exists and to eager-loaded relations. That said, scope composition and relation loading are exactly what the evaluation recommends testing before broad adoption. Write feature tests for each query shape you depend on.
- How do I include excluded records in a specific query?
- Use Eloquent's withoutGlobalScope with the package's exclusion scope class, or the include escape hatch the package provides if one exists. This keeps the default filtering intact while allowing admin screens, reports, or maintenance commands to see hidden rows. Document that escape-hatch pattern as a team convention before using the trait on audit-relevant models.
- Is laravel-excludable production-ready and actively maintained?
- The technical risk is low to moderate: the package is small, the API surface is narrow, and the code could be vendored or forked in an afternoon if maintenance lapses. The main risk is that it is single-maintainer software from a small agency, so pin a known-good version and watch release cadence. Version 4.1.0 is a compatibility release rather than a breaking change, so upgrade risk is low.
- What are the alternatives to Laravel Excludable for hiding archived rows?
- Alternatives include Laravel SoftDeletes, explicit local scopes, query-level where conditions, or a custom global scope tailored to your app. SoftDeletes changes deletion semantics and adds deleted_at handling, while local scopes keep visibility explicit at call sites. Laravel Excludable is a fit when you want a lightweight, model-level default exclusion without soft-delete behavior.
Weaver
How can I help you explore Laravel packages today?