Documentation

Horde_History

The Horde_History class provides methods of tracking changes in Horde objects.

Tags
author

Chuck Hagenbuch chuck@horde.org

author

Gunnar Wrobel wrobel@pardus.de

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.
$_logger  : Horde_Log_Logger
Our log handler.
__construct()  : mixed
Constructor.
_getByTimestamp()  : array<string|int, mixed>
Finds history objects by timestamp, and optionally filter 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
Gets 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
Return the maximum modification sequence. To be overridden in concrete class.
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
Gets 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.
_log()  : mixed
Logs an event to an item's history log. Any other details about the event are passed in $attributes.

Properties

$_auth

The current user.

protected string $_auth

$_cache

Cache driver object.

protected Horde_Cache $_cache

$_logger

Our log handler.

protected Horde_Log_Logger $_logger

Methods

__construct()

Constructor.

public __construct(string $auth) : mixed
Parameters
$auth : string

The current user.

Return values
mixed

_getByTimestamp()

Finds history objects by timestamp, and optionally filter on other fields as well.

public abstract _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
todo

Make protected.

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.

_getHistory()

Returns a Horde_History_Log corresponding to the named history entry, with the data retrieved appropriately.

public abstract _getHistory(string $guid) : Horde_History_Log
Parameters
$guid : string

The name of the history entry to retrieve.

Tags
todo

Make protected.

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()

Gets 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()

Return the maximum modification sequence. To be overridden in concrete class.

public getHighestModSeq([string $parent = null ]) : int
Parameters
$parent : string = null

Restrict to entries a specific parent.

Tags
since
2.1.0
todo

Make abstract in H6. Need to make this non-abstract for BC.

Return values
int

The modseq

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()

Gets 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 abstract 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

_log()

Logs an event to an item's history log. Any other details about the event are passed in $attributes.

protected abstract _log(Horde_History_Log $history, array<string|int, mixed> $attributes[, bool $replaceAction = false ]) : mixed
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

Search results