Branch
extends BaseEntity
in package
Branch Entity - Hierarchical Organizational Structure for KMP
Represents a branch in the KMP organizational hierarchy, supporting nested tree structures for kingdoms, principalities, baronies, shires, and other administrative divisions. Provides organizational scoping for members, roles, permissions, and activities.
Tree Structure Features:
- Hierarchical organization using nested set model (Tree behavior)
- Parent-child relationships with unlimited depth
- Automatic tree integrity maintenance and recovery
- Efficient descendant and ancestor queries with caching
Member Management:
- Associates members to specific organizational units
- Controls member visibility and authorization scope
- Supports branch-specific role assignments and permissions
- Enables organizational reporting and analytics
Configuration & Links:
- JSON-based links storage for external resources and websites
- Configurable branch types (Kingdom, Principality, Barony, Shire, etc.)
- Domain association for organization-specific branding
- Member enrollment controls and visibility settings
Authorization Integration:
- Implements getBranchId() for authorization system compatibility
- Supports branch-scoped permissions and data access control
- Enables hierarchical permission inheritance through tree structure
- Integrates with policy-based authorization framework
Usage Examples:
// Basic branch information
$branch = $branchesTable->get($id);
echo $branch->name; // "Kingdom of Atlantia"
echo $branch->location; // "Eastern United States"
echo $branch->type; // "Kingdom"
// Tree operations
$children = $branch->children; // Direct child branches
$descendants = $branch->getAllDescendants(); // All descendant branches
$parents = $branch->getAllParents(); // Path to root
// Member associations
foreach ($branch->members as $member) {
echo $member->sca_name;
}
// JSON links configuration
$branch->links = [
'website' => 'https://atlantia.sca.org',
'calendar' => 'https://calendar.atlantia.sca.org',
'newsletter' => 'https://acorn.atlantia.sca.org'
];
Database Schema:
- id: Primary key
- name: Unique branch name
- location: Geographic or administrative location
- type: Branch classification (Kingdom, Principality, etc.)
- parent_id: Parent branch for tree structure
- links: JSON field for external resource links
- can_have_members: Boolean flag for member enrollment
- domain: Associated domain for branding and access
- lft/rght: Nested set model tree structure fields
- created/modified: Timestamp tracking with user attribution
Tags
Table of Contents
Properties
- $branch_id : int|null
- $can_have_members : bool
- $can_have_officers : bool
- $children : array<string|int, Branch>
- $contact : Member|null
- $contact_id : int|null
- $created : DateTime
- $created_by : int|null
- $domain : string|null
- $id : int
- $lft : int|null
- $links : array<string|int, mixed>|null
- $location : string
- $members : array<string|int, Member>
- $modified : DateTime|null
- $modified_by : int|null
- $name : string
- $parent : Branch|null
- $parent_id : int|null
- $public_id : string
- $rght : int|null
- $type : string|null
- $_accessible : array<string, bool>
- Fields that can be mass assigned using newEntity() or patchEntity().
Methods
- getBranchId() : int|null
- Get branch ID for authorization system compatibility.
Properties
$branch_id
public
int|null
$branch_id
Associated branch ID (when applicable)
$can_have_members
public
bool
$can_have_members
Whether this branch can directly enroll members
$can_have_officers
public
bool
$can_have_officers
Whether this branch can have officers assigned
$children
public
array<string|int, Branch>
$children
Direct child branch entities
$contact
public
Member|null
$contact
Point of contact member for hamlet-mode branches
$contact_id
public
int|null
$contact_id
FK to members.id for hamlet-mode point of contact
$created
public
DateTime
$created
Creation timestamp
$created_by
public
int|null
$created_by
ID of user who created this branch
$domain
public
string|null
$domain
Associated domain for organization-specific access
$id
public
int
$id
Primary key identifier
$lft
public
int|null
$lft
Left boundary for nested set model tree structure
$links
public
array<string|int, mixed>|null
$links
JSON array of external resource links and websites
$location
public
string
$location
Geographic or administrative location description
$members
public
array<string|int, Member>
$members
Members associated with this branch
$modified
public
DateTime|null
$modified
Last modification timestamp
$modified_by
public
int|null
$modified_by
ID of user who last modified this branch
$name
public
string
$name
Unique branch name (e.g., "Kingdom of Atlantia")
$parent
public
Branch|null
$parent
Parent branch entity
$parent_id
public
int|null
$parent_id
Parent branch ID for hierarchical structure
$public_id
public
string
$public_id
Public-facing identifier for URL routing
$rght
public
int|null
$rght
Right boundary for nested set model tree structure
$type
public
string|null
$type
Branch classification (Kingdom, Principality, Barony, Shire, etc.)
$_accessible
Fields that can be mass assigned using newEntity() or patchEntity().
protected
array<string, bool>
$_accessible
= ['*' => true, 'id' => false]
Defines which fields can be safely mass-assigned during entity creation and updates. The ID field is protected to prevent unauthorized changes to the primary key.
Security Considerations:
- ID field is protected to prevent primary key manipulation
- All other fields are accessible for administrative flexibility
- Tree structure fields (lft/rght) are managed by Tree behavior
- Timestamp fields are handled by Timestamp behavior
Mass Assignment Examples:
// Safe mass assignment
$branch = $branchesTable->newEntity([
'name' => 'Barony of Windmasters Hill',
'location' => 'Northern Virginia',
'type' => 'Barony',
'parent_id' => $atlantiaId,
'links' => [
'website' => 'https://windmastershill.atlantia.sca.org'
]
]);
// Update existing branch
$branchesTable->patchEntity($branch, [
'location' => 'Updated Location',
'links' => $updatedLinks
]);
Mass assignment configuration
Methods
getBranchId()
Get branch ID for authorization system compatibility.
public
getBranchId() : int|null
Implements the getBranchId() pattern required by the KMP authorization system. For Branch entities, this returns the entity's own ID since branches are the primary organizational scope for authorization.
Authorization Integration:
- Enables branch-scoped policy authorization
- Supports hierarchical permission inheritance
- Integrates with PermissionsLoader for role-based access control
- Used by AuthorizationService for scope validation
Hierarchical Permissions: The authorization system uses this ID in combination with the tree structure to determine:
- Direct branch permissions (this branch only)
- Inherited permissions (from parent branches)
- Descendant permissions (applied to child branches)
Usage Examples:
// Direct authorization check
$user->checkCan('edit', $branch); // Uses $branch->getBranchId()
// Policy-based authorization
$this->Authorization->authorize($branch); // In controller
// Permission inheritance
$kingdoms = $user->getPermission('manage_branches')->branch_ids;
// Includes all descendant branches through tree hierarchy
Tags
Return values
int|null —The branch's own ID for authorization scoping, or null if entity is new