← Back to Awards Plugin

5.2.4 RecommendationsTable API Reference

Last Updated: December 4, 2025
Status: Complete
Plugin: Awards
Source: plugins/Awards/src/Model/Table/RecommendationsTable.php

Overview

The RecommendationsTable class provides comprehensive data management for award recommendations within the Awards plugin. It implements a complex state machine, workflow management, and extensive association relationships for managing the complete recommendation lifecycle from submission through approval to award presentation.

Class Definition

namespace Awards\Model\Table;

class RecommendationsTable extends BaseTable

Database Table

State Machine Integration

The table implements a sophisticated state machine for recommendation workflow:

Associations

BelongsTo

Association Foreign Key Join Type Class Name Description
Requesters requester_id LEFT Members Recommendation submitter
Members member_id LEFT Members Recommended member
ScheduledEvent event_id LEFT Awards.Events Scheduled event
AssignedEvent event_id LEFT Awards.Events Ceremony assignment
AssignedGathering gathering_id LEFT Gatherings Gathering assignment
Branches branch_id - Branches Organizational scope
Awards award_id INNER Awards.Awards Required award

BelongsToMany

Association Join Table Foreign Key Target Foreign Key Class Name
Events awards_recommendations_events recommendation_id event_id Awards.Events
Gatherings awards_recommendations_events recommendation_id gathering_id Gatherings

HasMany

Association Foreign Key Class Name Conditions
Notes entity_id Notes entity_type = 'Awards.Recommendations'
RecommendationStateLogs recommendation_id Awards.RecommendationsStatesLog -

Behaviors

Behavior Configuration Purpose
Timestamp - Automatic created/modified field management
Muffin/Footprint.Footprint - User attribution tracking
Muffin/Trash.Trash - Soft deletion support
Sortable field: 'stack_rank' Stack ranking for prioritization

Validation Rules

Field Validations

Field Rules
requester_id Optional, integer
member_id Optional, integer
branch_id Optional, integer
award_id Required, integer, not empty
requester_sca_name Required, scalar, max 255 characters, not empty
member_sca_name Required, scalar, max 255 characters, not empty
contact_email Required, scalar, max 255 characters, not empty
contact_number Optional, scalar, max 100 characters
reason Required, scalar, max 10,000 characters, not empty
created_by Optional, integer
modified_by Optional, integer
deleted Optional, datetime
given Optional, date

Business Rules

Rule Error Field Description
existsIn requester_id Requester must exist in Members table
existsIn member_id Member must exist in Members table
existsIn branch_id Branch must exist in Branches table
existsIn award_id Award must exist in Awards table

Methods

afterSave

Lifecycle hook that detects state changes and triggers audit logging.

public function afterSave($created, $entity, $options): void

Monitors the state field for changes and calls logStateChange() when transitions occur.

logStateChange

Creates audit trail records for state transitions.

protected function logStateChange($entity): void

Records:

addBranchScopeQuery

Applies branch-based filtering to queries.

public function addBranchScopeQuery(SelectQuery $query, array $branchIDs): SelectQuery

Parameters:

Returns: Query filtered to awards within specified branches.

Usage Examples

Recommendation Submission

$recommendationsTable = TableRegistry::getTableLocator()->get('Awards.Recommendations');
$recommendation = $recommendationsTable->newEmptyEntity();
$recommendation = $recommendationsTable->patchEntity($recommendation, [
    'requester_sca_name' => 'Duke John',
    'member_sca_name' => 'Lady Jane',
    'contact_email' => 'duke.john@example.com',
    'award_id' => 1,
    'reason' => 'Outstanding service to the realm...',
    'state' => 'submitted',
    'status' => 'pending'
]);

if ($recommendationsTable->save($recommendation)) {
    // State change automatically logged
}

State Transition Processing

$recommendation = $recommendationsTable->get($recommendationId);
$recommendation->beforeState = $recommendation->state;
$recommendation->beforeStatus = $recommendation->status;

$recommendation = $recommendationsTable->patchEntity($recommendation, [
    'state' => 'approved',
    'status' => 'approved',
    'modified_by' => $userId
]);

$recommendationsTable->save($recommendation); // Triggers automatic logging

Workflow Processing

// Find recommendations for processing
$pendingRecommendations = $recommendationsTable->find()
    ->where(['state' => 'submitted'])
    ->contain(['Awards', 'Members', 'Requesters'])
    ->orderBy(['created' => 'ASC'])
    ->toArray();

// Event assignment processing
$eventRecommendations = $recommendationsTable->find()
    ->innerJoinWith('Events')
    ->where(['Events.start_date <=' => date('Y-m-d')])
    ->where(['Events.end_date >=' => date('Y-m-d')])
    ->toArray();

Administrative Operations

// Branch-scoped recommendation discovery
$branchRecommendations = $recommendationsTable->find()
    ->innerJoinWith('Awards.Branches')
    ->where(['Awards.branch_id IN' => $authorizedBranchIds])
    ->contain(['RecommendationStateLogs'])
    ->toArray();

// Sortable stack ranking
$recommendationsTable->moveUp($recommendation, 3);
$recommendationsTable->moveDown($recommendation, 1);

Integration Points

Awards System Integration

Event Management Integration

State Logging Integration

Member Management Integration

Security Considerations

Data Integrity

Access Control

Schema Reference

CREATE TABLE awards_recommendations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    requester_id INT NULL,
    member_id INT NULL,
    branch_id INT NULL,
    award_id INT NOT NULL,
    event_id INT NULL,
    gathering_id INT NULL,
    requester_sca_name VARCHAR(255) NOT NULL,
    member_sca_name VARCHAR(255) NOT NULL,
    contact_email VARCHAR(255) NOT NULL,
    contact_number VARCHAR(100) NULL,
    reason TEXT NOT NULL,
    state VARCHAR(50),
    status VARCHAR(50),
    stack_rank INT NULL,
    given DATE NULL,
    created_by INT NULL,
    modified_by INT NULL,
    created DATETIME,
    modified DATETIME,
    deleted DATETIME NULL,
    FOREIGN KEY (requester_id) REFERENCES members(id),
    FOREIGN KEY (member_id) REFERENCES members(id),
    FOREIGN KEY (branch_id) REFERENCES branches(id),
    FOREIGN KEY (award_id) REFERENCES awards_awards(id),
    FOREIGN KEY (event_id) REFERENCES awards_events(id)
);