Overview

This document provides an introduction to the Hypervel Permission package, a comprehensive Role-Based Access Control (RBAC) system for the Hypervel/Hyperf framework. The package enables fine-grained authorization control by allowing models to be assigned permissions and roles, and provides HTTP middleware to protect routes based on these assignments.

For detailed information about specific subsystems, see: Architecture Overview (1.1), Core Permission System (2), HTTP Middleware Integration (3), Database Schema (4), and Framework Integration (5).

Sources: composer.json1-52 README.md1-5

---

What is Hypervel Permission?

Hypervel Permission is an authorization library that implements RBAC patterns for Hyperf-based applications. The package was migrated from spatie/laravel-permission and adapted for the Hypervel/Hyperf ecosystem. It provides a trait-based approach where any Eloquent model can be made "authorization-aware" by using the HasPermission and HasRole traits.

The system supports:

• Direct permission assignment: Models can have permissions assigned directly
• Role-based permissions: Models can have roles, and roles contain permissions
• Permission inheritance: Permissions assigned to roles are inherited by models with those roles
• Forbidden permissions: Explicit permission denials that override grants
• Multi-guard support: Different authentication contexts via guard_name
• Polymorphic relationships: Any model type can be an "owner" of permissions/roles
• Caching layer: Two-tier caching system for performance optimization

Sources: composer.json1-52 README.md1-5 LICENSE.md1-25

---

Key Components

The package consists of several major subsystems that work together:

Component	Primary Classes/Files	Purpose
Core Traits	HasPermission, HasRole	Provide authorization methods to models
Manager Service	PermissionManager	Handles model resolution, cache management, and coordination
HTTP Middleware	PermissionMiddleware, RoleMiddleware	Enforce authorization at the HTTP request level
Data Models	Role, Permission	Eloquent models representing roles and permissions
Database Schema	Migration file	Defines 5 tables for storing authorization data
Service Providers	ConfigProvider, PermissionServiceProvider	Bootstrap the package and integrate with Hyperf
Exceptions	PermissionException, RoleException, UnauthorizedException	Handle authorization failures
Console Commands	ShowCommand	CLI tools for inspecting permissions

Sources: composer.json23-35 composer.json43-50

---

System Architecture

The following diagram shows how the major components interact within the Hypervel/Hyperf framework:

Component Responsibilities:

• Traits (HasPermission, HasRole): Provide fluent API methods like givePermissionTo(), assignRole(), hasPermissionTo(), hasRole() that can be called on any model
• Manager (PermissionManager): Central service that resolves model classes from configuration, manages cache keys, and coordinates between traits and data layer
• Middleware: Intercept HTTP requests early in the pipeline and verify authorization before reaching application code
• Models (Role, Permission): Standard Eloquent models that represent authorization entities and their relationships
• Database: Five tables storing roles, permissions, and their assignments through pivot tables

Sources: composer.json28-35 composer.json43-50

---

Authorization Data Flow

The following sequence diagram illustrates how a permission check flows through the system:

Key Flow Points:

1. Authentication Check: Middleware first verifies a user is authenticated
2. Permission Retrieval: The HasPermission trait delegates to PermissionManager to get permissions
3. Cache Strategy: Manager checks cache before querying database
4. Permission Logic: Trait evaluates permission rules, including forbidden permissions
5. Exception Handling: Appropriate exceptions thrown based on failure type (401 vs 403)

Sources: composer.json28-35

---

Package Dependencies

Hypervel Permission integrates with several Hypervel framework packages:

Dependency	Version	Purpose
hypervel/auth	^0.3	Provides authentication context and AuthManager
hypervel/cache	^0.3	Caching layer for permission/role data
hypervel/console	^0.3	CLI command infrastructure
hypervel/core	^0.3	Core Hyperf framework integration
hypervel/support	^0.3	Helper functions and utilities

The package requires PHP 8.2 or higher and is designed specifically for the Hypervel/Hyperf ecosystem.

Sources: composer.json28-35 composer.json29

---

Package Structure

The package follows PSR-4 autoloading with the namespace Hypervel\Permission\:

The source code is located under the src/ directory, with the full namespace being Hypervel\Permission\ as defined in the autoload configuration.

Sources: composer.json23-26

---

Framework Integration

The package integrates with Hypervel/Hyperf through two mechanisms:

1. Hyperf Integration (via ConfigProvider): Registers services in the dependency injection container, commands in the console, and defines publishable assets
2. Hypervel Integration (via PermissionServiceProvider): Handles configuration merging and asset publishing during application bootstrap

The integration points are declared in the extra section of composer.json, allowing the framework to auto-discover and register the package components.

Sources: composer.json39-51

---

Database Schema Overview

The package creates a five-table schema to store authorization data:

Table	Purpose
roles	Stores role definitions (name, guard_name)
permissions	Stores permission definitions (name, guard_name)
role_has_permissions	Pivot table linking roles to permissions, includes is_forbidden flag
owner_has_permissions	Polymorphic pivot linking any model to permissions directly, includes is_forbidden flag
owner_has_roles	Polymorphic pivot linking any model to roles

The polymorphic structure (using owner_type and owner_id columns) allows any model class to be an owner of permissions and roles, providing maximum flexibility. The is_forbidden boolean flag enables negative permissions that explicitly deny access.

For detailed schema documentation, see Database Schema and Models (4).

Sources: composer.json2-4

---

Configuration and Customization

The package can be customized through a configuration file that allows overriding:

• Model class names for Role and Permission
• Database table names for all five tables
• Cache settings (store, expiration time, key prefixes)
• Column name customizations

Configuration is published to the application's config/permission.php file. For complete configuration options, see Configuration Reference (5.2).

Sources: composer.json43-50

---

Next Steps

To understand the complete system:

• Architecture Overview (1.1): Deep dive into design patterns and component relationships
• Installation and Setup (1.2): Step-by-step setup instructions
• Core Permission System (2): Learn how to use the HasPermission and HasRole traits
• HTTP Middleware Integration (3): Protect routes with permission and role checks
• Database Schema and Models (4): Understand the data structure and models
• Framework Integration (5): Learn about service providers and configuration

Sources: composer.json1-52