← Back to Awards Plugin

5.2.1 EventsTable API Reference

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

Overview

The EventsTable class manages award event data for ceremony coordination, temporal validation, and recommendation workflow integration. It handles event creation, temporal windows for recommendation processing, and integration with the awards lifecycle.

Class Definition

namespace Awards\Model\Table;

class EventsTable extends BaseTable

Database Table

Associations

BelongsTo

Association Foreign Key Join Type Class Name
Branches branch_id INNER Branches

HasMany

Association Foreign Key Join Type Class Name
RecommendationsToGive event_id LEFT Awards.Recommendations

BelongsToMany

Association Join Table Foreign Key Target Foreign Key Class Name
Recommendations awards_recommendations_events event_id recommendation_id Awards.Recommendations

Behaviors

Behavior Purpose
Timestamp Automatic created/modified field management
Muffin/Footprint.Footprint User attribution tracking (created_by/modified_by)
Muffin/Trash.Trash Soft deletion support via deleted field

Validation Rules

Field Validations

Field Rules
name Required, scalar, max 255 characters, not empty
description Required, scalar, max 255 characters, not empty
branch_id Required, integer, not empty
start_date Required on create, valid date, not empty
end_date Required on create, valid date, not empty
created_by Optional, integer
modified_by Optional, integer
deleted Optional, datetime

Business Rules

Rule Error Field Description
existsIn branch_id Branch must exist in Branches table

Methods

addBranchScopeQuery

Applies organizational access control by filtering events to authorized branches.

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

Parameters:

Returns: Modified query with branch filtering applied. Returns unmodified query if branch IDs array is empty.

Example:

$authorizedBranches = [1, 5, 12];
$query = $this->Events->find();
$query = $this->Events->addBranchScopeQuery($query, $authorizedBranches);

Entity Class

See Awards Plugin Overview for entity-level documentation.

Schema Reference

CREATE TABLE awards_events (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description VARCHAR(255) NOT NULL,
    branch_id INT NOT NULL,
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    created_by INT NULL,
    modified_by INT NULL,
    created DATETIME,
    modified DATETIME,
    deleted DATETIME NULL,
    FOREIGN KEY (branch_id) REFERENCES branches(id)
);