Grant Laravel Package

Getting Started

shipfastlabs/grant is a pre-1.0 authorization package, so treat the first hour as an API discovery exercise rather than a copy-paste install.

1. Install and publish:

   composer require shipfastlabs/grant
   php artisan vendor:publish --tag="grant-config"
   php artisan vendor:publish --tag="grant-migrations"
   php artisan migrate
   

2. Read the published config/grant.php first — v0.0.1 adds config validation, so this file is now actively parsed and validated at boot. Anything you leave as env()-driven is checked early; a bad value fails loudly on artisan boot rather than silently at runtime.
3. Attach the package trait to your User (or any authenticatable) model, and confirm whether permissions are resolved against a cache store or the database.
4. First use case: seed a small role/permission set, assign a role to a test user, then guard a single route with the package's middleware or a Gate::allows() check in a controller. Verify with php artisan tinker before wiring it into policies.

Where to look first when something misbehaves: the published config, then the package's migration (it defines the pivot/assignment tables and tells you whether writes are model-backed), then the service provider's Gate registrations.

Implementation Patterns

Gate integration over custom checks. The package registers abilities on Laravel's Gate. Prefer $this->authorize('permission-name') in controllers and Gate::allows() in policies over calling package APIs directly — it keeps you swappable and makes Gate::fake()/Gate::before() work in tests.

Model-backed writes. Assignments are persisted through Eloquent models rather than raw cache mutations. Do role/permission changes inside transactions alongside the domain change they belong to (e.g. upgrading a plan and granting the entitlement in one DB::transaction), so a rollback doesn't leave a stale grant behind.

Queue workers and long-running processes. v0.0.1 fixes a stale Gate memo in workers. The pattern that stays safe: any job that mutates a user's roles/permissions should clear the resolved-ability cache before the next authorization check in that same worker, and jobs that assume a permission should re-check rather than capture the result at dispatch time. For Octane, do the same in a request-terminating or middleware hook if your config caches per-request.

Middleware for coarse gates, policies for fine ones. Use route middleware for "can this user reach this section at all", and policies for per-record checks. Mixing them (policy checks inside middleware) tends to double-resolve and mask which layer denied the request.

Testing. Because abilities live on Gate, standard Laravel tooling applies: Gate::fake() for unit tests, $this->actingAs($user) plus assertForbidden for feature tests. For the package's own tables, keep a factory-based seeder so tests don't depend on production role names.

Gotchas and Tips

• Pre-1.0 churn. v0.0.1 is the first tagged release and includes audit-driven fixes to caching and write paths. Pin the version ("shipfastlabs/grant": "0.0.1") and read the diff before bumping; assume minor releases may change behavior until 1.0.
• Config validation is strict now. A previously "working" config with a null or malformed value will throw at boot. If a deploy fails immediately after upgrading, this is the first place to look — check config/grant.php against any env vars added or renamed.
• Stale permissions in workers. The v0.0.1 fix closes the common case, but any custom caching layer you add on top (a repository decorator, a memoized array on a singleton) reintroduces the same bug. Keep authorization resolution stateless per job.
• Cache store choice matters. If abilities are cached, a file or array store in tests versus redis in production can produce "works locally, denied in prod" reports. Assert the store explicitly in your test bootstrap.
• Parallel test isolation. PR #2 fixed flaky CI by isolating published files per test process. If you run Pest/PHPUnit with --parallel and publish the package's config or migrations in a test bootstrap, do the same — publish into a per-process temp path or keep the publish step out of the test suite entirely.
• Extension points. The service provider's Gate registration and the ability-name convention are your hooks: map package permission strings to your own domain language in one place rather than sprinkling string literals across policies. When the package's naming changes pre-1.0, that single adapter is the only edit.
• Debugging denials. Log the ability name and the resolved user ID at the point of denial (a Gate::after callback is enough) during rollout — permission packages fail closed, and a missing seed row looks identical to a wrong policy.