upskill-event-manager/docs/role-manager-api.md

HVAC Role Manager API Documentation

Overview

The HVAC Role Manager is a comprehensive WordPress role management system that provides advanced capabilities for role creation, inheritance, and conflict detection. It seamlessly integrates with The Events Calendar (TEC) and supports complex permission hierarchies.

Key Features

• Role creation and management
• Multiple role inheritance
• Capability conflict detection
• Transaction-based role operations
• TEC capability integration
• Core WordPress role protection

Prerequisites

• WordPress 5.0 or higher
• The Events Calendar (for TEC-specific capabilities)

API Reference

Role Management

create_role()

/**
 * Creates a new WordPress role with specified capabilities
 *
 * @param string $role_name     Unique identifier for the role
 * @param string $display_name  Human-readable name for the role
 * @param array  $capabilities  Array of capabilities (key: capability name, value: boolean)
 * @param array  $parent_roles  Optional. Array of parent role names to inherit from
 * @return bool True on success, false on failure
 * @throws InvalidArgumentException If role name/display name is empty or role exists
 */
public function create_role(
    string $role_name,
    string $display_name,
    array $capabilities,
    array $parent_roles = []
): bool

Example:

try {
    $role_manager->create_role(
        'event_coordinator',
        'Event Coordinator',
        ['edit_posts' => true, 'publish_tribe_events' => true],
        ['editor']  // Inherit from editor role
    );
} catch (InvalidArgumentException $e) {
    // Handle error
}

delete_role()

/**
 * Deletes a WordPress role if it's not a core role
 *
 * @param string $role_name Role identifier to delete
 * @return bool True on success, false on failure
 * @throws InvalidArgumentException If attempting to delete a core role
 */
public function delete_role(string $role_name): bool

Example:

try {
    $role_manager->delete_role('event_coordinator');
} catch (InvalidArgumentException $e) {
    // Handle error (e.g., attempting to delete core role)
}

Capability Management

add_capabilities()

/**
 * Adds capabilities to an existing role
 *
 * @param string $role_name    Role identifier
 * @param array  $capabilities Array of capability names to add
 * @return bool True on success, false on failure
 */
public function add_capabilities(string $role_name, array $capabilities): bool

Example:

$new_caps = ['new_cap_1', 'new_cap_2'];
$result = $role_manager->add_capabilities('event_coordinator', $new_caps);

remove_capabilities()

/**
 * Removes capabilities from an existing role
 *
 * @param string $role_name    Role identifier
 * @param array  $capabilities Array of capability names to remove
 * @return bool True on success, false on failure
 */
public function remove_capabilities(string $role_name, array $capabilities): bool

Example:

$result = $role_manager->remove_capabilities('event_coordinator', ['new_cap_1']);

Role Verification

role_exists()

/**
 * Checks if a role exists
 *
 * @param string $role_name Role identifier to check
 * @return bool True if role exists, false otherwise
 */
public function role_exists(string $role_name): bool

get_role_capabilities()

/**
 * Retrieves all capabilities for a role
 *
 * @param string $role_name Role identifier
 * @return array Array of capabilities (key: capability name, value: boolean)
 */
public function get_role_capabilities(string $role_name): array

Conflict Detection

detect_role_conflicts()

/**
 * Detects capability conflicts between roles
 *
 * @param array $role_names Array of role names to check for conflicts
 * @return array Array of conflict information
 */
public function detect_role_conflicts(array $role_names): array

Example:

$conflicts = $role_manager->detect_role_conflicts(['role_1', 'role_2']);
if (!empty($conflicts)) {
    // Handle conflicts
}

Advanced Concepts

Role Inheritance

The Role Manager supports multiple role inheritance, allowing roles to inherit capabilities from multiple parent roles. This creates a flexible permission hierarchy that can model complex organizational structures.

// Create a role that inherits from multiple parents
$role_manager->create_role(
    'senior_coordinator',
    'Senior Event Coordinator',
    ['manage_options' => true],
    ['event_coordinator', 'content_manager']
);

Transaction Roles

Transaction roles are temporary roles used during specific operations. They are automatically cleaned up to prevent role pollution.

// Clean up transaction roles
$role_manager->cleanup_transaction_roles();

Security Best Practices

1. Core Role Protection

   • Never modify WordPress core roles directly
   • Use role inheritance instead of modifying core roles
   • Always check for core role status before deletion

2. Capability Validation

   • Validate all capability names before assignment
   • Use WordPress capability constants where available
   • Check for capability conflicts in multi-role scenarios

3. Error Handling

   • Always wrap role operations in try-catch blocks
   • Validate input parameters thoroughly
   • Handle cleanup operations in catch blocks

Integration Examples

Basic Role Management

try {
    // Create a basic role
    $role_manager->create_role(
        'basic_user',
        'Basic User',
        ['read' => true]
    );

    // Add capabilities
    $role_manager->add_capabilities('basic_user', ['edit_posts']);

    // Verify capabilities
    $caps = $role_manager->get_role_capabilities('basic_user');
    
    // Clean up when done
    $role_manager->delete_role('basic_user');
} catch (Exception $e) {
    // Handle errors
}

TEC Integration

// Create an event manager role
$role_manager->create_role(
    'event_manager',
    'Event Manager',
    [
        'read' => true,
        'publish_tribe_events' => true,
        'edit_tribe_events' => true,
        'delete_tribe_events' => true,
        'manage_tribe_event_settings' => false
    ]
);

Testing & Development

Unit Testing

The Role Manager includes a comprehensive test suite. Run tests using:

phpunit tests/HVAC_Role_Manager_Test.php

Test Environment Setup

1. Ensure WordPress test environment is configured
2. Verify TEC is properly installed
3. Run the test suite
4. Check test coverage

Contributing Guidelines

1. Follow WordPress coding standards
2. Add unit tests for new features
3. Document all changes
4. Test thoroughly before submitting

Troubleshooting

Common Issues

1. Role Creation Fails

   • Check for duplicate role names
   • Verify capability format
   • Ensure parent roles exist

2. Capability Conflicts

   • Use detect_role_conflicts()
   • Check inheritance chain
   • Verify capability assignments

3. Core Role Protection

   • Cannot delete core roles
   • Use role inheritance instead
   • Check role status before operations