Documentation

Horde_History_Sql extends Horde_History

The Horde_History_Sql class provides a method of tracking changes in Horde objects, stored in a SQL table.

Tags
author

Chuck Hagenbuch chuck@horde.org

category

Horde

copyright

2003-2017 Horde LLC

license

http://www.horde.org/licenses/lgpl21 LGPL 2.1

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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
since
2.1.0
todo

Make abstract in H6.

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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
since
2.2.0
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
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
throws
Horde_History_Exception
Return values
mixed

setCache()

Set Cache object.

public setCache(Horde_Cache $cache) : mixed
Parameters
$cache : Horde_Cache

The cache instance.

Tags
since
2.1.0
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
throws
Horde_History_Exception
Return values
mixed

_nextModSeq()

Increments, and returns, the modseq value.

protected _nextModSeq() : int
Tags
throws
Horde_History_Exception
Return values
int

The new modseq value.

Search results