Skip to main content

​
Overview

The DatabaseAdapter class provides database connectivity and data retrieval methods for the GAC (Gestión de Acceso y Control) system. It implements the DatabaseAdapterInterface and handles all database operations related to roles, permissions, restrictions, and modules.

​
Class Reference

​
DatabaseAdapter

Namespace: DancasDev\GAC\Adapters Implements: DatabaseAdapterInterface

​
Constructor

public function __construct(PDO|array $params)
Initializes the database adapter with either a PDO instance or connection parameters.
​
params
PDO|array
required
Database connection. Can be either:
  • A PDO instance for direct connection reuse
  • An array with connection parameters: host, username, password, database
Throws:
  • DatabaseAdapterException - If connection parameters are invalid or connection fails
Example: 
// Using PDO instance
$pdo = new PDO('mysql:host=localhost;dbname=mydb', 'user', 'pass');
$adapter = new DatabaseAdapter($pdo);

// Using connection parameters
$adapter = new DatabaseAdapter([
    'host' => 'localhost',
    'username' => 'user',
    'password' => 'pass',
    'database' => 'mydb'
]);

​
Methods

​
getRoles

public function getRoles(string $entityType, string|int $entityId): array
Retrieves roles assigned to a specific entity.
​
entityType
string
required
Type of entity:
  • '1' for user
  • '2' for client
​
entityId
string|int
required
Identifier of the entity
Returns:
​
array
array
Array of roles assigned to the entity, ordered by priority (ascending)
Example: 
$roles = $adapter->getRoles('1', 123);
// Returns: [
//   ['id' => '5', 'code' => 'admin', 'priority' => '1'],
//   ['id' => '8', 'code' => 'editor', 'priority' => '2']
// ]

​
getPermissions

public function getPermissions(string $entityType, string|int $entityId, array $roleIds = []): array
Retrieves permissions associated with an entity, including both direct permissions and those inherited from assigned roles.
​
entityType
string
required
Type of entity:
  • '0' returns empty array (special case)
  • '1' for user
  • '2' for client
​
entityId
string|int
required
Identifier of the entity
​
roleIds
array
default:"[]"
Array of role identifiers for inherited permissions (optional)
Returns:
​
array
array
Array of permissions (unprocessed), ordered by from_entity_type (descending)
Example: 
$permissions = $adapter->getPermissions('1', 123, [5, 8]);
// Returns permissions for user 123 and roles 5, 8

​
getRestrictions

public function getRestrictions(string $entityType, string|int $entityId, array $roleIds = []): array
Retrieves restrictions associated with an entity, including both direct restrictions and those inherited from assigned roles.
​
entityType
string
required
Type of entity:
  • '0' returns empty array (special case)
  • '1' for user
  • '2' for client
​
entityId
string|int
required
Identifier of the entity
​
roleIds
array
default:"[]"
Array of role identifiers for inherited restrictions (optional)
Returns:
​
array
array
Array of restrictions (unprocessed), ordered by entity_type (descending)
Example: 
$restrictions = $adapter->getRestrictions('1', 123, [5]);
// Returns restrictions for user 123 and role 5

​
getModulesData

public function getModulesData(array $categoryIds = [], array $moduleIds = []): array
Retrieves module data based on provided module and/or category IDs.
​
categoryIds
array
default:"[]"
Array of module category identifiers (optional)
​
moduleIds
array
default:"[]"
Array of module identifiers (optional)
Returns:
​
array
array
Array of module data. Returns empty array if both parameters are empty.
Example: 
$modules = $adapter->getModulesData([1, 2], [10, 11]);
// Returns modules from categories 1, 2 and specific modules 10, 11

​
getEntitiesByRoles

public function getEntitiesByRoles(array $roleIds): array
Retrieves entities related to specific roles.
​
roleIds
array
required
Array of role identifiers
Returns:
​
array
array
Array of entities related to the roles. Returns empty array if roleIds is empty.
Example: 
$entities = $adapter->getEntitiesByRoles([5, 8]);
// Returns all entities with roles 5 or 8

​
destroyConnection

public function destroyConnection(): bool
Destroys the database connection. Returns:
​
bool
bool
Always returns true
Note: This method is automatically called by the destructor.

​
DatabaseAdapterInterface

The DatabaseAdapterInterface defines the contract that all database adapters must implement for GAC.

​
Interface Methods

All methods listed above are defined in the interface. Implementing this interface allows you to create custom database adapters for different database systems or ORMs.

​
Creating a Custom Database Adapter

You can create a custom database adapter by implementing the DatabaseAdapterInterface: 
use DancasDev\GAC\Adapters\DatabaseAdapterInterface;

class CustomDatabaseAdapter implements DatabaseAdapterInterface {
    private $connection;
    
    public function __construct($customConnection) {
        $this->connection = $customConnection;
    }
    
    public function getRoles(string $entityType, string|int $entityId): array {
        // Custom implementation
        return $this->connection->query(
            'SELECT id, code, priority FROM roles WHERE entity_type = ? AND entity_id = ?',
            [$entityType, $entityId]
        );
    }
    
    public function getPermissions(string $entityType, string|int $entityId, array $roleIds = []): array {
        // Custom implementation
        // Must return permissions in the expected format
    }
    
    public function getRestrictions(string $entityType, string|int $entityId, array $roleIds = []): array {
        // Custom implementation
    }
    
    public function getModulesData(array $categoryIds = [], array $moduleIds = []): array {
        // Custom implementation
    }
    
    public function getEntitiesByRoles(array $roleIds): array {
        // Custom implementation
    }
}

// Use with GAC
$customAdapter = new CustomDatabaseAdapter($myConnection);
$gac = new GAC($customAdapter);

​
Database Schema Requirements

The default DatabaseAdapter expects the following tables:
  • gac_role - Stores role definitions
  • gac_role_entity - Links roles to entities (users/clients)
  • gac_module_access - Stores permission rules
  • gac_restriction - Stores restriction rules
  • gac_restriction_method - Defines restriction types
  • gac_restriction_category - Categorizes restrictions
  • gac_module - Stores module definitions
  • gac_module_category - Categorizes modules
Each table should include:
  • is_disabled column (0 = active, 1 = disabled)
  • deleted_at column (NULL = active, timestamp = soft deleted)

​
Error Handling

The DatabaseAdapter throws DatabaseAdapterException in the following cases:
  • Invalid connection parameters provided to constructor
  • Database connection fails
  • Cannot set cache directory (for CacheAdapter)
Always wrap adapter operations in try-catch blocks: 
try {
    $adapter = new DatabaseAdapter([
        'host' => 'localhost',
        'username' => 'user',
        'password' => 'pass',
        'database' => 'mydb'
    ]);
    $roles = $adapter->getRoles('1', 123);
} catch (DatabaseAdapterException $e) {
    // Handle database adapter errors
    error_log('Database adapter error: ' . $e->getMessage());
}

Build docs developers (and LLMs) love

Get started for freeTalk to us