Configuration Reference

This document provides a complete reference for all configuration options available in the permission.php configuration file. Each option is explained with its purpose, default value, and effects on system behavior.

For information about how the configuration is loaded and registered with the framework, see Service Providers and Configuration. For details about the caching system that uses these cache-related configuration options, see Caching System.

---

Configuration File Structure

The permission.php configuration file is published to your application's config/ directory and contains five main sections: models, storage, table names, column names, and cache settings.

Configuration File Organization

Sources: publish/permission.php1-196

---

Model Configuration

The models section defines which Eloquent model classes are used for roles and permissions. These classes must implement specific contracts to function properly with the permission system.

Configuration Options

Option	Default Value	Contract Required	Purpose
models.role	\Hypervel\Permission\Models\Role::class	Hypervel\Permission\Contracts\Role	Specifies the Eloquent model for roles
models.permission	\Hypervel\Permission\Models\Permission::class	Hypervel\Permission\Contracts\Permission	Specifies the Eloquent model for permissions

Configuration Location: publish/permission.php19-41

How Model Configuration is Used

The PermissionManager reads these configuration values during initialization and validates that the specified classes implement the required contracts:

The validation occurs in src/PermissionManager.php46-67 which throws an InvalidArgumentException if either model class does not implement its required contract.

Custom Model Classes

To use custom model classes:

1. Create a class that extends the base model
2. Ensure it implements the required contract (Contracts\Role or Contracts\Permission)
3. Update the configuration value to point to your custom class

Example configuration:

Sources: publish/permission.php19-41 src/PermissionManager.php35-67

---

Storage Configuration

The storage section controls which database connection is used for permission-related tables. This allows you to store permissions in a separate database if needed.

Configuration Options

Option	Default Value	Environment Variable	Purpose
storage.database.connection	'mysql'	DB_CONNECTION	Database connection name for permission tables

Configuration Location: publish/permission.php54-58

Usage

This configuration option allows you to:

• Use a different database for permissions (e.g., separate microservice database)
• Use a different database driver (e.g., PostgreSQL instead of MySQL)
• Implement multi-tenancy with separate permission databases per tenant

Example configuration:

The connection name must match a connection defined in your config/database.php file.

Sources: publish/permission.php54-58

---

Table Names Configuration

The table_names section defines the names of all five database tables used by the permission system. These can be customized to match your existing schema or naming conventions.

Configuration Options

Option	Default Value	Purpose	Table Type
table_names.roles	'roles'	Stores role records	Entity table
table_names.permissions	'permissions'	Stores permission records	Entity table
table_names.role_has_permissions	'role_has_permissions'	Associates permissions with roles	Pivot table
table_names.owner_has_permissions	'owner_has_permissions'	Associates permissions with owners	Polymorphic pivot table
table_names.owner_has_roles	'owner_has_roles'	Associates roles with owners	Polymorphic pivot table

Configuration Location: publish/permission.php71-111

Table Relationships

Customizing Table Names

When changing table names, ensure:

1. The migration creates tables with the new names
2. Model classes reference the correct table names using the $table property
3. All pivot relationships use the correct table names

Example configuration:

Sources: publish/permission.php71-111

---

Column Names Configuration

The column_names section allows customization of column names used in pivot tables and polymorphic relationships. This is particularly useful when integrating with existing schemas or using UUID primary keys.

Configuration Options

Option	Default Value	Used In	Purpose
column_names.role_pivot_key	'role_id'	role_has_permissions, owner_has_roles	Foreign key column for role references
column_names.permission_pivot_key	'permission_id'	role_has_permissions, owner_has_permissions	Foreign key column for permission references
column_names.owner_morph_key	'owner_id'	owner_has_permissions, owner_has_roles	Foreign key column for owner references
column_names.owner_name	'owner'	Polymorphic relations	Name of the morphable relation

Configuration Location: publish/permission.php124-148

UUID Primary Keys Example

For applications using UUID primary keys instead of integer IDs:

Polymorphic Relationship Structure

The owner_name configuration value determines the name of the morphable relation (the prefix for owner_type and owner_id/owner_uuid columns).

Sources: publish/permission.php124-148

---

Cache Configuration

