Bastion Laravel Package

Getting Started

Bastion is a Filament-oriented permissions/access package: it syncs Filament resources/pages into permissions and lets you assign them through roles. v4.1.0 is a major-version release focused on Filament v4 compatibility and panel-aware syncing.

1. Install and publish:

   composer require chrisreedio/bastion
   php artisan vendor:publish --tag="bastion-config"
   php artisan vendor:publish --tag="bastion-migrations"
   php artisan migrate
   

2. Look first at:
   • config/bastion.php for guard, permission model, resource discovery, and panel settings.
   • The package README/upgrade guide for v3 → v4 changes.
   • BastionSyncCommand signature to confirm the exact panel argument syntax.
   • Your Filament panel provider for plugin/resource registration.
3. Register Bastion with your Filament panel(s) as documented, then run the sync:

   php artisan bastion:sync
   

   In v4.1.0 the sync command accepts an optional panel argument, so multi-panel apps can sync one panel at a time:

   php artisan bastion:sync admin
   

4. First use case: run the sync, assign generated permissions to a role, attach that role to a user, and verify access to a Filament resource. For nested/parent resources, test both parent and child access because v4.1 adds Filament v4 parent-resource compatibility.

Implementation Patterns

• Deploy-time sync: Run php artisan bastion:sync after migrations and after deploying resource changes. In multi-panel apps, run it once per panel with the new panel argument rather than relying on a global sync.
• Role seeding: Create baseline roles (e.g. super admin, editor) in seeders, then attach synced permissions. Do not depend on sync alone to create business roles.
• Panel isolation: Use the panel argument when panels have different resources or permission namespaces. This avoids syncing permissions for panels that are not deployed in a given context.
• Nested resources: After adding or renaming Filament parent/child resources, rerun sync and verify permissions for both levels. v4.1 handles Filament v4 parent resource checks, so nested resource access should be tested explicitly.
• Policy integration: Use Laravel gates/policies for fine-grained checks and let Bastion manage the Filament resource-level permissions. Keep authorization rules in policies when access depends on record ownership or state.
• CI/CD checks: Add a staging step that runs sync and asserts expected permission counts/names. This catches resource slug changes, renamed pages, or panel configuration drift before production.
• Scheduling: If resources change frequently in lower environments, schedule sync there; in production, prefer deployment-triggered sync so permission changes are auditable.
• Extension points: Prefer config-driven permission naming and resource discovery over patching vendor code. If you need custom behavior, bind your own implementation through the package’s config/service provider where supported.

Gotchas and Tips

• Major upgrade risk: v4.1.0 follows v3.0.1 and explicitly targets Filament v4. Treat it as a breaking upgrade. Do not install it in a Filament v3 app without checking the upgrade guide and testing panel/resource registration.
• Sync may prune permissions: Before the first production sync, confirm whether removed resources cause stale permissions to be deleted. Back up roles/permission assignments and test in staging.
• Panel argument syntax: The release adds an optional panel argument, but confirm whether it is positional (bastion:sync admin) or an option (--panel=admin) by inspecting BastionSyncCommand. Use the exact signature in scripts.
• Cache clearing: After sync, clear permission and Filament caches:

  php artisan permission:cache-reset
  php artisan optimize:clear
  

  If you use another permission backend, clear its cache explicitly.
• Nested resource edge cases: Parent-resource compatibility depends on Filament resource registration. Custom slugs, hidden resources, or resources without navigation registration may not sync as expected. Verify generated permission names.
• Multi-panel drift: Running sync without a panel may process all panels. If panels share resource classes but need different permissions, use the panel argument and confirm namespace behavior.
• Deployment ordering: Run migrations before sync, and sync before warming caches. Avoid running sync concurrently in multiple deploy workers; use a deploy hook or lock.
• Debugging: Inspect the permissions table and run the sync verbosely if supported (-v). Compare generated permission names to Filament resource/page slugs. If access fails, check guard names, role assignment, and policy/gate resolution before assuming sync failed.
• GitHub Action bumps: The Dependabot updates in this release are maintenance-only and do not affect application behavior.