5.2.3 RecommendationsStatesLogsTable API Reference
Last Updated: December 4, 2025
Status: Complete
Plugin: Awards
Source: plugins/Awards/src/Model/Table/RecommendationsStatesLogsTable.php
Overview
The RecommendationsStatesLogsTable class provides comprehensive audit trail management for recommendation state transitions within the Awards plugin. It implements detailed state change logging, accountability tracking, and timeline management for compliance monitoring and administrative oversight.
Class Definition
namespace Awards\Model\Table;
class RecommendationsStatesLogsTable extends BaseTable
Database Table
- Table Name:
awards_recommendations_states_logs - Display Field:
from_state - Primary Key:
id
Audit Trail Architecture
The table implements a comprehensive audit trail system:
- State Transition Logging: Before/after state tracking
- User Accountability: Creation tracking and administrative oversight
- Timeline Management: Automatic timestamp recording for audit compliance
- Immutable Records: No modification or deletion for compliance integrity
Associations
BelongsTo
| Association | Foreign Key | Join Type | Class Name |
|---|---|---|---|
| AwardsRecommendations | recommendation_id |
INNER | Awards.Recommendations |
Behaviors
| Behavior | Purpose |
|---|---|
| Timestamp | Automatic created timestamp (no modification tracking - immutable records) |
Note: No Trash behavior as audit records require permanent retention for compliance.
Validation Rules
Field Validations
| Field | Rules |
|---|---|
recommendation_id |
Required, integer, not empty |
from_state |
Required, scalar, max 255 characters, not empty |
to_state |
Required, scalar, max 255 characters, not empty |
created_by |
Optional, integer |
Business Rules
| Rule | Error Field | Description |
|---|---|---|
| existsIn | recommendation_id |
Recommendation must exist in AwardsRecommendations table |
Usage Examples
Automatic State Logging
State logging is triggered automatically through RecommendationsTable.afterSave():
// Automatic logging through RecommendationsTable integration
$recommendationsTable = TableRegistry::getTableLocator()->get('Awards.Recommendations');
$recommendation = $recommendationsTable->get($recommendationId);
// Set before state for logging
$recommendation->beforeState = $recommendation->state;
$recommendation->beforeStatus = $recommendation->status;
// Update state triggers automatic logging
$recommendation = $recommendationsTable->patchEntity($recommendation, [
'state' => 'approved',
'status' => 'approved',
'modified_by' => $userId
]);
$recommendationsTable->save($recommendation); // Triggers logStateChange()
Audit Trail Queries
// Get complete state history for recommendation
$stateLogsTable = TableRegistry::getTableLocator()->get('Awards.RecommendationsStatesLogs');
$stateHistory = $stateLogsTable->find()
->where(['recommendation_id' => $recommendationId])
->orderBy(['created' => 'ASC'])
->toArray();
// Recent state changes across all recommendations
$recentChanges = $stateLogsTable->find()
->contain(['AwardsRecommendations'])
->where(['created >=' => date('Y-m-d', strtotime('-7 days'))])
->orderBy(['created' => 'DESC'])
->toArray();
Administrative Reporting
// State transition analytics
$transitionCounts = $stateLogsTable->find()
->select([
'from_state',
'to_state',
'count' => $stateLogsTable->find()->func()->count('*')
])
->group(['from_state', 'to_state'])
->toArray();
// User activity audit trail
$userActivity = $stateLogsTable->find()
->where(['created_by' => $userId])
->contain(['AwardsRecommendations'])
->orderBy(['created' => 'DESC'])
->limit(50)
->toArray();
Compliance Monitoring
// Find recommendations with specific state transitions
$approvedRecommendations = $stateLogsTable->find()
->where([
'to_state' => 'approved',
'created >=' => $reportStartDate,
'created <=' => $reportEndDate
])
->contain(['AwardsRecommendations.Awards'])
->toArray();
Integration Points
Recommendation Workflow Integration
- Automatic state logging through
RecommendationsTable.afterSave()lifecycle hooks - Comprehensive state transition tracking for recommendation workflow management
- Administrative visibility for workflow monitoring and performance analytics
Audit Systems Integration
- Comprehensive audit trail for compliance monitoring and regulatory requirements
- Integration with administrative reporting systems
- Timeline tracking for workflow analytics
Member Management Integration
- User accountability tracking through creation user attribution
- Integration with member profiles for audit trail management
- Support for member-specific audit reporting
Administrative Reporting Integration
- State transition analytics for workflow performance monitoring
- Administrative dashboard integration for real-time visibility
- Export capabilities for external audit systems
Security Considerations
Data Integrity
- Immutable Records: Audit records cannot be modified after creation
- Permanent Retention: No soft deletion for compliance requirements
- Referential Integrity: Foreign key constraints with recommendations
Access Control
- Read-only access patterns for audit trail integrity
- Integration with authorization policies for access control
- Administrative oversight for visibility and compliance monitoring
Compliance Features
- Permanent retention of audit records
- Timeline tracking for documentation
- User accountability for administrative oversight
Schema Reference
CREATE TABLE awards_recommendations_states_logs (
id INT AUTO_INCREMENT PRIMARY KEY,
recommendation_id INT NOT NULL,
from_state VARCHAR(255) NOT NULL,
to_state VARCHAR(255) NOT NULL,
from_status VARCHAR(255) NULL,
to_status VARCHAR(255) NULL,
created_by INT NULL,
created DATETIME,
FOREIGN KEY (recommendation_id) REFERENCES awards_recommendations(id)
);