The cache section controls how permission and role data is cached to optimize performance. The system implements a two-tier caching strategy with configurable expiration times and cache stores.

Configuration Options

Option	Default Value	Environment Variable	Purpose
cache.expiration_seconds	86400 (24 hours)	N/A	TTL for all cached permission data
cache.store	'default'	PERMISSION_CACHE_STORE	Cache driver to use
cache.keys.roles	'hypervel.permission.cache.roles'	N/A	Cache key for global roles with permissions
cache.keys.owner_roles	'hypervel.permission.cache.owner.roles'	N/A	Prefix for owner-specific role caches
cache.keys.owner_permissions	'hypervel.permission.cache.owner.permissions'	N/A	Prefix for owner-specific permission caches

Configuration Location: publish/permission.php162-195

Cache Store Selection

The cache.store option supports three scenarios:

1. 'default': Uses the default cache store from config/cache.php
2. Named store: Uses a specific cache store (e.g., 'redis', 'memcached')
3. Invalid store: Falls back to 'array' driver (in-memory, non-persistent)

Cache Store Resolution Process:

The resolution logic is implemented in src/PermissionManager.php102-119

Cache Key Structure

The system uses three types of cache keys:

Global Roles Cache:

hypervel.permission.cache.roles

Stores all roles with their associated permissions for efficient role-permission lookups.

Owner Roles Cache:

hypervel.permission.cache.owner.roles:{owner_type}:{owner_id}

Example: hypervel.permission.cache.owner.roles:App\Models\User:123

Generated by src/PermissionManager.php124-127

Owner Permissions Cache:

hypervel.permission.cache.owner.permissions:{owner_type}:{owner_id}

Example: hypervel.permission.cache.owner.permissions:App\Models\User:123

Generated by src/PermissionManager.php132-135

Cache Key Generation

Cache Expiration

All cached data uses the same TTL defined in cache.expiration_seconds. The TTL is applied when:

• Roles with permissions are cached: src/PermissionManager.php144
• Owner roles are cached: src/PermissionManager.php166
• Owner permissions are cached: src/PermissionManager.php179

To disable caching entirely, set cache.store to 'array' and cache.expiration_seconds to 0.

Sources: publish/permission.php162-195 src/PermissionManager.php79-119 src/PermissionManager.php124-135

---

Configuration Loading Process

The following diagram illustrates how configuration values are accessed throughout the system:

All configuration access goes through src/PermissionManager.php88-91 which uses the ConfigInterface to retrieve values with the permission. prefix.

Sources: src/PermissionManager.php88-91 src/PermissionManager.php79-86

---

Configuration Change Impact

The following table summarizes the impact of changing each configuration option:

Configuration Path	Requires Migration Change	Requires Cache Clear	Requires Code Changes	Effect on Existing Data
models.role	No	No	Yes (if custom class)	No impact if compatible
models.permission	No	No	Yes (if custom class)	No impact if compatible
storage.database.connection	Yes	No	No	Data must be migrated to new connection
table_names.*	Yes	No	No	Tables must exist with new names
column_names.role_pivot_key	Yes	No	No	Columns must be renamed in DB
column_names.permission_pivot_key	Yes	No	No	Columns must be renamed in DB
column_names.owner_morph_key	Yes	No	No	Columns must be renamed in DB
column_names.owner_name	Yes	No	No	Morphable relation name changes
cache.expiration_seconds	No	No	No	New TTL applies to future cache entries
cache.store	No	Yes (recommended)	No	Cache location changes immediately
cache.keys.roles	No	Yes (recommended)	No	Cache key changes, old cache orphaned
cache.keys.owner_roles	No	Yes (recommended)	No	Cache key prefix changes
cache.keys.owner_permissions	No	Yes (recommended)	No	Cache key prefix changes

Best Practices for Configuration Changes

1. Model classes: Always implement the required contract interfaces
2. Database connection: Test connection before deploying; consider data migration strategy
3. Table names: Update migration file before running migrations
4. Column names: Ensure consistency across all pivot tables
5. Cache settings: Clear cache after changing cache keys or store to prevent stale data

Sources: publish/permission.php1-196 src/PermissionManager.php31-91