Getting Started

Minimal Setup Steps

Install Dependencies

composer require beartropy/permissions spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan migrate

Configure User Model Add the HasRoles trait to your User model:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Publish Package Config
```
php artisan vendor:publish --tag=beartropy-permissions-config
```
Update config/beartropy-permissions.php as needed (e.g., middleware, guards, or route prefix).
Access the UI Navigate to /permissions (or your configured route prefix) in your Laravel app.

First Use Case: Assigning a Role to a User

Log in as an admin with manage-permissions gate access.
Navigate to the Users tab in the permissions manager.
Search for the target user.
Click the Assign Roles button (pencil icon).
Select the desired role(s) from the modal and click Save.

Where to Look First

Documentation: beartropy.com/permissions (official docs).
Source Code: Focus on:
- src/Livewire/ for core components (e.g., PermissionsManager, RolesTable).
- config/beartropy-permissions.php for configuration options.
Views: Published under resources/views/vendor/beartropy-permissions/ after running vendor:publish --tag=beartropy-permissions-views.

Implementation Patterns

Workflow: Managing Permissions

Define Permissions Use dot notation (e.g., posts.create) for automatic grouping in the UI.

// Example: Create a permission via a seeder or migration
Spatie\Permission\Models\Permission::create(['name' => 'posts.create']);

Create Roles
- Navigate to the Roles tab in the UI.
- Click Add Role and define permissions via the modal.
- Use the Permission Groups feature (enabled via group_permissions config) to filter permissions by category (e.g., posts.*).
Assign Roles to Users
- Use the Users tab to bulk-assign roles or assign roles individually via the Assign Roles modal.
Bulk Actions
- Select multiple rows in any table (Roles, Permissions, or Users) and use the bulk delete action (trash icon).

Integration Tips

1. Authorization

Use the manage-permissions gate (configurable via gate in beartropy-permissions.php).

Example policy:

Gate::define('manage-permissions', function ($user) {
    return $user->hasRole('admin'); // Customize as needed
});

2. Customizing Routes

Override the default route by adding this to your routes/web.php:

Route::middleware(['web', 'auth'])
     ->prefix('admin')
     ->group(function () {
         Route::get('permissions', \Beartropy\Permissions\Livewire\PermissionsManager::class)
              ->name('permissions.manager');
     });

Update the prefix in config/beartropy-permissions.php to match.

3. Extending Components

Override Views: Publish views (vendor:publish --tag=beartropy-permissions-views) and modify them in resources/views/vendor/beartropy-permissions/.

Customize Tables: Extend the beartropy/tables components used by the package. For example, add a custom column to the RolesTable:

use Beartropy\Permissions\Livewire\RolesTable;

class CustomRolesTable extends RolesTable
{
    public function columns()
    {
        return parent::columns()->add(
            Column::make('Created At', 'created_at')
                ->dateTime()
        );
    }
}

Livewire::component('beartropy-permissions.roles-table', CustomRolesTable::class);

4. Internationalization

Publish translations:

php artisan vendor:publish --tag=beartropy-permissions-lang

Add custom translations to resources/lang/{locale}/permissions.php.

5. Dark Mode

The package supports dark mode out of the box. Ensure your app’s theme includes the dark class toggle or use a package like laravel-dark-mode.

Common Patterns

Task	Pattern
Sync permissions on login	Use `Auth::user()->syncPermissions()` or leverage Spatie’s cache.
Dynamic permission checks	Use `Gate::forUser($user)->allows('permission.name')` in your app.
Bulk user role updates	Use the Users table’s bulk action dropdown to assign roles.
Permission groups	Enable `group_permissions: true` in config and use dot notation.

Gotchas and Tips

Pitfalls

Middleware Misconfiguration
- If users can’t access /permissions, verify the middleware array in config/beartropy-permissions.php includes auth and your custom gate middleware.
- Example:
```
'middleware' => ['web', 'auth', 'verified', 'can:manage-permissions'],
```
Permission Caching Issues
- After bulk deletes or sync operations, Spatie’s permission cache may not update immediately. Clear it manually:
```
Spatie\Permission\Permission::clearCachedPermissions();
```
- The package automatically clears the cache on delete operations, but manual clearing may be needed in edge cases.
N+1 Query Warnings
- The package uses withCount() to mitigate N+1 queries, but if you extend tables, ensure you replicate this pattern:
```
public function query()
{
    return parent::query()->withCount('permissions');
}
```

Livewire 3 vs. 4

The package supports both Livewire 3 and 4. If you encounter routing issues, ensure your routes/web.php uses:

Route::livewire('/permissions', \Beartropy\Permissions\Livewire\PermissionsManager::class);

For Livewire 3, fall back to:

Route::get('/permissions', \Beartropy\Permissions\Livewire\PermissionsManager::class);

Guard-Specific Permissions
- Permissions are scoped to guards (e.g., web, api). If you use multiple guards, ensure your config specifies the correct default_guard:
```
'guards' => ['web', 'api'],
'default_guard' => 'web',
```

Debugging Tips

Livewire Logs Enable Livewire logging to debug component interactions:
```
'livewire' => [
    'log' => env('APP_DEBUG'),
],
```
Check storage/logs/livewire.log for errors.
Gate Authorization Verify the manage-permissions gate is properly defined and cached:
```
php artisan cache:clear
php artisan config:clear
```
Permission Grouping If groups don’t appear, ensure:
- group_permissions: true in the config.
- Permissions use dot notation (e.g., posts.create).
User Search Fields Customize user_search_fields in the config to include additional fields:
```
'user_search_fields' => ['name', 'email', 'username'],
```

Extension Points

Custom Modals Extend the ManagesEntity trait to create reusable modals for other entities:

use Beartropy\Permissions\Traits\ManagesEntity;

class CustomModal extends Component
{
    use ManagesEntity;

    // Override properties and methods as needed
}

Table Customization Override table queries or columns by extending the base tables:

class CustomPermissionsTable extends \Beartropy\Permissions\Livewire\PermissionsTable
{
    public function query()
    {
        return parent::query()->where('created_at', '>', now()->subDays(30));
    }
}

AI Integration Leverage the package’s MCP tools for AI-assisted documentation or component discovery:
```
php artisan beartropy:skills
```
This registers skills like bt-permissions-component for AI agents.

Pro Tips

Bulk Import Permissions Use a seeder to bulk-create permissions with groups:
```
$permissions =
```

Permissions Laravel Package