PHPackages                             glueful/aegis - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. glueful/aegis

ActiveGlueful-extension[Authentication & Authorization](/categories/authentication)

glueful/aegis
=============

Aegis: Role-Based Access Control extension for Glueful

v1.13.1(1w ago)1202[1 PRs](https://github.com/glueful/aegis/pulls)1MITPHPPHP ^8.3

Since Sep 14Pushed 2w agoCompare

[ Source](https://github.com/glueful/aegis)[ Packagist](https://packagist.org/packages/glueful/aegis)[ Docs](https://github.com/glueful/aegis)[ RSS](/packages/glueful-aegis/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (6)Versions (26)Used By (1)

Aegis (RBAC) Extension for Glueful
==================================

[](#aegis-rbac-extension-for-glueful)

Overview
--------

[](#overview)

Aegis provides a comprehensive, modern Role-Based Access Control (RBAC) system for your Glueful application. It implements hierarchical roles, direct user permissions, resource-level filters, and optional audit logging.

Features
--------

[](#features)

- **Hierarchical roles**: Create nested roles where child roles inherit ancestor permissions
- **Direct user permissions**: Per-user grants that augment role permissions
- **Resource-level filters**: Limit permissions to specific resources/types
- **Temporal permissions**: Expiry on roles and direct grants
- **Scoped access**: Multi-tenant friendly with scoping
- **Audit service**: Structured audit helpers + optional check logging
- **Targeted caching**: Catalog and non-temporal lookup caches via CacheStore
- **REST API**: Full CRUD + assignment endpoints
- **Flexible config**: Tunable caching, inheritance, and logging

Installation
------------

[](#installation)

### Installation (Recommended)

[](#installation-recommended)

**Install via Composer**

```
composer require glueful/aegis

# Rebuild the extensions cache after adding new packages
php glueful extensions:cache
```

Composer discovers packages of type `glueful-extension`, but **installing does not auto-enable** them — the provider must be added to `config/extensions.php`'s `enabled` allow-list. The CLI does that for you:

```
# Enable (adds the provider FQCN to config/extensions.php + recompiles the cache)
php glueful extensions:enable aegis

# Disable (removes it)
php glueful extensions:disable aegis
```

In production, manage the `enabled` list in config and run `php glueful extensions:cache` in your deploy step.

Run database migrations (if not auto-run by your workflow):

```
php glueful migrate:run
```

### Local Development Installation

[](#local-development-installation)

To develop the extension locally, register it as a Composer **path repository** in your app's `composer.json`, then require and enable it:

```
// composer.json
"repositories": [
    { "type": "path", "url": "extensions/aegis", "options": { "symlink": true } }
]
```

```
composer require glueful/aegis:@dev
php glueful extensions:enable aegis
```

Entries in `config/extensions.php` are plain string FQCNs (no `::class`) — prefer `extensions:enable` over editing by hand.

Run the migrations to create the necessary database tables:

```
php glueful migrate run
```

3. Generate API documentation (optional, if your tooling supports it):

```
php glueful generate:json doc
```

4. Restart your web server to apply the changes.

### Verify Installation

[](#verify-installation)

Check status and details:

```
php glueful extensions:list
php glueful extensions:info aegis
php glueful extensions:diagnose
```

Post-install checklist:

- Run migrations (if not auto-run): `php glueful migrate run`
- Hit an endpoint to verify: `GET /rbac/roles`
- Rebuild cache after Composer operations: `php glueful extensions:cache`
- Check logs for initialization messages or errors

### Quick Start

[](#quick-start)

Create a role, assign it to a user, and verify via the API. Replace placeholders before running:

- `API_BASE` with your base URL (e.g., )
- `TOKEN` with a valid bearer token
- `USER_UUID` with an existing user's UUID

```
API_BASE=http://localhost:8000
TOKEN=""
USER_UUID=""

# 1) Create a role
create_resp=$(curl -s -X POST "$API_BASE/rbac/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editor",
    "slug": "editor",
    "description": "Can edit content"
  }')

# Extract role UUID (requires jq). If jq is unavailable, inspect $create_resp
ROLE_UUID=$(printf "%s" "$create_resp" | jq -r '.data.uuid')
echo "Created role UUID: $ROLE_UUID"

# 2) Assign the role to a user
curl -s -X POST "$API_BASE/rbac/roles/$ROLE_UUID/assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\n    \"user_uuid\": \"$USER_UUID\",\n    \"scope\": {\"tenant_id\": \"tenant_1\"}\n  }" | jq .

# 3a) Verify: list the user's roles
curl -s "$API_BASE/rbac/users/$USER_UUID/roles" \
  -H "Authorization: Bearer $TOKEN" | jq .

# 3b) Verify: explicit role check by slug
curl -s -X POST "$API_BASE/rbac/users/$USER_UUID/check-role" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_slug": "editor"
  }' | jq .
```

### Quick Start (PHP)

[](#quick-start-php)

Programmatic equivalent using the container and services:

```