### Run tests and static analysis with Docker Compose

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Use these commands to start MongoDB and run Composer install, PHPUnit, and PHPStan inside a Docker container. Requires Docker Compose and no local PHP or Mongo installation.

```bash
docker compose up -d mongo
docker compose run --rm php composer install
docker compose run --rm php vendor/bin/phpunit
docker compose run --rm php vendor/bin/phpstan analyse --memory-limit=1G
```

--------------------------------

### Install package and publish config

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Install the package via Composer, publish the configuration file, and create indexes. Requires PHP 8.2+, Laravel 12.x/13.x, MongoDB server 7.x, and mongodb/laravel-mongodb ^5.0.

```bash
composer require webrek/laravel-mongo-permission
php artisan vendor:publish --tag=permission-config
php artisan permission:create-indexes
```

--------------------------------

### permission:check output trace example

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Example output from the permission:check command, showing a trace of why the answer is YES or NO. It includes direct grants, role-based grants, and wildcard checks.

```text
User 65f... has 'edit articles'?  YES
  ✓ direct grant: id=64a..., team_id=null
  ✓ via role 'editor' (id=64b..., team_id=null)
  ✗ wildcard 'posts.*' does not imply 'edit articles'
```

--------------------------------

### Quick start: create roles and permissions

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Shows how to set up a User model with the HasRoles trait, create a permission and role, assign the permission to the role, and assign the role to a user. The final check returns true.

```php
use Webrek\MongoPermission\Models\Permission;
use Webrek\MongoPermission\Models\Role;
use Webrek\MongoPermission\Traits\HasRoles;

class User extends Authenticatable {
    use HasRoles;
}

Permission::create(['name' => 'edit articles']);
$role = Role::create(['name' => 'editor']);
$role->givePermissionTo('edit articles');

$user->assignRole('editor');
$user->hasPermissionTo('edit articles'); // true
```

--------------------------------

### Create roles with inheritance using inheritsFrom

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Creates roles and sets up inheritance. A role inherits all permissions from its parent and ancestors. The example shows transitive inheritance: admin inherits from editor, which inherits from viewer, so admin gets view and edit permissions. hasDirectPermission returns false for transitive permissions.

```php
$viewer = Role::create(['name' => 'viewer']);
$viewer->givePermissionTo('view articles');

$editor = Role::create(['name' => 'editor']);
$editor->givePermissionTo('edit articles');
$editor->inheritsFrom($viewer);   // editor now grants view + edit

$admin = Role::create(['name' => 'admin']);
$admin->inheritsFrom($editor);    // admin now grants view + edit transitively

$user->assignRole('admin');
$user->hasPermissionTo('view articles');   // true
$user->hasDirectPermission('view articles'); // false (transitive)
```

--------------------------------

### Middleware for role and permission checks

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Shows how to protect routes using the 'role', 'permission', and 'role_or_permission' middleware, including a team-context example. Denied requests throw UnauthorizedException (HTTP 403).

```php
Route::get('/admin', ...)->middleware('role:admin');
Route::get('/edit',  ...)->middleware('permission:edit articles');
Route::get('/x',     ...)->middleware('role_or_permission:admin|edit articles');
Route::get('/teams/{team}/admin', ...)
    ->middleware(['team-context:team', 'role:admin']);
```

--------------------------------

### permission:list-users command usage examples

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Shows three ways to call the artisan command: with a role name, with a permission name, and with a team and guard. The command queries the user collection by role_ids.role_id or permission_ids.permission_id and outputs a table with id, name, email, team, and direct/via-role info.

```bash
php artisan permission:list-users admin
php artisan permission:list-users --permission="edit articles"
php artisan permission:list-users admin --team=acme --guard=api
```

--------------------------------

### Use MongoPermissionAssertions trait in a test case

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Include the MongoPermissionAssertions trait in your TestCase to use expressive assertions for user and role permissions. The example shows asserting a user has a role, a permission, a direct permission, and a role has a permission.

```php
use Webrek\MongoPermission\Testing\MongoPermissionAssertions;

class FooTest extends TestCase
{
    use MongoPermissionAssertions;

    public function test_admin_can_edit(): void
    {
        $this->assertUserHasRole($user, 'admin');
        $this->assertUserHasPermission($user, 'edit articles');
        $this->assertUserHasDirectPermission($user, 'publish');
        $this->assertRoleHasPermission($role, 'view');
    }
}
```

