KMP PHP API Reference

Child tables should override for custom branch relationships.

Implements business rules that ensure organizational data integrity beyond basic field validation. Enforces unique constraints and referential integrity for the branch hierarchy.

Business Rules:

• Unique branch names across entire organization
• Referential integrity for parent-child relationships
• Tree structure consistency (handled by Tree behavior)

Rule Processing:

• isUnique: Prevents duplicate branch names
• Additional rules can be added for complex business logic
• Integrates with Tree behavior for hierarchy validation

Retrieves all descendant branch IDs for a given branch, using a two-tier caching strategy for optimal performance. This method is critical for authorization and organizational reporting.

Caching Strategy:

1. Check individual cache for specific branch ID
2. If miss, rebuild entire descendants lookup table
3. Cache all branch descendants for future requests
4. Return specific branch descendants

Performance Characteristics:

• Cache hit: O(1) lookup time
• Cache miss: O(n) rebuild time, but caches all branches
• Memory efficient: Only stores branch IDs, not full entities
• TTL: Managed by 'branch_structure' cache configuration

Use Cases:

• Authorization: Check permissions for branch hierarchy
• Reporting: Generate reports for organizational units
• Member management: Find members in branch and sub-branches
• Event planning: Determine branch participation scope

Usage Examples:

// Get all branches under Kingdom of Atlantia
$atlantiaDescendants = $branchesTable->getAllDecendentIds($atlantiaId);
// Returns: [principality1, principality2, barony1, barony2, shire1, ...]

// Authorization check for hierarchical permissions
$userBranches = $user->getPermission('manage_events')->branch_ids;
$canManage = in_array($eventBranchId, $userBranches);

// Member search within organizational scope
$members = $membersTable->find()
    ->where(['branch_id IN' => $branchesTable->getAllDecendentIds($branchId)]);

Retrieves all parent branch IDs for a given branch, providing the complete path from the branch to the root of the hierarchy. Uses caching strategy similar to descendants for optimal performance.

Caching Strategy:

1. Check individual cache for specific branch ID
2. If miss, rebuild entire parents lookup table
3. Cache all branch parents for future requests
4. Return specific branch parents

Return Format:

• Array of parent IDs from immediate parent to root
• Empty array if branch is at root level
• Maintains hierarchical order (parent, grandparent, great-grandparent, ...)

Use Cases:

• Breadcrumb generation for navigation
• Permission inheritance checking
• Organizational reporting and analytics
• Branch hierarchy validation

Usage Examples:

// Get path to root for breadcrumbs
$parentIds = $branchesTable->getAllParents($baronyId);
// Returns: [principalityId, kingdomId] (immediate parent to root)

// Build breadcrumb navigation
$breadcrumbs = [];
foreach ($parentIds as $parentId) {
    $breadcrumbs[] = $branchesTable->get($parentId);
}

// Check permission inheritance
$hasInheritedPermission = false;
foreach ($branchesTable->getAllParents($branchId) as $parentId) {
    if ($user->hasPermissionForBranch($permission, $parentId)) {
        $hasInheritedPermission = true;
        break;
    }
}

Customizes the database schema to properly handle the JSON links field. This ensures that the links field is correctly typed for JSON operations and database storage.

JSON Field Configuration:

• links: Stores external resource URLs and configuration
• Supports nested JSON structures for complex link configurations
• Enables database-level JSON queries and operations

Usage Examples:

// JSON links structure
$branch->links = [
    'website' => 'https://atlantia.sca.org',
    'calendar' => 'https://calendar.atlantia.sca.org',
    'newsletter' => 'https://acorn.atlantia.sca.org',
    'social' => [
        'facebook' => 'https://facebook.com/atlantia.sca',
        'discord' => 'https://discord.gg/atlantia'
    ]
];

Retrieves the entire branch hierarchy as a threaded tree structure, optimized for UI display such as navigation menus, dropdowns, and organizational charts. Uses Tree behavior's efficient threaded find.

Tree Structure:

• Nested array with 'children' key for sub-branches
• Includes minimal fields for performance (id, name, parent_id)
• Maintains hierarchical relationships and ordering
• Ready for direct use in view templates

Performance Considerations:

• Efficient single query using Tree behavior
• Minimal field selection for reduced memory usage
• No caching (structure changes frequently)
• Use sparingly for large hierarchies

Usage Examples:

// Generate navigation menu
$tree = $branchesTable->getThreadedTree();
foreach ($tree as $kingdom) {
    echo $kingdom->name;
    foreach ($kingdom->children as $principality) {
        echo "  " . $principality->name;
        foreach ($principality->children as $barony) {
            echo "    " . $barony->name;
        }
    }
}

// Generate organizational chart data
$chartData = $this->convertTreeToChartFormat($tree);

Sets up the BranchesTable with all necessary associations, behaviors, and configuration for hierarchical branch management. Establishes parent-child relationships, member associations, and enables tree operations with audit trails.

Tree Behavior Configuration:

• Nested set model for efficient tree queries
• Automatic lft/rght field management
• Support for tree recovery and integrity maintenance
• Parent-child relationship handling

Behavioral Features:

• Timestamp: Automatic created/modified tracking
• Footprint: User attribution for data changes
• Trash: Soft deletion with recovery capabilities
• Tree: Hierarchical data management

Association Setup:

• Self-referential parent-child relationships
• One-to-many member associations
• Support for unlimited hierarchy depth

Implements comprehensive validation for branch entities to ensure data quality and organizational consistency. Enforces unique naming across the entire hierarchy and validates required organizational information.

Validation Rules:

• Name: Required, non-empty, unique across all branches
• Location: Required, non-empty string for geographic identification
• Additional validations applied through business rules

Security Considerations:

• Unique name constraint prevents organizational confusion
• Required fields ensure complete branch registration
• Validates against SQL injection and XSS attacks

Usage Examples:

// Valid branch data
$validData = [
    'name' => 'Barony of Windmasters Hill',
    'location' => 'Northern Virginia, USA',
    'type' => 'Barony',
    'parent_id' => $atlantiaId
];

// Validation errors
$invalidData = [
    'name' => '',  // Error: required field
    'location' => ''  // Error: required field
];

$duplicateData = [
    'name' => 'Kingdom of Atlantia'  // Error: name already exists
];