Settings Livewire Laravel Package

Getting Started

Because this package is an adapter rather than a standalone product, treat installation as a two-part dependency: the presentation layer plus the domain layer it renders. Start with:

composer require liberusoftware/settings-livewire livewire/livewire

Then confirm whether it also requires the underlying settings domain package (likely liberusoftware/settings or a module in the same Liberu monorepo). Check the package’s composer.json before assuming — the adapter may only declare a peer dependency or expect the host application to provide the settings repository.

First places to look after install:

1. src/Providers/*ServiceProvider.php — reveals the Livewire component aliases, view namespace, config file, and whether routes are auto-registered.
2. src/Livewire/ or src/Http/Livewire/ — the actual components; this is where the public API lives (properties, mount() arguments, action methods).
3. resources/views/ — Blade structure tells you what fields and layout you get, and what is publishable/overridable.
4. config/settings-livewire.php (if present) — usually controls component registration, route prefixes, middleware, and view paths.

Publish assets early so you can customize without editing vendor code:

php artisan vendor:publish --tag=settings-livewire-config
php artisan vendor:publish --tag=settings-livewire-views

A sensible first use case is an admin settings screen: a route guarded by your admin middleware that renders the package’s settings component, scoped to a group such as general or site. Embed it in an existing admin layout rather than using it as a full page, which lets you integrate it incrementally:

<livewire:settings-panel group="general" />

Verify the exact component alias from the service provider — adapter packages sometimes register namespaced aliases (e.g. settings-livewire::panel).

Implementation Patterns

Full-page vs embedded panel. Most presentation adapters support both. Use the full-page component when settings editing is a distinct admin destination; embed it when settings belong inside a larger dashboard. Embedding is usually better for day-to-day leverage because it avoids fighting the package’s layout assumptions.

Group/key scoping. Pass a group (and tenant or team key, if supported) through the component props or route parameter. Keep the adapter ignorant of business rules: it should render whatever the settings repository returns for that scope. If the component accepts a settings DTO or repository instance, inject it in mount() rather than hard-coding keys in Blade.

Form objects and validation. Livewire adapters typically bind to Livewire form objects or arrays. Follow the package’s convention — if it ships a form class, extend it rather than duplicating $rules in your own component. For custom fields, prefer adding validation in a subclass or published view partial over editing vendor code.

Authorization at the edges. Put can:manage-settings middleware on the route and, for embedded use, gate the component’s visibility in Blade with @can. Don’t rely on the component to authorize; adapters usually render whatever they’re given and assume the host has guarded access.

Events as the integration seam. Settings saves usually dispatch a Livewire event (e.g. settings-updated, settings.saved). Listen in sibling components to refresh navigation labels, cache-bust config, or update theme previews:

#[On('settings-updated')]
public function refreshSettings(): void
{
    $this->settings = $this->repository->all();
}

Extending fields. The productive pattern is: publish views → copy the field partial → register your field type if the adapter supports a field registry. If there’s no registry, subclass the component and override render() or a fields() method. Keep domain persistence in the settings package; the adapter should only translate input into calls on the domain service.

Testing. Use Livewire’s test helpers against the component directly:

Livewire::test(SettingsPanel::class, ['group' => 'general'])
    ->set('settings.site_name', 'Example')
    ->call('save')
    ->assertHasNoErrors()
    ->assertDispatched('settings-updated');

This is also the fastest way to discover the component’s real property names when documentation is absent.

Composition with other modules. Treat this as a UI plug-in inside a modular Liberu app. Keep cross-module coupling to Livewire events and the settings repository contract; avoid importing the adapter’s internals into other modules so you can swap the presentation layer later.

Gotchas and Tips

• Zero ecosystem signal. With no stars and no dependents, there are effectively no community answers, tutorials, or Stack Overflow threads. Budget time to read the source. Start with the service provider and component classes; that is usually faster than guessing from the README.
• License is NOASSERTION. This is a compliance flag, not a nuisance. Before using it in client or commercial work, confirm the actual license in the repository (LICENSE file, composer metadata, or the maintainer). NOASSERTION means automated tooling could not classify it, not that it is unlicensed — but you should not assume permissiveness.
• Version and release dates look unusual (the listed last release is in the future relative to typical package timelines). Pin exact versions in composer.json and check tags/branches rather than relying on ^ constraints. In monorepo-derived packages, tags sometimes diverge from the code you expect.
• Livewire 2 vs 3 differences. Check the installed Livewire major version against the adapter’s constraints. Watch for wire:model vs wire:model.live, $emit vs $this->dispatch(), and #[On] attributes. Mixing versions produces silent no-op updates rather than clear errors.
• Component alias collisions. Adapters often register generic aliases like settings. Run php artisan livewire:list (or inspect the provider) and namespace your own components to avoid conflicts.
• Config and view caching. After publishing config or views, run php artisan optimize:clear. Stale compiled views are the usual cause of “my published view isn’t being used.”
• View namespace overriding. Publish with the correct tag and override via the package’s namespace (settings-livewire::...), not by creating a same-named view in resources/views unless the package explicitly supports that path.
• Don’t put domain logic in the adapter. Validation that enforces business invariants, encryption of secret settings, and persistence belong in the settings domain package. The adapter is a thin translation layer; keeping it thin makes upgrades and replacement easier.
• Debugging workflow. When a save silently fails: inspect the component’s save() method, confirm the property names bound in the published Blade view, check authorization middleware, and use Livewire::test() to isolate whether the problem is UI binding or domain persistence. assertSet() and assertDispatched() narrow it quickly.
• Extension points to prefer, in order: config → published views → Livewire events/listeners → subclassing the component → editing vendor files (avoid). If the package lacks a documented extension point, the published view plus a subclass is usually the least fragile route.
• Watch the wider module graph. Packages in this ecosystem tend to share version constraints across module-settings, module-settings-livewire, and the host app. A composer update in one can strand the others; update the settings-related packages together and run the Livewire component tests afterward.