← Back to Awards Plugin

5.2.2 LevelsTable API Reference

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

Overview

The LevelsTable class provides comprehensive data management for award levels within the Awards plugin, implementing a hierarchical precedence system that organizes awards into distinct levels with clear ordering and organizational structure.

Class Definition

namespace Awards\Model\Table;

class LevelsTable extends BaseTable

Database Table

• Table Name: awards_levels
• Display Field: name
• Primary Key: id

Hierarchical Organization

The LevelsTable implements a hierarchical system where each level represents a distinct tier in the award progression system:

• Progression Ordering: Through progression_order field for hierarchical ranking
• Unique Level Names: Ensuring clear organizational identity
• Hierarchical Precedence: Management for award ranking and progression
• Administrative Oversight: For level configuration and management

Associations

HasMany

Association	Foreign Key	Class Name	Description
Awards	level_id	Awards.Awards	Links levels to multiple awards for hierarchical organization

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, must be unique
progression_order	Optional, integer
created_by	Optional, integer
modified_by	Optional, integer
deleted	Optional, datetime

Business Rules

Rule	Error Field	Description
isUnique	name	Level names must be unique system-wide

Methods

getAllLevelNames

Retrieves all award level names ordered by progression for hierarchical display.

public function getAllLevelNames(): array

Returns: Array of level names in hierarchical progression order.

Query Details:

• Selects only the name field for efficient data retrieval
• Excludes soft-deleted levels (deleted IS NULL)
• Orders by progression_order ascending

Usage Examples

Basic Level Creation

// Create a new award level
$levelsTable = TableRegistry::getTableLocator()->get('Awards.Levels');
$level = $levelsTable->newEmptyEntity();
$level = $levelsTable->patchEntity($level, [
    'name' => 'Knight',
    'progression_order' => 3
]);

if ($levelsTable->save($level)) {
    // Level created successfully
}

Hierarchy Management

// Retrieve all levels in progression order
$levels = $levelsTable->find()
    ->where(['deleted IS' => null])
    ->orderBy(['progression_order' => 'ASC'])
    ->toArray();

// Get level names for organizational display
$levelNames = $levelsTable->getAllLevelNames();

Administrative Operations

// Update level progression order
$level = $levelsTable->get($levelId);
$level = $levelsTable->patchEntity($level, [
    'progression_order' => $newOrder
]);
$levelsTable->save($level);

// Soft delete level with referential integrity protection
$levelsTable->delete($level); // Uses Trash behavior

Precedence Analytics

// Find awards by level precedence
$awards = $levelsTable->Awards->find()
    ->innerJoinWith('Levels')
    ->orderBy(['Levels.progression_order' => 'ASC'])
    ->toArray();

Administrative Interface Population

// Populate dropdown for award creation forms
$levelNames = $levelsTable->getAllLevelNames();
$this->set('levelOptions', array_combine($levelNames, $levelNames));

Reporting Integration

// Generate level-based reports
$levelNames = $levelsTable->getAllLevelNames();
$reportData = [];
foreach ($levelNames as $levelName) {
    $reportData[$levelName] = $this->generateLevelStatistics($levelName);
}

Integration Points

Awards Management System

• Level assignment to awards through foreign key relationships
• Hierarchical award organization and progression tracking
• Administrative level configuration and management interfaces
• Integration with award creation and modification workflows

Domain System Integration

• Coordination with domains for complete organizational structure
• Support for domain-level precedence and hierarchical organization
• Integration with administrative domain management interfaces
• Cross-reference support for reporting and analytics systems

Reporting System Integration

• Level-based award reporting and analytics capabilities
• Hierarchical data aggregation for statistical reporting
• Administrative dashboard integration for level management oversight
• Export capabilities for external reporting and analysis systems

Administrative Interface Integration

• Administrative level management through dedicated controllers
• Form integration for level creation, modification, and deletion
• Navigation integration with Awards plugin administrative interfaces
• Authorization integration through policy-based access control

Security Considerations

Data Integrity

• Validation rules ensuring level name uniqueness and organizational consistency
• Soft deletion preventing data loss while maintaining organizational integrity
• Audit trail support through Footprint behavior for accountability tracking

Access Control

• Integration with authorization policies for administrative access control
• Permission-based level management and configuration capabilities
• Administrative oversight for level creation, modification, and deletion

Schema Reference

CREATE TABLE awards_levels (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE,
    progression_order INT NULL,
    created_by INT NULL,
    modified_by INT NULL,
    created DATETIME,
    modified DATETIME,
    deleted DATETIME NULL
);

Related Documentation

• Awards Plugin Overview
• Award Hierarchy Management
• Domains Table Policy Reference
• Model Behaviors