← Back to Member Lifecycle ← Back to Table of Contents

4.1.1 MembersTable API Reference

The MembersTable class provides data access and business logic for the Member entity, serving as the central repository for user management within the KMP system.

Overview

MembersTable handles complex member relationships, validation rules, and business workflows essential for organizational member management. It extends BaseTable to inherit branch scoping, cache management, and standardized behaviors.

Core Responsibilities

Area Description
Identity Storage Complete user profiles with personal and contact information
Authentication Data Secure password storage and login tracking
Status Management Member status tracking with age-based workflow automation
Privacy Controls Configurable privacy settings and minor protection
Relationship Management Role assignments, branch membership, parent-child relationships

Associations

Role System Associations

Association Type Description
Roles BelongsToMany Role assignments through MemberRoles junction table
MemberRoles HasMany All role assignment records
CurrentMemberRoles HasMany Active role assignments (uses current finder)
UpcomingMemberRoles HasMany Future role assignments (uses upcoming finder)
PreviousMemberRoles HasMany Historical role assignments (uses previous finder)

Other Associations

Association Type Description
Branches BelongsTo Organizational branch membership
Parents BelongsTo Parent member for minors (self-referential)
GatheringAttendances HasMany Gathering attendance records

Behaviors

The table uses the following behaviors:

Usage Examples

Basic Member Operations

// Create new member with validation
$member = $this->Members->newEntity([
    'sca_name' => 'Aiden of the North',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email_address' => 'john@example.com',
    'password' => 'SecurePassword123!',
    'status' => Member::STATUS_ACTIVE
]);

if ($this->Members->save($member)) {
    // Member created successfully
}

Querying with Role Associations

// Access current role assignments
$member = $this->Members->get($id, [
    'contain' => ['CurrentMemberRoles.Roles']
]);

// Query members by role
$officerMembers = $this->Members->find()
    ->matching('Roles', function ($q) {
        return $q->where(['Roles.name' => 'Officer']);
    });

Temporal Role Queries

// Get upcoming role assignments
$upcomingRoles = $this->Members->find()
    ->contain(['UpcomingMemberRoles.Roles'])
    ->where(['id' => $memberId]);

// Historical role analysis
$pastRoles = $this->Members->find()
    ->contain(['PreviousMemberRoles.Roles'])
    ->where(['id' => $memberId]);

Complex Queries

// Find members with warrant eligibility
$warrantEligible = $this->Members->find()
    ->where([
        'Members.warrantable' => true,
        'Members.status' => Member::STATUS_VERIFIED_MEMBERSHIP
    ])
    ->contain(['Branches', 'CurrentMemberRoles.Roles']);

// Get validation queue count
$pendingValidations = $this->Members->getValidationQueueCount();

Validation Rules

Password Requirements

Rule Requirement
Minimum Length 12 characters
Maximum Length 125 characters
Required On create operations

Note: Additional complexity rules (uppercase, lowercase, numbers, special characters) are defined but currently commented out in the codebase.

Required Fields

Field Create Update Constraints
sca_name Required - 3-50 characters
first_name Required - Max 30 characters
last_name Required - Max 30 characters
email_address Required - Max 50 characters, unique
password Required - See password requirements

Optional Fields with Validation

Field Constraints
middle_name Max 30 characters
street_address Max 75 characters
city Max 30 characters
state Max 2 characters
zip Max 5 characters
phone_number Max 15 characters
membership_number Optional
membership_expires_on Valid date
parent_name Max 50 characters
background_check_expires_on Valid date
timezone Valid PHP timezone identifier

Timezone Validation

The timezone field validates against PHP’s DateTimeZone class:

// Valid values
'America/Chicago'
'America/New_York'
'UTC'
'Europe/London'

// Invalid (will fail validation)
'CST'  // Abbreviations not accepted
'Invalid/Zone'

Business Rules

Email Uniqueness

Email addresses must be unique across the entire organization:

// This will fail if email already exists
$member1 = $this->Members->newEntity(['email_address' => 'user@example.com']);
$this->Members->save($member1); // Success

$member2 = $this->Members->newEntity(['email_address' => 'user@example.com']);
$result = $this->Members->save($member2); // Fails

if (!$result) {
    $errors = $member2->getError('email_address');
    // Contains uniqueness violation message
}

Automatic Processing

beforeSave Event

The beforeSave event automatically triggers two critical processes:

  1. Age-Up Review (ageUpReview()): Transitions minor members to adult status when they reach age 18
  2. Warrant Eligibility Review (warrantableReview()): Updates warrant eligibility based on current member data
// These processes run automatically on every save
$member = $this->Members->get($id);
$member->birth_year = 2006; // Member is now 18
$member->membership_expires_on = new Date('+1 year');

$this->Members->save($member);
// Automatically triggers:
// - ageUpReview(): May update status from minor to adult
// - warrantableReview(): Updates warrant eligibility

See Member Lifecycle for detailed documentation on these processes.

Static Methods

getValidationQueueCount()

Returns the number of members requiring validation processing.

$queueCount = MembersTable::getValidationQueueCount();

Validation Queue Criteria:

Members are included if they match ANY of these conditions:

Condition Description
Has membership_card_path Active members with uploaded membership cards awaiting verification
Status is UNVERIFIED_MINOR Minor members awaiting verification
Status is MINOR_MEMBERSHIP_VERIFIED Minor members with verified membership awaiting parent verification

Usage Example:

// Get current validation queue size
$queueCount = $this->Members->getValidationQueueCount();

// Display on admin dashboard
if ($queueCount > 0) {
    echo "Validation Queue: {$queueCount} members pending review";
}

// Use in batch processing
$batchSize = min($queueCount, 25);

Integration Points

System Integration
Authentication Primary identity source for login system
Authorization Role-based permission inheritance
Activities Plugin Member authorization management
Awards Plugin Member recognition and achievement tracking
Officers Plugin Leadership role management and reporting

Security Considerations