Laravel Governor Laravel Package

Getting Started

• composer require genealabs/laravel-governor — pin ^0.22 if you're on Laravel 13 (see Gotchas), otherwise ^0.21 is fine on older frameworks.
• Run the setup command (php artisan governor:setup): it publishes config/governor.php, the migrations, and seeds the default roles (SuperAdmin/Admin/Member) plus permission records for the models it discovers.
• Add the HasRoles trait to your App\Models\User (and any other authenticatable model that needs its own role set).
• Look first at: config/governor.php (super-admin role name, entity discovery, UI route), the governor_roles / governor_permissions / pivot tables, and the bundled Governor admin screen.
• First use case: stop hand-rolling is_admin columns. Create a Post, hit $user->can('update', $post) in a controller — Governor's generated policies answer through role→entity permissions, and you flip the answer in the UI instead of in code.

Implementation Patterns

• Authorize through Gate, not through Governor directly. The package's value is that it plugs into Laravel's native policy/Gate pipeline, so @can, $this->authorize(), Gate::allows() and Blade directives all work unchanged. Treat the package as a permissions store, not an authorization API to call from your controllers.
• Ownership scoping. Permissions are granted per entity with an "own vs any" distinction, which is where most real-world value lives — "Members may update their own posts, Admins any." Verify ownership resolution on models with non-standard foreign keys (author_id, polymorphic owners) before trusting it.
• Role assignment as admin workflow. Roles are managed through the UI or by attaching through the roles relation in seeders/console commands. For provisioning (tenant onboarding, first admin), write an idempotent seeder that creates roles and attaches them rather than clicking through the UI per environment.
• Model discovery is the integration point. New Eloquent model → run the discovery/sync step (or re-run setup) so permission rows exist. A php artisan migrate in CI does not create them by itself. Consider a deploy step or a data migration that creates permissions for entities added in a release.
• Testing. Build a small helper: actingAs($this->admin) vs actingAs($this->member) against the same feature test. Seed the roles you need in TestCase::setUp — don't rely on the package's seeded defaults surviving a RefreshDatabase.
• Custom policies still win. If a resource has logic Governor can't express (state machines, team scoping), write a normal policy and let it take precedence; use Governor for the coarse CRUD layer only.

Gotchas and Tips

• Laravel 13 support only arrived in 0.22.0. If you're upgrading the framework, bump the package in the same PR — otherwise Composer will hold you back on laravel/framework and the failure looks like a framework problem, not a package constraint. Conversely, 0.22.0 has no reason to break L10/L11 consumers, but it's a 0.x package: pin the minor and read each changelog. Minor bumps here have historically carried behaviour changes.
• Silent 403s after adding a model are the #1 support ticket. Permission rows are per-entity, not per-instance; no row = denied. Check the governor_permissions table before debugging your policy.
• Role caching. Permissions/roles are commonly cached per request or per user; after changing a role in the UI or seeder, clear the cache (php artisan cache:clear, or the package's own cache key) before concluding it "didn't work."
• SuperAdmin bypass is name-based. Renaming that role in config or in the DB silently removes the bypass — and the person doing it is usually the only one who could fix it. Keep the name stable, and make sure at least one SuperAdmin exists in every environment, including staging and prod.
• The admin UI is a privilege-escalation surface. Restrict its middleware/route group in config/governor.php, or disable it in production entirely and manage roles via console/seeders.
• Don't run it alongside another ACL package (Spatie Permission, Bouncer). Both want roles-style relations and Gate hooks; conflicts show up as confusing "permission granted by one, denied by the other" behaviour.
• Migrations before users. Published migrations are timestamped at publish time — run them before seeding application users, or role attachment fails on a missing pivot table.
• Debugging path: php artisan route:list | grep -i governor → inspect the governor_* tables directly → Gate::forUser($u)->inspect('update', $post) to see which policy/ability actually answered. inspect() tells you far more than the boolean can().