Refine Nova Laravel Package

Getting Started

1. Prerequisites — A Laravel app running Laravel Nova (build target is Nova 4) and hammerstone/refine installed. Refine is the engine; this package is the thin Nova adapter that feeds Nova's filter state into a Refiner.

2. Install — composer require hammerstone/refine-nova. No service provider registration needed in modern Laravel; publish assets/config only if the README for your version says so.

3. Write a Refiner first — Before touching Nova, define a Refiner class (from hammerstone/refine) with filters() and sorts(). This is where 90% of your work lives; the Nova package only decides how those filters are presented and applied.

4. Register it on the resource — Add the package's refiner filter to filters() in your Nova resource:

   public function filters(Request $request)
   {
       return [
           new RefineFilter(UserRefiner::class),
           // ...native Nova filters
       ];
   }
   

5. First use case — Take an index page that has accumulated four or five native Nova filters (status, date range, text search, relation exists) and collapse them into one Refiner that you also reuse in your JSON API controller. That dual-use is the whole point of the package.

If you only have simple, single-column filters, stay with native Nova filters — Refine is overhead until you need composable, reusable, API-shareable filtering.

Implementation Patterns

• One Refiner per resource, shared everywhere. Put the Refiner in app/Refiners, then use it from the Nova filter, from API controllers (UserRefiner::for(User::class)->apply($request)->results()), and from console commands. Nova becomes one consumer, not a special case.
• Register the filter once, reuse the component. The Nova filter should be a thin shell — constructor arg is the Refiner class, nothing else. Avoid putting query logic in the resource.
• Compose alongside native filters. You can keep Nova's BooleanFilter/DateFilter for the simple cases and add the Refine filter for the complex ones. They stack; Nova merges each filter's constraints into the index query.
• Deep-linkable saved views. Nova serializes filter state into the query string, so a Refine filter state becomes a shareable URL. Use this for "saved views" by bookmarking or by generating links in a custom tool.
• Custom filter UI. If the default presentation doesn't fit, publish the package's Vue component and swap the filter's component name. Keep the component's payload shape identical so the PHP side keeps working.
• Test at the boundary. Instead of driving Nova's browser UI, test the Refiner directly with query params and assert on toSql() or result IDs. The Nova adapter is then a thin, low-risk layer you verify manually once.

Gotchas and Tips

• Staleness is still the main risk. v0.2.4 is the first fresh tag in a while, but its release note ("Fix a bug in Nova 3 (I think!)") tells you two things: the maintainer is not targeting Nova 4 with this patch, and the changelog is informal enough that you shouldn't assume coverage. Pin the version in composer.json, and before upgrading Nova, smoke-test the filter on one resource. If breaking changes land upstream, budget for a fork — at 34 stars the package is small enough that vendoring the filter class and its Vue component is a realistic afternoon.
• v0.2.4 changes nothing for Nova 4 users. The patch is scoped to Nova 3 compatibility. If you're on Nova 4, treat it as a no-op: upgrading is harmless but you should not expect the fix to touch any behaviour you rely on, and you should not read the new tag as evidence that Nova 4 support has been re-verified. Nova 3 users get a bug fix of unstated scope — verify the specific bug against your resource before celebrating.
• Confirm the query-param key. Refine and Nova each have their own convention for how filter state is serialized into the URL (filter[...] vs filters[...]). If the filter renders but does nothing, log $request->all() inside the Refiner and check the key actually arriving. This is the #1 integration bug.
• Authorization is not automatic. Refine filters operate on the Eloquent builder, not through Nova's per-filter canSee/policy checks. If a filter exposes a column a user shouldn't see (e.g. filtering by another tenant's relation), gate it in the Refiner's filters() method based on $request->user().
• Don't let it build a second query. The Nova filter must constrain the resource's index query. If you see correct filtered rows but the pagination count is wrong, you've likely applied filters to a separate builder — check that the filter returns a closure operating on $query rather than calling ->results().
• Debugging: dd($query->toSql(), $query->getBindings()) in the Refiner's apply is faster than tailing logs. The generated SQL also reveals whether your filter is using where vs whereHas correctly.
• Cache keys: If you cache index queries, the Refine parameter string must be part of the key. It's easy to forget because Nova's own filters are already baked into the page URL.
• Extension points worth knowing: the filter class itself (subclass to change presentation), the published Vue component, and the Refiner base class. Those three cover almost every customization you'll need — there's no deeper plugin layer to learn.