Nova Searchable Belongs To Filter Laravel Package

Product Decisions This Supports

• Build vs. buy for admin tooling. A searchable belongsTo filter is a narrow, well-understood piece of custom engineering. Writing the equivalent in-house means an async search endpoint, a Vue component, Nova asset registration, and ongoing upgrade tracking. An MIT dependency of a few hundred lines costs less to adopt and pin than to rebuild — a tactical buy, not a platform commitment.
• Back-office usability as an operational metric. Nova's stock BelongsTo filter renders a <select> containing every row of the related table. On high-cardinality relationships (customers, accounts, owners, regions) that means slow index pages and unusable dropdowns. Type-ahead search cuts time-to-find and mis-selections, measurable in admin clicks and seconds for a real task like "find the post by author Jordan Lee."
• Roadmap placement. This belongs in the internal tooling / admin productivity bucket, not the differentiation bucket. Fund it from operational-excellence or tech-debt budget rather than customer-facing capacity; it clears admin workflow complaints without consuming a sprint.
• Upgrade and platform-modernization planning. v2.0.3 is a compatibility-only patch adding Laravel 11 to the Composer constraint — no API changes, no deprecations. That moves the package from "upgrade blocker" to "keep" during a Laravel 11 migration. Critical caveat: Laravel 11 support does not imply a validated Nova major version. Confirm the Nova pairing separately before writing it into the upgrade path, since Nova's release cadence is not coupled to Laravel's.
• Dependency governance and technical-debt posture. Low adoption (29 stars, 0 dependents), single maintainer, no test suite, narrow scope. That profile argues for version pinning, a named owner, quarterly review, and a documented fork-or-replace fallback — not for rejection. Cheap to adopt and cheap to abandon is exactly what makes a small dependency defensible.
• Use-case validation before commitment. Confirm the pain is real and recurring: admins repeatedly filtering belongsTo relationships where the related table has thousands of records. If related tables are small, the package delivers nothing and the native filter is correct.

When to Consider This Package

Adopt when:

• The team already runs Laravel Nova. Hard prerequisite — this is a Nova filter and adds nothing to a non-Nova admin stack. Never introduce Nova for this package.
• Users repeatedly struggle with long belongsTo filter dropdowns. The value scales with cardinality. Start with the biggest related table, not the most complex resource; blast radius is nil (one line in filters(), one-line revert), so there is no reason to pilot on something trivial.
• The app is on Laravel 11 or migrating to it. Require ^2.0.3 specifically — earlier tags don't declare Laravel 11 support and Composer will refuse on constraint conflicts. Run composer why-not during adoption.
• You can absorb the operational guardrails. That means pinning the exact version, naming an owner, adding a smoke test that asserts tenant scoping and authorization, and documenting the one-line fallback to Laravel\Nova\Filters\BelongsTo in the admin runbook.
• Search columns can be indexed. Default to identifiers admins already type (name, email, account_number, external_id) and make sure the searched columns have indexes. A LIKE '%term%' scan on a 500k-row table turns a snappy filter into a timeout.

Look elsewhere when:

• You're not on Nova, or you're planning to leave it. The package is a thin wrapper over Nova's filter contract; it carries no value outside that ecosystem.
• Related tables are small. Under a few thousand rows the native filter is fine and this adds a dependency for zero gain.
• You need complex filter semantics. Multi-relationship, cross-resource, or sophisticated multi-select logic is explicitly out of scope. The extension model is plain PHP inheritance plus an apply() override — no config file, no events.
• You need a supported, SLA-backed dependency. Single maintainer, 29 stars, zero dependents, no test suite. Read src/SearchableBelongsToFilter.php and resources/js/components/Filter.vue end-to-end (an afternoon) and treat the source as the spec before signing off.
• Nova 5 is on the roadmap and unvalidated. The changelog only touches the Laravel constraint. Treat Nova upgrades as a re-test trigger, not an assumption.

How to Pitch It (Stakeholders)

For executives — one paragraph. Our Nova admin panel has a filter that lists every record in a related table as a dropdown. On our largest tables that makes admin index pages slow and the filter practically unusable, which shows up as wasted staff time and wrong-record selections. This is an MIT-licensed, few-hundred-line package that swaps that dropdown for a type-ahead search box. It's a one-line change per resource, it stores the same filter value so bookmarks and existing workflows keep working, and reverting is another one line. Cost is essentially zero; the return is measurable admin time saved on the exact screens where staff currently scroll thousands of rows.

For engineering — the technical summary. A drop-in replacement for Laravel\Nova\Filters\BelongsTo. SearchableBelongsToFilter::make('Author')->filterBy('author')->searchColumns(['name','email']) — note filterBy takes the relationship method name, not the foreign key column. Install is composer require suenerds/nova-searchable-belongs-to-filter followed by php artisan nova:publish; the first failure mode for a filter that renders but appears inert or unstyled is unregistered compiled assets, so hard-refresh and check the network tab before debugging anything else. The stored filter value stays a scalar related-model ID, so the filtered index behaves identically to the old filter and existing filter URLs keep resolving.

What we're asking engineering to own. Pin ^2.0.3 (Laravel 11 support landed there; earlier tags don't declare it). Ship it first on the highest-cardinality relationship. Add an acceptance test that visits a Nova index with the filter applied and asserts expected records appear and an out-of-scope tenant's records do not — authorization flow through the related resource's indexQuery must be verified, not assumed, because the failure mode is cross-tenant data exposure rather than a UX bug. Verify empty state means "no constraint" and that a saved filter value renders the selected label without a search round-trip. Check Filter.vue for a result cap and debounce; if there isn't one, add a take() constraint via apply() override. Run a two-way UAT with ops — same task, old filter vs. new — and put the clicks-and-seconds delta in the release note. Re-test the Nova index page after every Nova or Laravel major bump, and keep the one-line revert documented.