 |
VOOZH | about |
|
VOOZH | about |
This page documents the RevisionController, which provides GraphQL operations for querying and restoring historical changes tracked by the automatic audit system. The controller enables clients to retrieve complete revision history for any model instance and selectively restore previous field values.
For information about how the audit system automatically logs changes, see Auto-Auditing and Lifecycle Hooks. For the EventLog table structure and revision tracking implementation, see Revision System.
Sources: src/Controller/RevisionController.php1-44
The RevisionController provides GraphQL operations for querying and restoring historical changes tracked by the automatic audit system. It allows clients to retrieve revision history for any model instance and selectively restore previous field values.
Sources: src/Controller/RevisionController.php1-44
The revision system consists of three primary components that work together to provide comprehensive audit trail functionality:
The RevisionController exposes two GraphQL operations that wrap the Revision type, which in turn reads from the EventLog table. All models extending Light\Model automatically write to EventLog on every insert, update, and delete operation.
Sources: src/Controller/RevisionController.php12-43 src/Type/Revision.php12-119 src/Model.php120-238
Retrieves all revision history for a specific model instance, sorted by creation time in descending order (most recent first).
GraphQL Schema:
Parameters:
| Parameter | Type | Description |
|---|---|---|
model_class | string | Fully qualified class name (e.g., "Light\\Model\\User") |
model_id | int | Primary key value of the model instance |
Authorization:
revision.read permission@Logged annotation)Implementation Details:
The query filters EventLog entries by both class and id, then sorts by created_time in descending order src/Controller/RevisionController.php35-37 Each EventLog entry is wrapped in a Revision type for GraphQL exposure src/Controller/RevisionController.php39-41
Sources: src/Controller/RevisionController.php29-42
Restores specific fields from a historical revision to the current model instance. This allows selective rollback without reverting the entire record.
GraphQL Schema:
Parameters:
| Parameter | Type | Description |
|---|---|---|
revision_id | int | The EventLog ID to restore from |
fields | string[] | Array of field names to restore |
Authorization:
revision.restore permission@Logged annotation)Behavior:
EventLog entry by revision_id src/Controller/RevisionController.php23Revision wrapper src/Controller/RevisionController.php24retoreFields() with the specified fields src/Controller/RevisionController.php24Sources: src/Controller/RevisionController.php15-25 src/Type/Revision.php27-43
The Revision type provides three different perspectives on change history, each optimized for different use cases:
Returns the complete snapshot of the model's state at the time of the revision.
Field: content
Returns: Mixed (object) - Complete field-value pairs sorted by key
Use Case: Viewing the full state of a model at a specific point in time
Implementation: Retrieves the source field from the EventLog entry, which contains the pre-change state src/Type/Revision.php66 and sorts fields alphabetically for consistent output src/Type/Revision.php68
Sources: src/Type/Revision.php63-70
Returns only the fields that changed, showing their new values after the change.
Field: delta
Returns: Mixed (object) - Only changed field-value pairs
Use Case: Efficiently viewing what changed in an update operation
Implementation: Compares source and target objects field-by-field src/Type/Revision.php79-82 building a delta object containing only fields where values differ. Both objects are sanitized before comparison src/Type/Revision.php75-76
Sources: src/Type/Revision.php72-87
Returns human-readable unified diff format showing before/after changes for each field.
Field: diff
Returns: Mixed (object) - Field names mapped to unified diff strings
Use Case: Displaying changes in a code-review style format for complex fields
Implementation: Uses sebastian/diff library to generate unified diff output src/Type/Revision.php97-106 for each changed field. Handles both scalar values and JSON-encoded arrays src/Type/Revision.php110-114
Sources: src/Type/Revision.php89-118
The revision system is automatically populated by the base Light\Model class. Every model extending this class generates EventLog entries without any explicit instrumentation.
Automatic Tracking:
| Operation | Source | Target | Timestamps Updated |
|---|---|---|---|
| Insert | null | New record JSON | created_time, created_by |
| Update | Original record JSON | Modified record JSON | updated_time, updated_by |
| Delete | null | Deleted record JSON | None |
User Attribution:
The system automatically captures the current user ID from the Auth\Service container src/Model.php126-129 and associates it with the audit log entry src/Model.php137 src/Model.php233
Blob Field Filtering:
To prevent storing large binary data in audit logs, the system filters out fields with blob data types (longblob, mediumblob, tinyblob) before JSON encoding src/Model.php179-185 src/Model.php204-209
Sources: src/Model.php120-238
The Revision type provides metadata about each change:
Fields:
| Field | Type | Description |
|---|---|---|
revision_id | Int! | The EventLog primary key identifier |
createdTime | String! | ISO 8601 timestamp when the change occurred |
revisionBy | String | Display name of the user who made the change (null if system) |
User Resolution:
The revisionBy field performs a join to the User table to resolve the user ID to a display name src/Type/Revision.php54-58 Returns null if the user_id is not set or the user no longer exists.
Sources: src/Type/Revision.php45-61
Both operations in the RevisionController enforce security through GraphQLite annotations:
Permission Requirements:
| Operation | Permission | Scope |
|---|---|---|
getRevisionsByModel | revision.read | Read access to revision history |
restoreRevision | revision.restore | Write access to restore changes |
Authentication:
Both operations require authentication via the @Logged annotation src/Controller/RevisionController.php16 src/Controller/RevisionController.php29 which validates the JWT token before execution.
Authorization:
The @Right annotation enforces permission checks through the RBAC system src/Controller/RevisionController.php20 src/Controller/RevisionController.php31 For more details on permission configuration, see Role Hierarchy and Permissions.
Sources: src/Controller/RevisionController.php15-32
The complete GraphQL schema for the Revision type:
Note: The Mixed type represents arbitrary JSON data. The content, delta, and diff fields return objects with field names as keys and values matching the field types of the underlying model.
Sources: src/Type/Revision.php12-119
Returns a chronological list of changes to User #42, showing only what changed in each revision.
Restores the email and status fields from revision 1234 to the current model instance, leaving other fields unchanged.
Returns full snapshots and diffs for all changes to Config #5, useful for detailed audit review.
Sources: src/Controller/RevisionController.php1-44 src/Type/Revision.php1-119
Refresh this wiki