Laravel Excludable Laravel Package

Technical Evaluation

Architecture fit: laravel-excludable is a thin Eloquent trait package — it extends the query builder with exclusion scopes (e.g., globally excluding records flagged as excluded). Its footprint is small and idiomatic Laravel; there's no service provider magic beyond registration, no new persistence layer, and no opinion imposed on schema beyond a boolean/timestamp column convention. Architecturally it fits any Laravel app using Eloquent, which is the default for our stack. The trade-off is that it operates by mutating global query scopes, which is a cross-cutting behavior change: once applied to a model, every query, relationship, and aggregate inherits the exclusion silently. That is powerful but is the primary architectural consideration — it shifts visibility logic from explicit call sites into the model layer.

Integration feasibility: High. It's a Composer package with a single trait; integration is use Excludable; on target models plus the relevant column migration. No queue workers, no external services, no configuration surface to speak of. 4.1.0 adding Laravel 11.x compatibility removes the main blocker we would have hit — our primary platform is on Laravel 11, and prior versions would have required a dependency override or a fork.

Technical risk: Low-to-moderate. The package is small and single-maintainer (maize-tech, a small Italian agency), which is the dominant risk vector. The API surface is narrow enough that we could vendor/fork it in an afternoon if maintenance lapses. The behavioral risk is higher than the supply-chain risk: global scopes are easy to forget, and "why is this row missing?" debugging across a team is a real cost. Version 4.1.0 is a compatibility release, not a breaking change, so upgrade risk is negligible.

Key questions for the maintainer / our team:

• Is the exclusion column convention fixed, or configurable per model? (Determines migration effort.)
• Does it compose correctly with SoftDeletes and other global scopes — ordering, withoutGlobalScope, and withTrashed-style escape hatches?
• Does it apply to exists(), count(), and eager-loaded relations, or only top-level queries?
• What is the release cadence and support policy? 4.1.0 lands ~Laravel 11 GA; are Laravel 12 plans committed?
• Test coverage and CI matrix — is Laravel 11 tested against PHP 8.2/8.3?

Integration Approach

Stack fit: Native. Eloquent trait, standard Composer install, no framework version gymnastics now that Laravel 11 is supported. It slots into our existing model layer without touching infrastructure, containers, or deployment.

Migration path: Minimal and reversible. Sequence: (1) add the exclusion column via a nullable, indexed migration with a safe default; (2) backfill if the semantics require it; (3) adopt the trait on one low-risk, read-heavy model first; (4) observe; (5) expand model-by-model. Because the trait is opt-in per model, rollout is incremental and can be halted mid-way without rollback of the package itself — only per-model trait removal plus column drop.

Compatibility: Requires Laravel 11.x (per 4.1.0) — confirm the floor for our remaining Laravel 10 services; those must stay on the 4.0.x line or be upgraded first. Verify PHP version support against our runtime images. Check interaction with SoftDeletes early; if both are used on the same model, define a clear precedence rule and document it, because two overlapping visibility scopes is exactly where teams get confused.

Sequencing: Pin ^4.1 only after (a) the Laravel 10 services are upgraded or explicitly excluded from scope, and (b) a spike confirms scope composition with soft deletes and relation loading. Schedule the first model adoption in a low-traffic window with query-log comparison before/after to catch unintended row disappearance. Do not adopt on financial or audit-relevant models until the escape-hatch pattern (withoutGlobalScope equivalents) is documented as team convention.

Operational Impact

Maintenance: Low ongoing effort — no runtime to operate, no config to drift. The real cost is dependency lifecycle: a single-maintainer package means we should track its health and be prepared to vendor. Set a calendar review at each Laravel major release; the Laravel 11 gap is direct evidence that compatibility lag can block our platform upgrades, so mirror that risk forward to Laravel 12.

Support: Community/OSS support only, effectively best-effort from a small agency. No SLA. For anything business-critical, assume we are the escalation path. Budget for an internal owner and a documented fork procedure.

Scaling: Neutral. Global scopes compile into the SQL WHERE clause; performance impact is an index question, not a package question — ensure the exclusion column is indexed and that composite indexes cover common query shapes. No memory or concurrency concerns.

Failure modes:

• Silent data invisibility: the highest-impact failure. A model gains the trait, a scope excludes more than intended, and rows vanish from reports or exports with no error. Mitigate with an integration test asserting expected row counts pre/post adoption and a team-wide convention for bypassing the scope in admin/reporting contexts.
• Scope interaction bugs: conflicts with SoftDeletes or custom global scopes producing duplicate or contradictory WHERE clauses.
• Abandonment: package stops receiving Laravel compatibility updates and blocks a future framework upgrade. Mitigation: vendoring plan, narrow API surface keeps fork cost trivial.
• Upgrade surprise: a future major bump changes default exclusion semantics. Mitigate by pinning to ^4.1 and reading changelogs before minor bumps given the maintainer's low release volume.

Ramp-up: Near-zero. Any Laravel developer understands traits and Eloquent scopes; onboarding is a code-review checklist item ("is this model excludable, and does the reader know it?"). The training investment is not in the package but in the convention — specifically, teaching the team that absence of a row may mean exclusion rather than deletion, and where the documented escape hatches live. Allocate a short design note and one brown-bag session rather than formal training.

Recommendation: Adopt at ^4.1 for suitable models on Laravel 11, staged per-model, with the visibility convention documented up front. Treat maintainer risk as accepted-and-mitigated via a vendorable fork rather than as a blocker.