Skip to main content

​
Overview

This guide walks you through setting up GAC and performing your first permission check. You’ll learn how to configure the database connection, set up an entity, retrieve permissions, and validate access.
This guide assumes you’ve already installed GAC and imported the database schema. If not, check the installation guide first.

​
Step 1: Initialize GAC

Create a GAC instance and configure the database connection. 
<?php

require_once 'vendor/autoload.php';

use DancasDev\GAC\GAC;
use PDO;

// Create PDO connection
$pdo = new PDO(
    'mysql:host=localhost;dbname=your_database',
    'username',
    'password'
);

// Initialize GAC with PDO
$gac = new GAC();
$gac->setDatabase($pdo);
The database connection array requires all four keys: host, database, username, and password. Missing any will throw a DatabaseAdapterException.

​
Step 2: Configure caching (optional)

Enable caching to improve performance by reducing database queries. 
// Set up file-based caching
$gac->setCache(
    key: 'myapp_gac',           // Cache key prefix
    ttl: 1800,                  // TTL in seconds (30 minutes)
    dir: '/path/to/cache/dir'   // Cache directory
);
Caching is optional but recommended for production. The default TTL is 30 minutes (1800 seconds).

​
Step 3: Set the entity

Specify which user or client you want to check permissions for. 
// Set entity for a user
$gac->setEntity('user', $userId);

// Or set entity for a client
$gac->setEntity('client', $clientId);

// You can also use numeric entity types directly
$gac->setEntity('1', $userId);    // '1' = user
$gac->setEntity('2', $clientId);  // '2' = client
The setEntity() method returns the GAC instance, allowing method chaining: 
$permissions = $gac->setEntity('user', $userId)
                   ->getPermissions();
Entity types are mapped internally: ‘user’ → ‘1’ and ‘client’ → ‘2’. You can use either format.

​
Step 4: Retrieve permissions

Get the permissions for the specified entity. 
// Get permissions (from cache if available)
$permissions = $gac->getPermissions();

// Get permissions directly from database (bypass cache)
$permissions = $gac->getPermissions(fromCache: false);
The getPermissions() method returns a Permissions object containing all modules the entity can access.

​
Step 5: Check permissions

Use the Permissions object to verify access to modules and features. 
// Check if user has access to a module
if ($permissions->has('users')) {
    echo "User has access to the users module";
}

​
Available features

GAC supports these built-in features:
  • create / '0' - Create new records
  • read / '1' - Read/view records
  • update / '2' - Update existing records
  • delete / '3' - Delete records
  • trash / '4' - Access trash/recycle bin (combined with read, update, or delete)
  • dev / '5' - Access development/beta features
You can use either the string name (e.g., ‘create’) or numeric code (e.g., ‘0’) when checking features.

​
Step 6: Apply restrictions

Retrieve and validate restrictions to enforce additional access rules. 
// Get restrictions for the entity
$restrictions = $gac->getRestrictions();

// Check if entity has date-based restrictions
if ($restrictions->has('by_date')) {
    $dateRestriction = $restrictions->get('by_date');
    
    // Validate current date against restrictions
    $allowed = $dateRestriction->run([
        'date' => time()
    ]);
    
    if (!$allowed) {
        $error = $dateRestriction->getError();
        die('Access denied: Outside allowed time window');
    }
}

// Check entity-based restrictions (e.g., branch access)
if ($restrictions->has('by_branch')) {
    $branchRestriction = $restrictions->get('by_branch');
    
    $allowed = $branchRestriction->run([
        'entity' => $currentBranchId
    ]);
    
    if (!$allowed) {
        die('Access denied: Branch not allowed');
    }
}
Restrictions are optional. If no restrictions are configured for an entity, the has() method returns false.

​
Complete example

Here’s a complete example combining all steps: 
<?php

require_once 'vendor/autoload.php';

use DancasDev\GAC\GAC;
use PDO;

// 1. Initialize GAC
$pdo = new PDO('mysql:host=localhost;dbname=your_database', 'username', 'password');
$gac = new GAC();
$gac->setDatabase($pdo)
    ->setCache('myapp_gac', 1800);

// 2. Set entity (e.g., from session)
$userId = $_SESSION['user_id'];
$gac->setEntity('user', $userId);

// 3. Get permissions
$permissions = $gac->getPermissions();

// 4. Check access to users module
if (!$permissions->has('users')) {
    http_response_code(403);
    die('Access denied: You do not have access to the users module');
}

// 5. Verify create permission
$permission = $permissions->get('users');
if (!$permission->hasFeature('create')) {
    http_response_code(403);
    die('Access denied: You cannot create users');
}

// 6. Check restrictions
$restrictions = $gac->getRestrictions();
if ($restrictions->has('by_date')) {
    $dateRestriction = $restrictions->get('by_date');
    if (!$dateRestriction->run(['date' => time()])) {
        http_response_code(403);
        die('Access denied: Outside allowed time window');
    }
}

// 7. All checks passed - proceed with operation
echo "Access granted: You can create users";
createNewUser($_POST);

​
Cache management

GAC provides methods to manage the permission cache: 
// Clear cache for current entity
$gac->setEntity('user', $userId)
    ->clearCache();

// Clear cache including global restrictions
$gac->clearCache(includeGlobal: true);

// Purge permissions cache for specific entities
$gac->purgePermissionsBy('user', [$userId1, $userId2]);
$gac->purgePermissionsBy('role', [$roleId]);
$gac->purgePermissionsBy('global', []);

// Purge restrictions cache
$gac->purgeRestrictionsBy('user', [$userId]);
Clear the cache when permissions or restrictions change (e.g., after assigning a new role or updating module access).

​
Common patterns

​
Middleware for route protection

function checkPermission(string $module, array $features = []) {
    global $gac;
    
    $permissions = $gac->getPermissions();
    $permission = $permissions->get($module);
    
    if (!$permission) {
        http_response_code(403);
        die('Access denied');
    }
    
    if (!empty($features) && !$permission->hasFeature($features)) {
        http_response_code(403);
        die('Insufficient permissions');
    }
}

// Usage in routes
checkPermission('users', ['read']);
showUsers();

​
API endpoint protection

// POST /api/users - Create user
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $gac->setEntity('client', $apiClientId);
    $permissions = $gac->getPermissions();
    $permission = $permissions->get('users');
    
    if (!$permission || !$permission->hasFeature('create')) {
        echo json_encode(['error' => 'Forbidden']);
        http_response_code(403);
        exit;
    }
    
    // Process request
}

​
Next steps

You now know the basics of GAC! Explore these topics to learn more:

Permissions

Deep dive into permission management and granularity

Restrictions

Learn about date-based and custom restrictions

Adapters

Implement custom database and cache adapters

API reference

Complete API documentation for all classes

Build docs developers (and LLMs) love

Get started for freeTalk to us