Installation and Setup

This page provides step-by-step instructions for installing the hypervel/permission package, publishing configuration and migration files, and completing initial setup. For detailed configuration options, refer to page 5.2 (Configuration Reference). For database schema details, refer to page 4.1 (Database Migrations).

Package Installation

The hypervel/permission package is installed via Composer and requires PHP 8.2 or higher.

Composer Installation

The package automatically registers with supported frameworks through service provider auto-discovery mechanisms defined in composer.json39-51

Package Dependencies and Auto-Discovery

Sources: composer.json28-35 composer.json39-51

Framework Integration

The package supports both Hyperf and Hypervel frameworks through dedicated integration providers defined in composer.json39-51

Hyperf Framework Integration

Hyperf applications use Hypervel\Permission\ConfigProvider for dependency injection and command registration.

ConfigProvider Registration Flow

The ConfigProvider::__invoke() method returns an array with three sections:

• dependencies: Binds Factory contract to PermissionManager singleton (src/ConfigProvider.php15-17)
• commands: Registers ShowCommand for CLI access (src/ConfigProvider.php18-20)
• publish: Defines publishable assets with IDs config and migrations (src/ConfigProvider.php21-34)

Sources: src/ConfigProvider.php10-37 composer.json43-45

Hypervel Framework Integration

Hypervel applications use Hypervel\Permission\PermissionServiceProvider extending Hypervel\Support\ServiceProvider.

PermissionServiceProvider Lifecycle

The PermissionServiceProvider implements two methods:

• register(): Merges default configuration from publish/permission.php into the application config (src/PermissionServiceProvider.php19-25)
• boot(): Registers publishable assets with tags permission-config and permission-migrations (src/PermissionServiceProvider.php11-38)

Sources: src/PermissionServiceProvider.php9-39 composer.json46-49

Publishing Configuration and Migrations

After installation, publish the configuration file and database migrations to your application.

Publishing Commands

For Hyperf Applications:

For Hypervel Applications:

Published Files

Asset Publishing Mapping

Asset Type	Package Path	Hyperf Destination	Hypervel Destination
Configuration	publish/permission.php	config/autoload/permission.php	config/permission.php
Migration	database/migrations/2025_07_02_000000_create_permission_tables.php	database/migrations/2025_07_02_000000_create_permission_tables.php	database/migrations/2025_07_02_000000_create_permission_tables.php

Sources: src/ConfigProvider.php21-34 src/PermissionServiceProvider.php27-38

Configuration Overview

The published permission.php configuration file controls permission system behavior. For detailed documentation of all options, refer to page 5.2 (Configuration Reference).

Configuration Structure

Configuration File Sections

Key Configuration Options

Configuration Key	Line Range	Purpose	Default Value
models.role	publish/permission.php29	Role model class	\Hypervel\Permission\Models\Role::class
models.permission	publish/permission.php40	Permission model class	\Hypervel\Permission\Models\Permission::class
storage.database.connection	publish/permission.php56	Database connection	env('DB_CONNECTION', 'mysql')
table_names.roles	publish/permission.php78	Roles table name	'roles'
table_names.permissions	publish/permission.php86	Permissions table name	'permissions'
table_names.role_has_permissions	publish/permission.php94	Role-permission pivot	'role_has_permissions'
table_names.owner_has_permissions	publish/permission.php102	Owner-permission pivot	'owner_has_permissions'
table_names.owner_has_roles	publish/permission.php110	Owner-role pivot	'owner_has_roles'
cache.expiration_seconds	publish/permission.php168	Cache TTL	86400 (24 hours)
cache.store	publish/permission.php194	Cache driver	env('PERMISSION_CACHE_STORE', 'default')
cache.keys.roles	publish/permission.php175	Global roles cache key	'hypervel.permission.cache.roles'

Sources: publish/permission.php1-196

Database Setup

After publishing the migration, execute it to create the required database tables.

Running Migrations

For Hyperf Applications:

For Hypervel Applications:

Migration Class Structure

The migration file defines an anonymous class extending Hypervel\Database\Migrations\Migration (database/migrations/2025_07_02_000000_create_permission_tables.php11):

Migration Methods

Created Tables

The migration creates five tables defined in database/migrations/2025_07_02_000000_create_permission_tables.php24-88:

Table Name	Primary Key	Notable Columns	Defined At
roles	id (bigIncrements)	name (unique), guard_name	lines 28-35
permissions	id (bigIncrements)	name (unique), guard_name	lines 37-43
role_has_permissions	[permission_id, role_id] (composite)	is_forbidden (boolean)	lines 44-53
owner_has_permissions	[permission_id, owner_id, owner_type] (composite)	is_forbidden (boolean), owner morphs	lines 55-64
owner_has_roles	[role_id, owner_id, owner_type] (composite)	owner morphs	lines 66-74

Entity Relationship Schema

Sources: database/migrations/2025_07_02_000000_create_permission_tables.php11-89

Verification

After completing the installation and setup, verify the system is working correctly:

1. Check Configuration: Ensure config/permission.php exists and contains expected values
2. Verify Database: Confirm the five permission tables exist in your database
3. Test Integration: The package should now be available for use in your application models

The permission system is now ready for use. Next, you can add the HasPermission and HasRole traits to your application models. For detailed usage information, see HasPermission Trait and HasRole Trait.