Skip to content

Commit 3a0cfc7

Browse files
Emre Akayclaude
Emre Akay
and
claude
committed
fix: correct 3 documentation inaccuracies against source code
- Remove fictitious Policies section (src/Policies/ doesn't exist, Gate::policy() removed) - Replace with Gate::before integration docs reflecting actual service provider code - Add missing ?OrganizationNode $organizationNode property to RoleSwitchedEvent docs - Fix allWithoutAAuthOrganizationNodeScope() to show as instance method, not static Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 325bc9a commit 3a0cfc7

File tree

3 files changed

+80
-119
lines changed

3 files changed

+80
-119
lines changed

‎.ai/guidelines/core.blade.php‎

Lines changed: 30 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
- **ABAC**: Model-level attribute filtering with JSON rules applied via global scopes
1010
- **Automatic Data Filtering**: Global scopes filter data based on user's authorized organization nodes
1111
- **Middleware**: Route-level permission, role, and organization scope protection
12-
- **Policies**: Laravel Gate integration with OrganizationNode and Role policies
12+
- **Gate Integration**: `Gate::before` callback for Laravel authorization integration
1313
- **Cache**: Configurable caching with automatic invalidation via observers
1414
- **Super Admin**: Bypass all permission checks with configurable column
1515
- **Events**: Lifecycle events for roles and permissions
@@ -512,8 +512,8 @@ public static function getABACRules(): array
512512
// Access the related organization node
513513
$orgNode = $school->relatedAAuthOrganizationNode();
514514

515-
// Get all records without organization scope filtering
516-
$all = School::allWithoutAAuthOrganizationNodeScope();
515+
// Get all records without organization scope filtering (instance method)
516+
$all = (new School)->allWithoutAAuthOrganizationNodeScope();
517517
</code-snippet>
518518
@endverbatim
519519

@@ -567,64 +567,47 @@ public static function getABACRules(): array
567567
</code-snippet>
568568
@endverbatim
569569

570-
### Policies
570+
### Laravel Gate Integration
571571

572-
AAuth registers Laravel Gate policies for `OrganizationNode` and `Role` models via `Gate::policy()` in the service provider. A `Gate::before` callback also integrates AAuth with Laravel's built-in authorization and checks super admin status.
573-
574-
**OrganizationNodePolicy** (`src/Policies/OrganizationNodePolicy.php`):
572+
AAuth integrates with Laravel's built-in authorization via a `Gate::before` callback registered in the service provider:
575573

576574
@verbatim
577-
<code-snippet name="OrganizationNodePolicy" lang="php">
578-
// viewAny: requires 'view_organization_nodes' permission
579-
// view: requires 'view_organization_nodes' + verifies node is accessible via AAuth::organizationNode($id)
580-
// create: requires 'create_organization_nodes' permission
581-
// update: requires 'update_organization_nodes' + verifies node accessibility
582-
// delete: requires 'delete_organization_nodes' + verifies node accessibility
583-
584-
// Usage with Laravel Gate:
585-
Gate::allows('viewAny', OrganizationNode::class);
586-
Gate::allows('view', $organizationNode);
587-
Gate::allows('update', $organizationNode);
588-
</code-snippet>
589-
@endverbatim
575+
<code-snippet name="Gate::before Integration" lang="php">
576+
// Registered in AAuthServiceProvider::boot()
577+
Gate::before(function ($user, $ability, $arguments = []) {
578+
$aauth = app('aauth');
579+
580+
// Super admin bypasses all permission checks
581+
if ($aauth->isSuperAdmin()) {
582+
return true;
583+
}
590584

591-
**RolePolicy** (`src/Policies/RolePolicy.php`):
585+
// Delegate to AAuth::can() for all Gate checks
586+
return $aauth->can($ability, ...$arguments) ?: null;
587+
});
592588

593-
@verbatim
594-
<code-snippet name="RolePolicy" lang="php">
595-
// viewAny: requires 'view_roles' permission
596-
// view: requires 'view_roles' + for organization roles, checks scope access
597-
// create: requires 'create_roles' permission
598-
// update: requires 'update_roles' + for organization roles, checks scope access
599-
// delete: requires 'delete_roles' + checks $role->deletable + for org roles, checks scope access
600-
601-
// Organization role scope check: iterates user's organization nodes
602-
// and verifies at least one node matches the role's organization_scope_id.
603-
// System roles always pass the scope check.
604-
605-
// Usage with Laravel Gate:
606-
Gate::allows('update', $role);
607-
Gate::allows('delete', $role); // also checks deletable attribute
589+
// This means standard Laravel Gate/Policy checks work with AAuth:
590+
Gate::allows('edit_something');
591+
$user->can('edit_something');
592+
@can('edit_something') ... @endcan
608593
</code-snippet>
609594
@endverbatim
610595

611-
**Gate::before callback**: The service provider registers a `Gate::before` that checks `isSuperAdmin()` (bypasses all checks if true) and then delegates to `AAuth::can()` for all Gate checks.
612-
613596
### Events
614597

615598
AAuth dispatches events for role and permission lifecycle:
616599

617600
@verbatim
618601
<code-snippet name="Available Events" lang="php">
619-
use AuroraWebSoftware\AAuth\Events\RoleCreatedEvent;
620-
use AuroraWebSoftware\AAuth\Events\RoleUpdatedEvent;
621-
use AuroraWebSoftware\AAuth\Events\RoleDeletedEvent;
622-
use AuroraWebSoftware\AAuth\Events\RoleAssignedEvent;
623-
use AuroraWebSoftware\AAuth\Events\RoleRemovedEvent;
624-
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent;
625-
use AuroraWebSoftware\AAuth\Events\PermissionAddedEvent;
626-
use AuroraWebSoftware\AAuth\Events\PermissionUpdatedEvent;
627-
use AuroraWebSoftware\AAuth\Events\PermissionRemovedEvent;
602+
use AuroraWebSoftware\AAuth\Events\RoleCreatedEvent; // Role $role
603+
use AuroraWebSoftware\AAuth\Events\RoleUpdatedEvent; // Role $role
604+
use AuroraWebSoftware\AAuth\Events\RoleDeletedEvent; // Role $role
605+
use AuroraWebSoftware\AAuth\Events\RoleAssignedEvent; // int $userId, Role $role, ?OrganizationNode $organizationNode
606+
use AuroraWebSoftware\AAuth\Events\RoleRemovedEvent; // int $userId, Role $role, ?OrganizationNode $organizationNode
607+
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent; // int $userId, Role $newRole, ?Role $oldRole, ?OrganizationNode $organizationNode
608+
use AuroraWebSoftware\AAuth\Events\PermissionAddedEvent; // Role $role, string $permission, ?array $parameters
609+
use AuroraWebSoftware\AAuth\Events\PermissionUpdatedEvent; // Role $role, string $permission, ?array $parameters, ?array $oldParameters
610+
use AuroraWebSoftware\AAuth\Events\PermissionRemovedEvent; // Role $role, string $permission
628611

629612
// Listen to events in your EventServiceProvider or listener classes
630613
</code-snippet>

‎README.md‎

Lines changed: 20 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1138,35 +1138,30 @@ aauth_is_super_admin(); // bool
11381138

11391139
---
11401140

1141-
## Policies
1141+
## Laravel Gate Integration
11421142

1143-
AAuth registers Laravel Gate policies for `OrganizationNode` and `Role` models.
1143+
AAuth integrates with Laravel's built-in authorization via a `Gate::before` callback registered in `AAuthServiceProvider`:
11441144

1145-
### OrganizationNodePolicy
1146-
1147-
| Method | Permission | Additional Check |
1148-
|--------|-----------|-----------------|
1149-
| viewAny | `view_organization_nodes` | - |
1150-
| view | `view_organization_nodes` | Node accessibility check |
1151-
| create | `create_organization_nodes` | - |
1152-
| update | `update_organization_nodes` | Node accessibility check |
1153-
| delete | `delete_organization_nodes` | Node accessibility check |
1154-
1155-
### RolePolicy
1145+
```php
1146+
// Super admin bypasses all permission checks
1147+
// All other Gate checks are delegated to AAuth::can()
1148+
Gate::before(function ($user, $ability, $arguments = []) {
1149+
$aauth = app('aauth');
11561150

1157-
| Method | Permission | Additional Check |
1158-
|--------|-----------|-----------------|
1159-
| viewAny | `view_roles` | - |
1160-
| view | `view_roles` | Scope access check for org roles |
1161-
| create | `create_roles` | - |
1162-
| update | `update_roles` | Scope access check for org roles |
1163-
| delete | `delete_roles` | Deletable + scope access check |
1151+
if ($aauth->isSuperAdmin()) {
1152+
return true;
1153+
}
11641154

1165-
### Gate::before Integration
1155+
return $aauth->can($ability, ...$arguments) ?: null;
1156+
});
1157+
```
11661158

1167-
AAuth registers a `Gate::before` callback that:
1168-
1. Checks if user is super admin (bypasses all checks)
1169-
2. Delegates to `AAuth::can()` for all Gate checks
1159+
This means standard Laravel authorization works with AAuth:
1160+
```php
1161+
Gate::allows('edit_something');
1162+
$user->can('edit_something');
1163+
@can('edit_something') ... @endcan
1164+
```
11701165

11711166
---
11721167

@@ -1223,7 +1218,7 @@ use AuroraWebSoftware\AAuth\Events\RoleUpdatedEvent; // Properties: Role $rol
12231218
use AuroraWebSoftware\AAuth\Events\RoleDeletedEvent; // Properties: Role $role
12241219
use AuroraWebSoftware\AAuth\Events\RoleAssignedEvent; // Properties: int $userId, Role $role, ?OrganizationNode
12251220
use AuroraWebSoftware\AAuth\Events\RoleRemovedEvent; // Properties: int $userId, Role $role, ?OrganizationNode
1226-
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent; // Properties: int $userId, Role $newRole, ?Role $oldRole
1221+
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent; // Properties: int $userId, Role $newRole, ?Role $oldRole, ?OrganizationNode $organizationNode
12271222
use AuroraWebSoftware\AAuth\Events\PermissionAddedEvent; // Properties: Role $role, string $permission, ?array $parameters
12281223
use AuroraWebSoftware\AAuth\Events\PermissionUpdatedEvent; // Properties: Role $role, string $permission, ?array $parameters, ?array $oldParameters
12291224
use AuroraWebSoftware\AAuth\Events\PermissionRemovedEvent; // Properties: Role $role, string $permission

‎resources/boost/guidelines/core.blade.php‎

Lines changed: 30 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
- **ABAC**: Model-level attribute filtering with JSON rules applied via global scopes
1010
- **Automatic Data Filtering**: Global scopes filter data based on user's authorized organization nodes
1111
- **Middleware**: Route-level permission, role, and organization scope protection
12-
- **Policies**: Laravel Gate integration with OrganizationNode and Role policies
12+
- **Gate Integration**: `Gate::before` callback for Laravel authorization integration
1313
- **Cache**: Configurable caching with automatic invalidation via observers
1414
- **Super Admin**: Bypass all permission checks with configurable column
1515
- **Events**: Lifecycle events for roles and permissions
@@ -512,8 +512,8 @@ public static function getABACRules(): array
512512
// Access the related organization node
513513
$orgNode = $school->relatedAAuthOrganizationNode();
514514

515-
// Get all records without organization scope filtering
516-
$all = School::allWithoutAAuthOrganizationNodeScope();
515+
// Get all records without organization scope filtering (instance method)
516+
$all = (new School)->allWithoutAAuthOrganizationNodeScope();
517517
</code-snippet>
518518
@endverbatim
519519

@@ -567,64 +567,47 @@ public static function getABACRules(): array
567567
</code-snippet>
568568
@endverbatim
569569

570-
### Policies
570+
### Laravel Gate Integration
571571

572-
AAuth registers Laravel Gate policies for `OrganizationNode` and `Role` models via `Gate::policy()` in the service provider. A `Gate::before` callback also integrates AAuth with Laravel's built-in authorization and checks super admin status.
573-
574-
**OrganizationNodePolicy** (`src/Policies/OrganizationNodePolicy.php`):
572+
AAuth integrates with Laravel's built-in authorization via a `Gate::before` callback registered in the service provider:
575573

576574
@verbatim
577-
<code-snippet name="OrganizationNodePolicy" lang="php">
578-
// viewAny: requires 'view_organization_nodes' permission
579-
// view: requires 'view_organization_nodes' + verifies node is accessible via AAuth::organizationNode($id)
580-
// create: requires 'create_organization_nodes' permission
581-
// update: requires 'update_organization_nodes' + verifies node accessibility
582-
// delete: requires 'delete_organization_nodes' + verifies node accessibility
583-
584-
// Usage with Laravel Gate:
585-
Gate::allows('viewAny', OrganizationNode::class);
586-
Gate::allows('view', $organizationNode);
587-
Gate::allows('update', $organizationNode);
588-
</code-snippet>
589-
@endverbatim
575+
<code-snippet name="Gate::before Integration" lang="php">
576+
// Registered in AAuthServiceProvider::boot()
577+
Gate::before(function ($user, $ability, $arguments = []) {
578+
$aauth = app('aauth');
579+
580+
// Super admin bypasses all permission checks
581+
if ($aauth->isSuperAdmin()) {
582+
return true;
583+
}
590584

591-
**RolePolicy** (`src/Policies/RolePolicy.php`):
585+
// Delegate to AAuth::can() for all Gate checks
586+
return $aauth->can($ability, ...$arguments) ?: null;
587+
});
592588

593-
@verbatim
594-
<code-snippet name="RolePolicy" lang="php">
595-
// viewAny: requires 'view_roles' permission
596-
// view: requires 'view_roles' + for organization roles, checks scope access
597-
// create: requires 'create_roles' permission
598-
// update: requires 'update_roles' + for organization roles, checks scope access
599-
// delete: requires 'delete_roles' + checks $role->deletable + for org roles, checks scope access
600-
601-
// Organization role scope check: iterates user's organization nodes
602-
// and verifies at least one node matches the role's organization_scope_id.
603-
// System roles always pass the scope check.
604-
605-
// Usage with Laravel Gate:
606-
Gate::allows('update', $role);
607-
Gate::allows('delete', $role); // also checks deletable attribute
589+
// This means standard Laravel Gate/Policy checks work with AAuth:
590+
Gate::allows('edit_something');
591+
$user->can('edit_something');
592+
@can('edit_something') ... @endcan
608593
</code-snippet>
609594
@endverbatim
610595

611-
**Gate::before callback**: The service provider registers a `Gate::before` that checks `isSuperAdmin()` (bypasses all checks if true) and then delegates to `AAuth::can()` for all Gate checks.
612-
613596
### Events
614597

615598
AAuth dispatches events for role and permission lifecycle:
616599

617600
@verbatim
618601
<code-snippet name="Available Events" lang="php">
619-
use AuroraWebSoftware\AAuth\Events\RoleCreatedEvent;
620-
use AuroraWebSoftware\AAuth\Events\RoleUpdatedEvent;
621-
use AuroraWebSoftware\AAuth\Events\RoleDeletedEvent;
622-
use AuroraWebSoftware\AAuth\Events\RoleAssignedEvent;
623-
use AuroraWebSoftware\AAuth\Events\RoleRemovedEvent;
624-
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent;
625-
use AuroraWebSoftware\AAuth\Events\PermissionAddedEvent;
626-
use AuroraWebSoftware\AAuth\Events\PermissionUpdatedEvent;
627-
use AuroraWebSoftware\AAuth\Events\PermissionRemovedEvent;
602+
use AuroraWebSoftware\AAuth\Events\RoleCreatedEvent; // Role $role
603+
use AuroraWebSoftware\AAuth\Events\RoleUpdatedEvent; // Role $role
604+
use AuroraWebSoftware\AAuth\Events\RoleDeletedEvent; // Role $role
605+
use AuroraWebSoftware\AAuth\Events\RoleAssignedEvent; // int $userId, Role $role, ?OrganizationNode $organizationNode
606+
use AuroraWebSoftware\AAuth\Events\RoleRemovedEvent; // int $userId, Role $role, ?OrganizationNode $organizationNode
607+
use AuroraWebSoftware\AAuth\Events\RoleSwitchedEvent; // int $userId, Role $newRole, ?Role $oldRole, ?OrganizationNode $organizationNode
608+
use AuroraWebSoftware\AAuth\Events\PermissionAddedEvent; // Role $role, string $permission, ?array $parameters
609+
use AuroraWebSoftware\AAuth\Events\PermissionUpdatedEvent; // Role $role, string $permission, ?array $parameters, ?array $oldParameters
610+
use AuroraWebSoftware\AAuth\Events\PermissionRemovedEvent; // Role $role, string $permission
628611

629612
// Listen to events in your EventServiceProvider or listener classes
630613
</code-snippet>

0 commit comments

Comments
 (0)