 |
VOOZH | about |
|
VOOZH | about |
This document explains how to define authorization rules in the hypervel/auth system using abilities and policies. Abilities are simple callback-based rules for authorizing actions, while policies are class-based collections of authorization logic organized around a specific model or resource type.
For information about the Gate class that evaluates these rules, see 3.1. For information about how to use authorization in your application (checking permissions, middleware, etc.), see 3.1, 3.4, and 4.2.
The Gate supports two complementary approaches to defining authorization logic:
| Approach | Use Case | Definition Method | Storage Location |
|---|---|---|---|
| Abilities | Simple, one-off authorization checks | Gate::define() | Closures or callbacks stored in $abilities array |
| Policies | Model-centric authorization with multiple related checks | Gate::policy() | Class instances resolved from $policies mapping |
Both approaches support the same authorization checking methods (allows(), denies(), check(), etc.) but differ in how the authorization logic is organized and resolved.
Sources: src/Access/Gate.php28-53
Abilities are named authorization rules defined as closures or callbacks. Each ability is registered with a unique name (e.g., "update-post", "view-dashboard") and associated with a callable that determines whether a user can perform that action.
The Gate stores abilities in two internal arrays:
$abilities - Contains the executable callbacks src/Access/Gate.php50$stringCallbacks - Contains string representations of class-based callbacks src/Access/Gate.php30The most straightforward way to define an ability is with a closure:
The first parameter is always the user (nullable for guest support), followed by any arguments passed during the authorization check.
Abilities can reference class methods using string notation:
String callbacks are converted to closures via buildAbilityCallback() src/Access/Gate.php164-194
The define() method handles multiple callback formats src/Access/Gate.php122-139:
[ClassName::class, 'method'] - Converted to 'ClassName@method'$abilities'ClassName@method' - Stored in $stringCallbacks and wrapped in a closureSources: src/Access/Gate.php122-139
The resource() method provides a convenient way to define standard CRUD abilities for a resource:
This single call is equivalent to defining five separate abilities src/Access/Gate.php144-159:
| Ability Name | Policy Method | Purpose |
|---|---|---|
post.viewAny | viewAny() | List all resources |
post.view | view() | View a single resource |
post.create | create() | Create a new resource |
post.update | update() | Update an existing resource |
post.delete | delete() | Delete a resource |
You can customize the ability-to-method mapping by passing a third parameter:
Sources: src/Access/Gate.php144-159
Policies are classes that organize authorization logic around a particular model or resource type. Instead of defining scattered abilities, you group related authorization rules into a single policy class.
For example, a PostPolicy might contain methods like view(), update(), delete(), each handling authorization for that specific action on Post models.
Policies are registered by mapping a model class to a policy class src/Access/Gate.php199-204:
The mapping is stored in the $policies array src/Access/Gate.php51:
Sources: src/Access/Gate.php199-204
When the Gate needs a policy instance, it resolves it from the DI container src/Access/Gate.php519-522:
This allows policies to have dependencies injected through their constructors.
The getPolicyFor() method determines which policy to use for a given object src/Access/Gate.php493-512:
Sources: src/Access/Gate.php493-522
Policy methods follow these conventions:
The first parameter is always the user. Additional parameters are the arguments passed to the authorization check.
The Gate converts ability names to method names using camel case src/Access/Gate.php599-602:
| Ability Name | Policy Method |
|---|---|
view | view() |
update-post | updatePost() |
delete-comment | deleteComment() |
Sources: src/Access/Gate.php599-602
Policies can define a special before() method that runs before any other policy method src/Access/Gate.php562-571:
Behavior:
before() returns non-null, that result is used and the specific method is skippedbefore() returns null, evaluation continues to the specific policy methodbefore() method receives the ability name as a parameterSources: src/Access/Gate.php562-571 src/Access/Gate.php537-549
When the Gate checks an ability, it follows this resolution order src/Access/Gate.php463-485:
Key Points:
Sources: src/Access/Gate.php463-485
When a policy is used, the Gate follows this execution flow src/Access/Gate.php533-554:
Sources: src/Access/Gate.php527-554 src/Access/Gate.php562-571
Both abilities and policies can support guest (unauthenticated) users by making the user parameter nullable. The Gate determines if a callback can be called with a null user through reflection src/Access/Gate.php338-398
The Gate uses reflection to determine if a callback allows guests src/Access/Gate.php394-398:
A parameter allows guests if:
?Authenticatable)nullIf a callback doesn't allow guests and the user is null, the callback is skipped src/Access/Gate.php418-420
Sources: src/Access/Gate.php338-398
| Aspect | Abilities | Policies |
|---|---|---|
| Organization | Flat, name-based | Model-centric classes |
| Best For | Simple, standalone checks | Related authorization rules for a model |
| Registration | Gate::define(name, callback) | Gate::policy(Model::class, Policy::class) |
| Resolution | By ability name | By object class + ability name |
| Before Hooks | Global before() callbacks | Per-policy before() methods |
| Dependency Injection | Not supported (closures) | Supported (resolved from container) |
| Code Reuse | Limited | High (methods in a class) |
Sources: src/Access/Gate.php122-139 src/Access/Gate.php199-204 src/Access/Gate.php463-485
String callbacks defined with Class@method syntax are wrapped in a special closure that handles policy resolution and before hooks src/Access/Gate.php164-194:
This allows string callbacks to benefit from:
before() methodSources: src/Access/Gate.php164-194
The Gate automatically transforms ability names to method names for policy resolution:
Examples:
| Ability | Transformation | Policy Method |
|---|---|---|
"view" | None | view() |
"update" | None | update() |
"view-any" | Camel case | viewAny() |
"create-draft" | Camel case | createDraft() |
"admin-delete" | Camel case | adminDelete() |
This transformation is performed by formatAbilityToMethod() src/Access/Gate.php599-602 and is applied when:
Sources: src/Access/Gate.php599-602 src/Access/Gate.php529 src/Access/Gate.php551
This diagram shows the complete flow when checking authorization with both abilities and policies in the system:
Key Decision Points:
Sources: src/Access/Gate.php303-333 src/Access/Gate.php411-426 src/Access/Gate.php463-485 src/Access/Gate.php527-554
Refresh this wiki