--------------------------------

### Artisan commands for permission management

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

List of Artisan commands to create indexes, roles, permissions, show permissions, reset cache, prune expired permissions, list users, check permissions, and migrate from Spatie. Each command includes relevant options and arguments.

```bash
php artisan permission:create-indexes
```

```bash
php artisan permission:create-role admin [--guard=web] [perm1 perm2 ...]
```

```bash
php artisan permission:create-permission "edit articles" [--guard=web]
```

```bash
php artisan permission:show [--guard=web] [--team=...]
```

```bash
php artisan permission:cache-reset
```

```bash
php artisan permission:prune-expired [--user-model=...] [--dry-run]
```

```bash
php artisan permission:list-users {role} [--permission=...] [--guard=...] [--team=...]
```

```bash
php artisan permission:check {user_id} {permission} [--guard=...] [--team=...]
```

```bash
php artisan permission:migrate-from-spatie [--connection=mysql] [--match-by=email] [--skip-users] [--force] [--dry-run]
```

--------------------------------

### composer.json keywords and support URLs

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Adds keywords and support URLs to composer.json to improve Packagist search visibility. Takes about 10 minutes.

```json
{
  "keywords": ["laravel", "mongodb", "permissions", "roles", "rbac",
               "acl", "authorization", "multi-tenant", "wildcard"],
  "support": {
    "issues": "https://github.com/webrek/laravel-mongo-permission/issues",
    "source": "https://github.com/webrek/laravel-mongo-permission"
  }
}
```

--------------------------------

### Run permission:migrate-from-spatie with various options

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Use these Artisan commands to migrate from spatie/laravel-permission. The --dry-run flag previews changes, --skip-users omits user assignments, and --force overwrites existing Mongo roles/permissions with the same (name, guard, team). The command reads spatie tables and matches SQL users to Mongo users by email by default.

```bash
# Dry-run against your "spatie" SQL connection
php artisan permission:migrate-from-spatie --connection=spatie --dry-run

# Real run, matching SQL users to Mongo users by email
php artisan permission:migrate-from-spatie --connection=spatie

# Roles and permissions only, no user assignments
php artisan permission:migrate-from-spatie --connection=spatie --skip-users

# Overwrite Mongo roles/permissions that already exist with the same (name, guard, team)
php artisan permission:migrate-from-spatie --connection=spatie --force
```

--------------------------------

### Role hierarchy API sketch

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Shows the proposed API for role inheritance: editor inherits from viewer, admin inherits from editor, and getAllPermissions walks the inheritance graph.

```php
$editor->inheritsFrom($viewer);     // editor gets viewer's perms
$admin->inheritsFrom($editor);      // and transitively viewer's
$admin->getAllPermissions();        // walks the inheritance graph
```

--------------------------------

### Reading relations: user, role, and permission methods

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Shows how to access forward and inverse relations as collections. Methods return plain collections (not query builders) and are resolved on call; use them in views and reports, not in tight loops.

```php
// On the user (via the HasRoles / HasPermissions traits)
$user->roles();          // Collection<Role>
$user->permissions();    // Collection<Permission> direct grants

// On a role
$role->permissions();    // Collection<Permission>
$role->users();          // users holding the role
                         // (matches both flat ["id"] and structured role_ids)

// On a permission
$permission->roles();    // Collection<Role> that grant it
```

--------------------------------

### Suggested release sequence

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Shows the planned versioning and feature mapping for the package, indicating which features land in each minor version.

```text
v1.1  →  A1 (TTL) + B1 + B2 + B3
v1.2  →  A2 (Hierarchy) + C1 + C2 + D1 + D2
v1.3  →  A3 (Spatie migration)
v1.4+ →  E1 (Filament) as separate repo
```

--------------------------------

### permission:check command usage

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Shows the artisan command syntax for checking a user's permission. It accepts a user ID and permission name, with an optional guard flag.

```bash
php artisan permission:check {user_id} {permission} [--guard=]
```

--------------------------------

### Wildcard permission creation and checks

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Creates a wildcard permission 'posts.*' and grants it to a user. The trailing '*' matches all remaining segments, so hasPermissionTo('posts.edit') and hasPermissionTo('posts.edit.own') both return true.

```php
Permission::create(['name' => 'posts.*']);
$user->givePermissionTo('posts.*');
$user->hasPermissionTo('posts.edit');         // true
$user->hasPermissionTo('posts.edit.own');     // true
```

