Horde_History_Sql
extends Horde_History
in package
The Horde_History_Sql class provides a method of tracking changes in Horde objects, stored in a SQL table.
Tags
Table of Contents
- $_auth : string
- The current user.
- $_cache : Horde_Cache
- Cache driver object.
- $_db : Horde_Db_Adapter
- Horde_Db_Adapter instance to manage the history.
- $_logger : Horde_Log_Logger
- Our log handler.
- __construct() : mixed
- Constructor.
- _getByTimestamp() : array<string|int, mixed>
- Finds history objects by timestamp, and optionally filtered on other fields as well.
- _getHistory() : Horde_History_Log
- Returns a Horde_History_Log corresponding to the named history entry, with the data retrieved appropriately.
- getActionModSeq() : int
- Gets the modseq of the most recent change to $guid
- getActionTimestamp() : int
- Returns the timestamp of the most recent change to $guid.
- getByModSeq() : array<string|int, mixed>
- Return history objects with changes during a modseq interval, and optionally filtered on other fields as well.
- getByTimestamp() : array<string|int, mixed>
- Finds history objects by timestamp, and optionally filter on other fields as well.
- getHighestModSeq() : int|bool
- Returns the current value of the modseq.
- getHistory() : Horde_History_Log
- Returns a Horde_History_Log corresponding to the named history entry, with the data retrieved appropriately.
- getLatestEntry() : array<string|int, mixed>|bool
- Returns the latest entry of $guid.
- log() : mixed
- Logs an event to an item's history log.
- removeByNames() : mixed
- Removes one or more history entries by name.
- removeByParent() : mixed
- Remove one or more history entries by parent.
- setCache() : mixed
- Set Cache object.
- setLogger() : null
- Set the log handler.
- _getByModSeq() : array<string|int, mixed>
- Returns history objects with changes during a modseq interval, and optionally filtered on other fields as well.
- _log() : mixed
- Logs an event to an item's history log.
- _nextModSeq() : int
- Increments, and returns, the modseq value.
Properties
$_auth
The current user.
protected
string
$_auth
$_cache
Cache driver object.
protected
Horde_Cache
$_cache
$_db
Horde_Db_Adapter instance to manage the history.
protected
Horde_Db_Adapter
$_db
$_logger
Our log handler.
protected
Horde_Log_Logger
$_logger
Methods
__construct()
Constructor.
public
__construct(string $auth, Horde_Db_Adapter $db) : mixed
Parameters
- $auth : string
-
The current user.
- $db : Horde_Db_Adapter
-
The database connection.
Return values
mixed —_getByTimestamp()
Finds history objects by timestamp, and optionally filtered on other fields as well.
public
_getByTimestamp(string $cmp, int $ts[, array<string|int, mixed> $filters = array() ][, string $parent = null ]) : array<string|int, mixed>
Note: For BC reasons, the results are returned keyed by the object UID, with a (fairly useless) history_id as the value. @todo This should be changed for Horde 6.
Parameters
- $cmp : string
-
The comparison operator (<, >, <=, >=, or =) to check the timestamps with.
- $ts : int
-
The timestamp to compare against.
- $filters : array<string|int, mixed> = array()
-
An array of additional (ANDed) criteria. Each array value should be an array with 3 entries:
- field: the history field being compared (i.e. 'action').
- op: the operator to compare this field with.
- value: the value to check for (i.e. 'add').
- $parent : string = null
-
The parent history to start searching at. If non-empty, will be searched for with a LIKE '$parent:%' clause.
Tags
Return values
array<string|int, mixed> —An array of history object ids that have had at least one match for the given $filters. Will return empty array if none matched the criteria. If the same GUID has multiple matches withing the range requested, there is no guarantee which entry will be returned.
_getHistory()
Returns a Horde_History_Log corresponding to the named history entry, with the data retrieved appropriately.
public
_getHistory(string $guid) : Horde_History_Log
Parameters
- $guid : string
-
The name of the history entry to retrieve.
Tags
Return values
Horde_History_Log —A Horde_History_Log object.
getActionModSeq()
Gets the modseq of the most recent change to $guid
public
getActionModSeq(string $guid, string $action) : int
Parameters
- $guid : string
-
The name of the history entry to retrieve.
- $action : string
-
An action: 'add', 'modify', 'delete', etc.
Tags
Return values
int —The modseq, or 0 if no matching entry is found.
getActionTimestamp()
Returns the timestamp of the most recent change to $guid.
public
getActionTimestamp(string $guid, string $action) : int
Parameters
- $guid : string
-
The name of the history entry to retrieve.
- $action : string
-
An action: 'add', 'modify', 'delete', etc.
Tags
Return values
int —The timestamp, or 0 if no matching entry is found.
getByModSeq()
Return history objects with changes during a modseq interval, and optionally filtered on other fields as well.
public
getByModSeq(int $start, int $end[, array<string|int, mixed> $filters = array() ][, string $parent = null ]) : array<string|int, mixed>
Parameters
- $start : int
-
The (exclusive) start of the modseq range.
- $end : int
-
The (inclusive) end of the modseq range.
- $filters : array<string|int, mixed> = array()
-
An array of additional (ANDed) criteria. Each array value should be an array with 3 entries:
- field: the history field being compared (i.e. 'action').
- op: the operator to compare this field with.
- value: the value to check for (i.e. 'add').
- $parent : string = null
-
The parent history to start searching at. If non-empty, will be searched for with a LIKE '$parent:%' clause.
Return values
array<string|int, mixed> —An array of history object ids, or an empty array if none matched the criteria.
getByTimestamp()
Finds history objects by timestamp, and optionally filter on other fields as well.
public
getByTimestamp(string $cmp, int $ts[, array<string|int, mixed> $filters = array() ][, string $parent = null ]) : array<string|int, mixed>
Parameters
- $cmp : string
-
The comparison operator (<, >, <=, >=, or =) to check the timestamps with.
- $ts : int
-
The timestamp to compare against.
- $filters : array<string|int, mixed> = array()
-
An array of additional (ANDed) criteria. Each array value should be an array with 3 entries:
- field: the history field being compared (i.e. 'action').
- op: the operator to compare this field with.
- value: the value to check for (i.e. 'add').
- $parent : string = null
-
The parent history to start searching at. If non-empty, will be searched for with a LIKE '$parent:%' clause.
Tags
Return values
array<string|int, mixed> —An array of history object ids, or an empty array if none matched the criteria.
getHighestModSeq()
Returns the current value of the modseq.
public
getHighestModSeq([string $parent = null ]) : int|bool
We take the MAX of the horde_histories table instead of the value of the horde_histories_modseq table to ensure we never miss an entry if we query the history system between the time we call nextModSeq() and the time the new entry is written.
Parameters
- $parent : string = null
-
Restrict to entries a specific parent.
Tags
Return values
int|bool —The highest used modseq value, false if no history.
getHistory()
Returns a Horde_History_Log corresponding to the named history entry, with the data retrieved appropriately.
public
getHistory(string $guid) : Horde_History_Log
Parameters
- $guid : string
-
The name of the history entry to retrieve.
Tags
Return values
Horde_History_Log —A Horde_History_Log object.
getLatestEntry()
Returns the latest entry of $guid.
public
getLatestEntry(string $guid[, bool $use_ts = false ]) : array<string|int, mixed>|bool
Parameters
- $guid : string
-
The name of the history entry to retrieve.
- $use_ts : bool = false
-
If false we use the 'modseq' field to determine the latest entry. If true we use the timestamp instead of modseq to determine the latest entry. Note: Only 'modseq' can give a definitive answer.
Tags
Return values
array<string|int, mixed>|bool —The latest history entry, or false if $guid does not exist.
log()
Logs an event to an item's history log.
public
log(string $guid[, array<string|int, mixed> $attributes = array() ][, bool $replaceAction = false ]) : mixed
The item must be uniquely identified by $guid. Any other details about the event are passed in $attributes. Standard suggested attributes are:
- who: The id of the user that performed the action (will be added automatically if not present).
- ts: Timestamp of the action (this will be added automatically if it is not present).
Parameters
- $guid : string
-
The unique identifier of the entry to add to.
- $attributes : array<string|int, mixed> = array()
-
The hash of name => value entries that describe this event.
- $replaceAction : bool = false
-
If $attributes['action'] is already present in the item's history log, update that entry instead of creating a new one.
Tags
Return values
mixed —removeByNames()
Removes one or more history entries by name.
public
removeByNames(array<string|int, mixed> $names) : mixed
Parameters
- $names : array<string|int, mixed>
-
The history entries to remove.
Tags
Return values
mixed —removeByParent()
Remove one or more history entries by parent.
public
removeByParent(string $parent) : mixed
Parameters
- $parent : string
-
The parent name to remove.
Tags
Return values
mixed —setCache()
Set Cache object.
public
setCache(Horde_Cache $cache) : mixed
Parameters
- $cache : Horde_Cache
-
The cache instance.
Tags
Return values
mixed —setLogger()
Set the log handler.
public
setLogger(Horde_Log_Logger $logger) : null
Parameters
- $logger : Horde_Log_Logger
-
The log handler.
Return values
null —_getByModSeq()
Returns history objects with changes during a modseq interval, and optionally filtered on other fields as well.
protected
_getByModSeq(int $start, int $end[, array<string|int, mixed> $filters = array() ][, string $parent = null ]) : array<string|int, mixed>
Note: For BC reasons, the results are returned keyed by the object UID, with a (fairly useless) history_id as the value. @todo This should be changed for Horde 6.
Parameters
- $start : int
-
The (exclusive) start of the modseq range.
- $end : int
-
The (inclusive) end of the modseq range.
- $filters : array<string|int, mixed> = array()
-
An array of additional (ANDed) criteria. Each array value should be an array with 3 entries:
- field: the history field being compared (i.e. 'action').
- op: the operator to compare this field with.
- value: the value to check for (i.e. 'add').
- $parent : string = null
-
The parent history to start searching at. If non-empty, will be searched for with a LIKE '$parent:%' clause.
Return values
array<string|int, mixed> —An array of history object ids that have had at least one match for the given $filters. Will return empty array if none matched the criteria. If the same GUID has multiple matches withing the range requested, there is no guarantee which entry will be returned.
_log()
Logs an event to an item's history log.
protected
_log(Horde_History_Log $history, array<string|int, mixed> $attributes[, bool $replaceAction = false ]) : mixed
Any other details about the event are passed in $attributes.
Parameters
- $history : Horde_History_Log
-
The history item to add to.
- $attributes : array<string|int, mixed>
-
The hash of name => value entries that describe this event.
- $replaceAction : bool = false
-
If $attributes['action'] is already present in the item's history log, update that entry instead of creating a new one.
Tags
Return values
mixed —_nextModSeq()
Increments, and returns, the modseq value.
protected
_nextModSeq() : int
Tags
Return values
int —The new modseq value.