Belich Tables Laravel Package

Getting Started

This release targets the Livewire/Alpine stack, so the first step is aligning your frontend dependencies before touching package code:

1. Require the package and confirm your app is on Livewire 2.5+ and Alpine 3.x. Alpine 2 will not work with this version — the internals assume Alpine 3 directive behaviour.
2. Publish the package config and assets (php artisan vendor:publish --tag=...) and read the config file first. The new default filters are defined there; that file is the single best map of how the package wires filtering into your components.
3. Load scripts in the correct order: Livewire's @livewireScripts first, then Alpine 3 (deferred). Alpine 3 expects to be loaded with defer and will initialise on DOMContentLoaded.
4. First use case: render the package's Livewire component inside a Blade view, let the shipped default filters apply, and confirm the filter state round-trips through the component. Once that renders, replace one default filter with a custom one to validate the extension path.

If you are upgrading, treat this as a frontend-dependency upgrade first and a package upgrade second — most breakage will surface in Alpine directives, not PHP.

Implementation Patterns

Component-first integration. Mount the package component (or extend its base Livewire component / apply its trait) inside your existing views rather than rebuilding filter UI by hand. Keep your own wrapper thin so package updates don't collide with custom markup.

Filters as configuration, not code. With defaults now shipped, the idiomatic pattern is to accept the defaults and append custom filters in config rather than redefining the whole set. Use the package's filter contract/abstract class for anything bespoke, and register it alongside — not instead of — the defaults.

Alpine 3 for the interaction layer. Use x-data to wrap filter widgets, $wire to call Livewire methods from Alpine handlers, and $dispatch for cross-component events. This is the pattern the Alpine 3 support is built for: Livewire owns server state, Alpine owns transient UI state (open/closed panels, debounce visuals, dropdowns).

Shareable filter state. Push filter properties into the query string via Livewire's $queryString so filtered views are linkable. This is the day-to-day win: users share a URL, the same default-plus-custom filter combination hydrates on load.

Event-driven filter changes. Emit a filter-changed event from the filter UI and listen in the results component. This keeps filter controls and result rendering decoupled and makes it trivial to add a second consumer (e.g. an export button) later.

Test at the Livewire boundary. Use Livewire::test() to assert that setting a filter property produces the expected result set, and that defaults are applied on mount. You get most of the coverage without browser tests; reserve Dusk/browser tests for Alpine-driven interactions.

Gotchas and Tips

• Alpine 3 is a breaking change from Alpine 2. x-spread is gone, x-init timing changed, the global Alpine object and magic properties behave differently, and x-on shorthand parsing is stricter. Audit any custom directives in your own Blade partials, not just package views.
• Script ordering bites. Alpine must initialise after Livewire has rendered. If you see directives silently not firing, it's almost always Alpine loading before Livewire's scripts or being loaded without defer.
• Morphdom will eat your Alpine state. Livewire re-renders can reset x-data scope. Use wire:ignore around Alpine-managed widgets and wire:key on repeated filter rows.
• Defaults vs. persisted state. New default filters may be applied on mount and overwrite query-string values depending on hydration order. Test a bookmarked filtered URL explicitly — this is the most likely regression from "Set the default filters."
• Config caching. After changing default filters, run php artisan config:cache (and clear it in local). A stale cached config makes it look like your filter changes were ignored.
• Livewire 2.5 is a floor, not a target. Livewire 3 changes script injection, wire:model deferral, and component lifecycle. If you're starting fresh, budget for a Livewire 3 migration rather than pinning to 2.5 long-term.
• Debugging toolkit. Livewire DevTools plus the Alpine DevTools extension let you inspect component state and directive scope side by side; $wire.get('filters') in the console is the fastest way to confirm what the server actually received.
• Extension points to prefer: publish and override package views, subclass the filter contract, append to the config filter list, and hook the filter-changed event. Avoid editing vendor files — the default-filter change in this release is exactly the kind of thing that will be overwritten.