Laravel Excludable Laravel Package

Product Decisions This Supports

• Framework upgrade planning: v4.1.0 adds Laravel 11.x compatibility, so this package no longer blocks an upgrade of a Laravel 10 → 11 roadmap item. Confirm your other dependencies are also L11-ready before scheduling the upgrade.
• Build vs. buy for "hide this record" behavior: Packages like this one cover a recurring product need — hiding records from the default query surface (archived listings, flagged/spam content, moderated submissions, deactivated accounts) without deleting the underlying data. Buying is typically cheaper than building a bespoke global-scope + state-column mechanism.
• Feature feasibility: Enables low-effort implementation of "exclude/restore" admin actions, reversible moderation flows, and "visible to admins but not end users" behavior in existing Eloquent models.
• Data-retention and audit posture: Supports non-destructive hiding, which aligns with retention/reporting requirements more cleanly than hard deletes — useful when legal, finance, or analytics stakeholders need rows to persist.
• Risk/roadmap input: A fresh release signals active maintenance, which is a positive input for "keep vs. replace" decisions during dependency audits.

When to Consider This Package

Consider it when:

• You repeatedly need a reversible, query-level exclusion on Eloquent models and want a consistent, package-supported pattern rather than ad-hoc where clauses scattered across the codebase.
• You are on (or moving to) Laravel 11 and need the dependency to be compatible — this release is the enabling signal; pin to ^4.1 and re-run your test suite after upgrading.
• The exclusion is a cross-cutting concern (many models, many queries) where a global scope genuinely reduces defects from forgotten filters.
• You want the "invisible by default, visible on request" semantics — safer than opt-in filtering, where a missed where leaks hidden records.

Look elsewhere when:

• The behavior is a one-off on a single model: a plain boolean/timestamp column plus a local scope is simpler and avoids a dependency.
• You actually need soft deletes semantics (Laravel's built-in SoftDeletes already gives restore, force-delete, and with-trashed behavior) — running both abstractions risks confusing, overlapping visibility rules.
• You need audit trails, scheduling, or approval workflows around exclusion — this package is a query-visibility primitive, not a moderation system; pair it with your own domain model.
• Governance risk is unacceptable: it is a small, single-vendor/small-maintainer package. If your org requires long-term support guarantees or vendor SLAs, wrap it behind an internal interface or implement the trait in-house (it is a thin pattern).
• Hidden-by-default scoping would surprise teams on reporting/analytics queries — verify reporting paths explicitly request excluded rows.

Adoption checklist: verify L11 constraint in composer.json, confirm migration/state-column strategy, add a regression test asserting default queries exclude rows and explicit include paths return them, and document the behavior for analytics/reporting owners.

How to Pitch It (Stakeholders)

For executives: This is a small, focused Laravel add-on that implements a common product behavior — hiding records from normal views while keeping the data intact — as a reusable pattern instead of custom code. The new 4.1.0 release is primarily a Laravel 11 compatibility update, which removes a blocker on our framework upgrade path and signals the package is maintained. Cost/benefit: low integration effort, reduced custom code and bug surface for "hide/restore" features, with the main residual risk being reliance on a small third-party maintainer — mitigated by keeping usage behind a thin internal abstraction so it can be swapped or replicated internally if maintenance lapses.

For engineering: v4.1.0 adds Laravel 11.x support (PR #30). It's a non-breaking, compatibility-only change — no migration or API changes implied for existing users. Recommended actions: bump to ^4.1, confirm the L11 constraint resolves in your lockfile, re-run the suite, and add explicit tests covering default-excluded and explicitly-included query paths. Because exclusion is enforced via global scopes, be deliberate about reporting/analytics queries and admin tooling that must see excluded rows, and avoid overlapping it with SoftDeletes on the same model.