Search Livewire Laravel Package

Getting Started

• Install with composer require liberusoftware/search-livewire. Because this is a presentation adapter, also confirm the underlying search module (likely liberusoftware/search or similar) is installed and configured — this package almost certainly does not implement search itself.
• Check composer.json for required versions of livewire/livewire, Laravel, and the core search package. With 0 stars and a recent release date, verify compatibility against your app before committing.
• First places to look after install:
  • config/search-livewire.php (publish with php artisan vendor:publish --tag=search-livewire-config if available)
  • resources/views/ for the search UI Blade templates
  • src/ for the Livewire component class (commonly Search or SearchBar)
  • The service provider for component aliases and view namespaces (search-livewire::...)
• First use case: render the component in a Blade layout and point it at your search backend. Typical shape:

<livewire:search-livewire.search />
{{-- or the alias registered by the service provider --}}

• Before wiring UI, verify the search service resolves from the container and returns results in tinker. If the adapter is thin, most failures will come from the underlying search module, not Livewire.

Implementation Patterns

• Embed as a self-contained component. Keep the search box and results in one Livewire component so query state, pagination, and result rendering stay in sync. Avoid splitting query input and results across components unless you explicitly dispatch events.
• Bind query with debounce. Use wire:model.debounce.300ms="query" (Livewire v2) or wire:model.live.debounce.300ms="query" (v3) to avoid flooding the search backend on every keystroke.
• Override the component for app-specific behavior. Extend the package's Livewire class, override render() or result-mapping methods, and register your subclass in the layout. This is usually cleaner than editing vendor views.
• Publish and customize views. Publish views to resources/views/vendor/search-livewire and adjust markup, result partials, and empty states. Keep the package's class names and wire: bindings intact to avoid breaking the component contract.
• Drive filters and facets through public properties. Expose filters as Livewire properties (public array $filters = []), pass them to the search service, and reset pagination when filters change. This keeps everything bookmarkable via query-string syncing: protected $queryString = ['query', 'filters'];
• Paginate via the search backend, not Eloquent. If the underlying search returns paginated results, use its paginator or map to a LengthAwarePaginator before rendering. Do not call ->paginate() on a collection.
• Integration tip: wrap the component in your layout and pass initial state via attributes:

<livewire:search-livewire.search :query="request('q')" :filters="request('filters', [])" />

• Testing pattern: use Livewire's test helpers to assert query updates and rendered results:

Livewire::test(Search::class)
    ->set('query', 'laravel')
    ->assertSee('Laravel');

Mock or fake the underlying search service so tests do not depend on an external engine.

• Workflow: treat this package as the UI layer only. Put ranking, indexing, and result shaping in the search module or a repository class, and keep the Livewire component responsible for input state, loading indicators, and rendering.

Gotchas and Tips

• Low adoption risk. Zero stars, zero dependents, and a NOASSERTION license mean you should audit the license and source before production use. Confirm the license file is present and compatible with your project.
• Version pinning. Livewire v2 vs v3 differences (wire:model vs wire:model.live, $emit vs $this->dispatch) can silently break the adapter. Check the package's composer.json constraints and pin Livewire accordingly.
• Component alias collisions. The service provider may register a generic alias like search. If you have your own Search component, use the fully qualified class name in Blade or rename the alias in config.
• Views not found. If you see View [search-livewire::...] not found, the view namespace is not registered or views were not published. Run php artisan vendor:publish and check the service provider's loadViewsFrom path.
• Assets and styling. Many presentation adapters assume Tailwind or Alpine. If the component renders unstyled or JavaScript interactions fail, check whether the package expects specific frontend assets. Publish assets with the package's tag if documented; otherwise inspect the Blade for @once, @push, or x-data usage.
• N+1 and heavy result mapping. When mapping search hits to models, eager-load relationships. If the adapter hydrates Eloquent models per result, this can explode query counts. Prefer projecting only needed fields or a dedicated read model.
• Pagination reset bugs. When query or filters change, explicitly call $this->resetPage() (or the package's equivalent). Otherwise users land on page 5 of a smaller result set and see an empty list.
• Debugging Livewire interactions. Use $this->dispatchBrowserEvent / dispatch and browser devtools to confirm requests fire. For backend failures, log the search service response and check whether the adapter swallows exceptions during rendering.
• Extension points to prefer: subclass the Livewire component, override render()/result formatting, and publish config/views. Avoid editing files in vendor/ — the package is not widely used, so updates may still contain breaking changes.
• Query-string state. If the component syncs query parameters, ensure names do not collide with other filters on the page. Add #[Url(as: 'q')] (Livewire v3) or $queryString carefully.
• Fallback plan. Given the maturity level, keep the search backend decoupled. If the adapter becomes unmaintained, you should be able to replace the Livewire component with a small custom component without rewriting search logic.