Roles Permissions Livewire Laravel Package

Getting Started

This is a presentation adapter, not a full RBAC implementation. Expect it to ship Livewire components/views that sit on top of a separate roles & permissions domain package (almost certainly another liberusoftware/* module). Your first job is to confirm what it depends on before writing any code.

1. Inspect the manifest first. Run composer show liberusoftware/roles-permissions-livewire and open the package's composer.json. You're looking for:
   • The require block — which core roles/permissions package it wraps.
   • extra.laravel.providers — whether auto-discovery is configured.
   • The Livewire version constraint (^3.0 vs ^2.0 will dictate component syntax).
2. Install both layers. If the core module isn't pulled in transitively, install it explicitly, then run its migrations before this package's (if any). A common failure mode is installing the Livewire adapter alone and hitting "class not found" or empty permission tables.
3. Publish assets. Typical tags to try:

   php artisan vendor:publish --provider="Liberu\RolesPermissionsLivewire\RolesPermissionsLivewireServiceProvider"
   # or, more reliably, inspect available tags:
   php artisan vendor:publish --list | grep -i roles
   

   Look for config, views, and lang tags. Migrations only if the adapter owns any tables (usually it doesn't).
4. Where to look first, in order:
   • src/Http/Livewire/ (or src/Livewire/) — the components you'll actually mount.
   • routes/web.php — whether routes are auto-registered (often behind a config flag/middleware group).
   • resources/views/livewire/ — the Blade you'll override when customizing.
   • config/roles-permissions-livewire.php — guard names, layout, middleware, route prefixes.
5. First use case: render the role index. Either hit the registered route (/admin/roles by convention) or embed the component directly in an existing admin view:

   <livewire:roles-permissions::role-index />
   

   If the namespace prefix differs, run php artisan livewire:list (Livewire 3) to see the registered component aliases rather than guessing.

Implementation Patterns

Mount inside your existing admin shell. Most teams don't want a second layout. Disable the package's layout in config and embed components in your own Blade:

<x-admin-layout>
    <livewire:roles-permissions::role-manager />
</x-admin-layout>

Check the config for a layout key — this is the single most common thing to change on day one.

Gate the surface area, not just the buttons. The components render UI; they do not necessarily enforce authorization. Wrap routes/mounts in your own middleware:

Route::middleware(['web', 'auth', 'can:manage-roles'])
    ->group(fn () => Route::get('/admin/roles', RoleIndexPage::class));

And verify the components call $this->authorize(...) internally — if they don't, add it by subclassing (below).

Subclass rather than fork. When you need extra columns, filters, or a different model, extend the component and swap the alias:

namespace App\Livewire;

use Liberu\RolesPermissionsLivewire\Livewire\RoleIndex as BaseRoleIndex;

class RoleIndex extends BaseRoleIndex
{
    public function render()
    {
        return view('livewire.admin.role-index', [
            'roles' => $this->rolesQuery()->withCount('users')->get(),
        ]);
    }
}

Then either override the component alias in a service provider (Livewire::component('roles-permissions::role-index', RoleIndex::class)) or reference your class directly. Prefer this over editing vendor views.

Override views via publish, not resources/views/vendor guesswork. Confirm the exact namespace by inspecting the component's render() method, then publish and edit. If the view path is roles-permissions-livewire::livewire.role-index, the published file lands at resources/views/vendor/roles-permissions-livewire/livewire/role-index.blade.php.

Wire to your user model deliberately. This adapter will assume a specific contract — either Spatie's HasRoles trait or a Liberu core trait. Verify:

class User extends Authenticatable
{
    use HasRoles; // confirm which trait the core package expects
}

If guards differ (e.g., admin vs web), set the guard in config and ensure your auth provider matches. Mismatched guards produce "role not found" with no error.

Event-driven invalidation. Role changes made through these components should invalidate any cached permission maps. If the core package registers cache invalidation on RoleAttached/RoleDetached events, confirm those fire; if you have a custom cache layer, listen to the same events and flush.

Testing pattern. Livewire components are cheap to test — do it rather than clicking around:

Livewire::actingAs($admin)
    ->test(RoleIndex::class)
    ->assertSee('Administrator')
    ->call('deleteRole', $role->id)
    ->assertHasNoErrors();

Seed roles/permissions in a setUp fixture so component tests don't depend on migrations running in a specific order.

Gotchas and Tips

This package is thin by design — the risk lives in the core module. With 0 stars and 0 dependents, treat it as unaudited. Read src/ end-to-end before production: you're looking for missing authorize() calls, mass-assignment on role/permission creation, and unvalidated syncPermissions payloads. Livewire's public-property model makes it easy to expose more than intended.

License is NOASSERTION. That's a red flag for commercial use — no declared license means all rights reserved by default. Get written clarification or avoid until resolved. Do not assume MIT because siblings in the liberusoftware org are MIT.

The release date (2026-10-26) is in the future. Check tags/branches with composer show --all and inspect the actual commit history. You may be pulling a dev branch or a misconfigured tag; pin explicitly:

"liberusoftware/roles-permissions-livewire": "dev-main#<sha>"

Livewire version skew is the #1 install failure. If your app is Livewire 3 and the package's constraints are ^2.0, components will fail on wire:model semantics, @entangle, and the missing ->layout() API. Check the constraint before installing; don't try to force-resolve.

Tailwind content paths. Vendor Livewire views are scanned by the package's own CSS or not at all. If components render unstyled, add the publish path to tailwind.config.js:

content: [
  './resources/views/**/*.blade.php',
  './vendor/liberusoftware/roles-permissions-livewire/resources/views/**/*.blade.php',
]

Config caching bites on route/middleware changes. After editing the package config, run php artisan config:clear — Livewire component aliases and route prefixes registered from config won't pick up changes under config:cache.

Extension points, ranked by safety:

1. Config overrides (guard, layout, route prefix, middleware).
2. View publishing + override.
3. Component subclassing + alias rebinding.
4. Model swapping via config ('models.role' => App\Models\Role::class) — only if the package reads models from config; verify in src/.
5. Forking — last resort, and you'll own the maintenance.

Debugging checklist when a component renders empty:

• php artisan livewire:list — is the alias registered?
• Is the authenticated user resolving via the configured guard?
• Do roles / permissions tables contain rows? (Adapter won't seed them.)
• Is the core package's service provider registered before this one in bootstrap/providers.php?
• Check storage/logs/laravel.log for a swallowed AuthorizationException.

No dependents means no community escape hatch. Budget time for reading source and writing your own tests. If you need production-grade RBAC UI, weigh this against wiring Filament Shield or hand-rolling a small admin screen against Spatie — often less total risk than adopting a thin, unmaintained adapter.