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()
```php
/**
 * 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:
```php
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()
```php
/**
 * 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:
```php
try {
    $role_manager->delete_role('event_coordinator');
} catch (InvalidArgumentException $e) {
    // Handle error (e.g., attempting to delete core role)
}
```

### Capability Management

#### add_capabilities()
```php
/**
 * 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:
```php
$new_caps = ['new_cap_1', 'new_cap_2'];
$result = $role_manager->add_capabilities('event_coordinator', $new_caps);
```

#### remove_capabilities()
```php
/**
 * 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:
```php
$result = $role_manager->remove_capabilities('event_coordinator', ['new_cap_1']);
```

### Role Verification

#### role_exists()
```php
/**
 * 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()
```php
/**
 * 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()
```php
/**
 * 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:
```php
$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.

```php
// 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.

```php
// 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
```php
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
```php
// 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:
```bash
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