Analytics Core Livewire Laravel Package

Getting Started

This is a presentation adapter, not an analytics engine. It exists to sit on top of liberusoftware/analytics-core (the domain package that owns the metrics, aggregations, and storage) and expose that domain through Livewire components — dashboards, widgets, filters, charts. Treat it as a thin view layer and your mental model will be correct from day one.

Before you write a single line, do this:

1. Read the repo source, not the README. With zero stars, zero dependents, and a NOASSERTION license, the README will not be a contract. The src/ tree and composer.json are. Identify: the service provider class, the Livewire::component(...) registrations (this tells you the exact component aliases you'll type in Blade), and the views/ namespace.
2. Install the core alongside it. The adapter is useless alone. Confirm which version of liberusoftware/analytics-core the adapter's composer.json requires — that constraint is your real compatibility matrix.
3. Check the Livewire major version. Livewire 2 ($listeners, mount() semantics, wire:model) and Livewire 3 (attributes, wire:model.live) are not interchangeable. Given the 2026 release date, assume v3 but verify.
4. Confirm the module registration mechanism. Liberu packages typically register through a module manifest or a module.json consumed by liberusoftware/module-* tooling. If you're not running that ecosystem, you may need to register the provider manually in bootstrap/providers.php.

Your first use case should be the smallest possible one: render a single widget or dashboard component inside an authenticated Blade view and confirm it returns data. Something like:

<livewire:analytics.dashboard />

or, if the package exposes widgets individually:

<livewire:analytics.widget name="revenue.last_30_days" />

Do not start by customizing views. Get the default rendering working first — that validates the provider, the view namespace, the Livewire registration, and the core's data access in one shot. If nothing renders, your problem is almost always registration, not analytics.

Implementation Patterns

Adapter as composition root. Keep your own application code ignorant of analytics-core internals. Your controllers and Blade templates should reference only the adapter's Livewire components and its published config. When the core changes shape, you patch one adapter boundary instead of grepping your codebase.

Filter binding via public properties. The dominant pattern in packages like this is a dashboard component with public filter state ($from, $to, $granularity, $segment) updated by wire:model.live. Drive everything from those properties rather than passing filters as component parameters — it keeps the URL-independent state in one place and makes #[Url]-style shareable dashboards trivial to add later.

<livewire:analytics.dashboard :from="$start" :to="$end" />

Widget composition over monolithic dashboards. If the package ships a Dashboard component that hardcodes a grid, prefer building your own layout in Blade and dropping individual widget components into it. You get layout control, lazy-loading per widget (<livewire:... lazy />), and independent loading states — which matters enormously when one widget runs a 3-second aggregate query.

Wrap in your own thin components. Create App\Livewire\Reports\RevenuePanel that extends or composes the package component and pins your defaults (timezone, currency, tenant scope). This is your extension point for anything the package doesn't expose: it lets you add authorization, caching, or pre-processing without forking.

Cache at the adapter boundary. Analytics queries are expensive and dashboards are hit constantly. Cache the results, keyed on (widget, filters, tenant, user-scope), with a TTL that matches your data refresh cadence. Livewire's #[Computed] or a Cache::remember inside the component's data-fetch method is usually enough. Never let a dashboard issue a fresh aggregate on every poll.

Poll deliberately. If the package exposes wire:poll, use it only on low-cost counters. For anything heavy, poll a cached summary or skip polling entirely and give the user an explicit refresh button.

Authorize the component, not the route. Analytics data is sensitive and often crosses tenant/role boundaries. Add AuthorizesRequests and a mount() guard to your wrapper components. Don't assume the package does this — a presentation adapter rarely owns the authorization policy.

Gotchas and Tips

The license is NOASSERTION. This is not a formality. It means the repository does not declare a recognized OSI license, so your legal position for production use is unclear. Get this resolved before the package lands in a commercial product. For an internal tool, note it and move on.

Zero stars, zero dependents, no release history to speak of. You are the first serious consumer. Expect missing edge-case handling, undocumented behavior, and no Stack Overflow answers. Budget time to read the source and be prepared to fork. Pin the exact version in composer.json — do not use a floating constraint, because a silent minor bump in a package with no dependents has no downstream pressure to stay compatible.

View namespace collisions. Packages that publish views under a generic namespace like analytics:: can collide with the core package or with your own app views. Check loadViewsFrom in the provider and confirm the namespace is distinct. If it isn't, publish and override.

wire:key on widget loops. If you render widgets in a @foreach, always include a stable wire:key. Without it, Livewire will reuse DOM nodes across filter changes and you'll get charts that don't re-render or render the previous dataset — the classic "data changed but the chart didn't" bug.

Chart library assumptions. Presentation adapters frequently assume a specific front-end chart stack (Chart.js, ApexCharts, Filament widgets). Check the published assets and @once @push('scripts') blocks. If your layout doesn't have the expected stack, components render blank with no error. This is the single most common "it's installed but nothing shows" cause.

Empty vs. zero. Analytics components often conflate "no data" with "zero value". Verify how a fresh install with an empty events table renders — you want a deliberate empty state, not a crash on max() of an empty collection.

Timezone and date boundaries. Filters passed as strings get parsed somewhere; make sure it's the same timezone your core aggregates in. Off-by-one-day dashboard totals are almost always a UTC/local mismatch at the adapter boundary, not a core bug.

Debugging order. When a widget misbehaves: (1) confirm the component is registered — php artisan livewire:list or dump the component aliases; (2) confirm the view resolves — php artisan view:clear then check for a View [analytics::...] not found; (3) confirm the core returns data by calling the underlying service directly in tinker. Isolating the adapter from the core is the fastest way to find which layer is broken.

Extension points to look for (and to prefer over forking): published config, published views, a resolve()/binding in the container for swapping the data provider, and any protected function getData() style hook in the components. If the package offers none of these, subclassing is your only lever — so design your wrapper components to be the seam from the start.