--------------------------------

### Migration command shape

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Artisan command to migrate from spatie/laravel-permission to Mongo. Includes connection, user model, user mongo collection, and dry-run options.

```bash
php artisan permission:migrate-from-spatie \
    --connection=mysql \
    --user-model="App\\Models\\User" \
    --user-mongo-collection=users \
    --dry-run
```

--------------------------------

### Prune expired grants with permission:prune-expired artisan command

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Runs the prune command to garbage-collect expired grants. Use --dry-run to preview without deleting, and --user-model to target a specific user model. Expired subdocs are not removed automatically, so run this on a schedule or ad-hoc.

```bash
php artisan permission:prune-expired
php artisan permission:prune-expired --dry-run
php artisan permission:prune-expired --user-model="App\\Models\\User"
```

--------------------------------

### Assign roles and permissions with expiration

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Shows the proposed API for assigning roles and permissions with an expiration time. The `hasRole` check returns false once the TTL has passed.

```php
$user->assignRole('admin', expiresAt: now()->addHours(2));
$user->givePermissionTo('publish posts', expiresAt: now()->addDays(7));
$user->hasRole('admin'); // false once the TTL has passed
```

--------------------------------

### Assign expiring role and permission with assignRoleUntil and givePermissionToUntil

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Assigns a role and a permission with an expiry timestamp. The grant remains on the user document but stops counting toward checks once the expiry passes, even if the cache was warmed before. After the expiry, hasRole and hasPermissionTo return false.

```php
$user->assignRoleUntil('admin', now()->addHours(2));
$user->givePermissionToUntil('publish posts', now()->addDays(7));

$user->hasRole('admin');                  // true for two hours
$user->hasPermissionTo('publish posts');  // true for seven days

// After the expiry passes:
$user->hasRole('admin');                  // false
```

--------------------------------

### Configure team resolver closure

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Set the team resolver closure in config/permission.php to automatically determine the active team ID. The closure returns the current team ID from the authenticated user or a header.

```php
'team_resolver' => fn () =>
    request()->user()?->current_team_id
    ?? request()->header('X-Team-Id'),
```

--------------------------------

### Flush permission cache manually

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Run this artisan command to manually reset the permission cache. Useful when you need to flush immediately without waiting for automatic invalidation.

```bash
php artisan permission:cache-reset
```

--------------------------------

### Blade directives for roles and permissions

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/README.md

Blade directives for checking roles and permissions, including native @can which is routed through Gate::before.

```blade
@role('admin') ... @endrole
@hasanyrole('admin|editor') ... @endhasanyrole
@hasallroles('admin|editor') ... @endhasallroles
@unlessrole('guest') ... @endunlessrole

@permission('edit articles') ... @endpermission
@haspermission('edit articles') ... @endhaspermission
@hasanypermission('edit|delete') ... @endhasanypermission

@can('edit articles') ... @endcan   {{-- native Laravel, routed via Gate::before --}}
```

--------------------------------

### Schema change for expiring grants

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Proposed schema for subdocuments embedded in `users.role_ids` and `users.permission_ids`, adding an `expires_at` field.

```javascript
{ role_id: ObjectId, team_id: ObjectId|null, expires_at: ISODate|null }
```

--------------------------------

### MongoPermissionAssertions trait

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Defines a trait with assertion methods for testing roles and permissions. Consumers use the trait in their TestCase for ergonomic wrappers around the trait methods.

```php
trait MongoPermissionAssertions
{
    public function assertUserHasRole($user, string $role, ?string $guard = null): void;
    public function assertUserDoesNotHaveRole($user, string $role): void;
    public function assertUserHasPermission($user, string $perm): void;
    public function assertUserHasDirectPermission($user, string $perm): void;
    public function assertRoleHasPermission($role, string $perm): void;
}
```

--------------------------------

### PHPStan level 6 CI job

Source: https://github.com/webrek/laravel-mongo-permission/blob/main/docs/roadmap.md

Adds a PHPStan analysis job to the GitHub Actions workflow, running on PHP 8.3 with the mongodb extension. Level 6 catches missing type hints without false positives of higher levels.

```yaml
analyse:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v5
    - uses: shivammathur/setup-php@v2
      with: { php-version: '8.3', extensions: mongodb }
    - run: composer install --no-progress
    - run: vendor/bin/phpstan analyse --no-progress
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.