Integrations Livewire Laravel Package

Getting Started

Know what you're installing. The description — "integrations livewire presentation adapter" — says this is the UI layer only. It renders Livewire components for an integrations domain that lives elsewhere (almost certainly a sibling integrations core module in the same Liberu module family). Installing this package alone will not give you working integrations; it gives you screens and actions that call into services you must also have.

1. Confirm the core is present first:

   composer show | grep -i liberu
   

   You want the integrations domain/application module alongside this one. If it's missing, stop here — nothing in the adapter will resolve.

2. Install and let the module provider register itself:

   composer require liberusoftware/integrations-livewire
   php artisan optimize:clear
   php artisan vendor:publish --provider="Liberu\IntegrationsLivewire\Providers\IntegrationsLivewireServiceProvider"
   

   Treat the provider FQCN as a guess until you check src/Providers/ — Liberu's namespace casing varies across modules.

3. Read these four things, in this order, before writing any code:

   • composer.json → the require block tells you which core module and which Livewire major version you're bound to.
   • src/Providers/*.php → reveals view namespaces, config keys, and any container bindings you can swap.
   • src/Livewire/ (or src/Http/Livewire/) → the component list is the feature list.
   • resources/views/livewire/ → tells you what each component expects and what it emits.

4. First use case — drop the index screen into an existing page:

   {{-- resources/views/dashboard.blade.php --}}
   <livewire:integrations.index />
   

   Use php artisan route:list and grep for livewire to see whether the package ships standalone routes you can just visit, or whether everything is meant to be embedded.

If the component alias isn't what you guessed, list what's actually registered:

php artisan tinker
>>> collect(app(\Livewire\Livewire::class)->getComponents())->keys()->filter(fn($k) => str_contains($k, 'integration'));

Implementation Patterns

Treat the adapter as a boundary, not a place for logic. The healthy pattern with a package like this is: Livewire component owns UI state (search term, pagination, modal visibility, form input), and delegates every decision to the core module's actions/services. When you need behaviour the adapter doesn't expose, add it to the core and surface it through the component — don't reach into models from the Blade template.

Embedding vs. owning. Two viable integrations:

• Embed (<livewire:integrations.index />) when you want the package's screens as-is. Fast, zero maintenance, but you inherit its layout assumptions.
• Compose when you need it inside your own shell. Publish the views and strip the layout wrapper, or subclass the component and override render() to point at your own view:

  class IntegrationsIndex extends \Liberu\IntegrationsLivewire\Livewire\Index
  {
      public function render()
      {
          return view('app.integrations.index');
      }
  }
  

Pass identifiers, not objects. If a component takes a connection/integration, pass a route-bound key or ID and let the component resolve it. Serialising models across Livewire requests is where these adapters break first.

Authorization belongs in mount(), not the view. Whatever the core exposes (policies, gates, ability checks), call it up front so unauthorised users get a 403 rather than an empty table:

public function mount($integration)
{
    $this->authorize('view', $integration);
    $this->integration = $integration;
}

Credential forms need deliberate hydration settings. For API keys and tokens, prefer wire:model.blur (or ->defer) over live binding, use type="password", and never ->live() on a secret field — every keystroke becomes a request payload visible in the network tab and in any request logging middleware.

Long-running work goes to a queue. Integration "test connection" and "sync now" actions are the classic Livewire trap: a 30-second HTTP call inside a component request blocks the worker and hits PHP/gateway timeouts. Dispatch a job and poll status:

public function sync()
{
    SyncIntegration::dispatch($this->integration);
    $this->status = 'queued';
}

Then wire:poll.5s on a status property, or a broadcast event if the core emits one.

Testing. Bind a fake for the core service and assert the component renders state, not side effects:

Livewire::test(IntegrationsIndex::class)
    ->set('search', 'stripe')
    ->assertSee('Stripe')
    ->assertDispatched('integration-selected');

This is also the fastest way to discover the public API — Livewire::test() against an unknown component fails loudly and usefully.

Extending. Typical extension points for this class of package, in order of likelihood: publishable views (vendor:publish --tag=...views), a config file for route prefixes/middleware/component registration, and container bindings for the services the components resolve in mount(). Check all three before forking.

Gotchas and Tips

This is effectively undocumented, zero-adoption software. Zero stars, zero dependents, no public issue history means: no Stack Overflow answers, no blog posts, and no one else has hit your bug. Budget for reading src/ as your primary documentation, and vendor the package (composer require then commit vendor/ or use a path repository) if you plan to patch it.

The release metadata is inconsistent. The listed last release (2026-10-26) is in the future relative to typical tooling, which usually means a mistagged date, a dev-main branch masquerading as a release, or a monorepo split artefact. Pin an explicit version or commit SHA in composer.json — do not float on ^1.0 or dev-main for a package this young.

Pin the Livewire major. Component syntax diverged hard between v2 and v3: wire:model vs wire:model.live, $emit/dispatchBrowserEvent vs dispatch(), $listeners vs #[On]. A presentation adapter written for one will render but silently fail to update on the other. Check composer.json's Livewire constraint and align your app, not the other way around.

View namespace collisions. In multi-module Liberu installs, several modules register view namespaces and component aliases. If integrations.index resolves to the wrong class, you're seeing last-registered-wins. Verify with the component registry dump above, and check provider boot() order in bootstrap/providers.php.

Clear caches after every install step. config:cache and route:cache will happily serve a stale world where the module provider doesn't exist. Run php artisan optimize:clear before concluding the package is broken.

Watch for hard-coded layout references. Adapters commonly @extends('layouts.app') or assume a specific admin theme. If pages render blank or throw a missing-view exception, publish the views and repoint the layout — that's usually the entire fix.

Debugging checklist, in order: (1) provider registered? php artisan about; (2) component alias resolves? registry dump; (3) view found? php artisan view:cache and read the exception path; (4) service resolves? bind it in tinker directly; (5) request payload correct? Livewire devtools / browser network tab. The failure is almost always at step 1–3, not in your Blade.

Secrets hygiene. Integration UIs handle API keys, OAuth tokens, and webhook secrets. Confirm the adapter doesn't persist raw credentials into public Livewire properties (they're serialised into the DOM), doesn't log request payloads on failed saves, and that any "reveal" affordance is gated. Given the package's maturity, assume nothing here is audited and review the credential path yourself before shipping.