[commits] [Wiki] created: Doc/Dev/HordeHistory

[Ralf Lang (B1 Systems GmbH)]

rlang  Thu, 12 Apr 2018 14:26:39 +0000

Created page: https://wiki.horde.org/Doc/Dev/HordeHistory

[[toc]]

+ Horde_History

Horde_History is a library to track and find change events for  
arbitrary resources. Histories can be saved to SQL or MongoDb, a  
Composite backend also exists.
Possible use cases are sync protocols, undo/rewind features or human  
consumable history information. The Horde_Activesync implementation  
uses Horde_Histories to track create/delete/update events of syncable  
items.

++ General Usage
Create an implementation of the Horde_History class and fulfill its  
dependencies
<code>$history = new Horde_History_Sql($username, Horde_Db_Adapter  
$db);</code>

Log events related to a $guid identifying the resource tracked
<code>
$history->log('room1:shelf1:item100', array(
         'who' => 'someuser', // defaults to the user provided at  
construction of the object
         'action' => 'create',
    ));

$history->log('room1:shelf1:item100', array(
         'who' => 'someotheruser', // defaults to the user provided at  
construction of the object
         'action' => 'modify',
         'ts' => 1287666089, // Defaults to now,
         'desc' => 'Human Readble Description'
    ));

$history->log('room1:shelf1:item100', array('action' => 'delete'));
</code>

Retrieve the whole history of some guid
<code>
$log = $history->getHistory("room1:shelf1:item100"); // returns a  
Horde_History_Log object
</code>

Retrieve the list of history items compared to a certain timestamp

<code>
$ids = $history->getByTimestamp('>=', 1287666089); // returns an array  
of integers
</code>

Or add filters
<code>
$ids = $history->getByTimestamp('>=', 1287666089, array(
     array('action', '==', 'delete')
     )
); // returns an array of integers
</code>


Get events between some changesets, allowing filters

<code>
$ids = $history->getByModSeq(1287, 1305);
); // returns an array of integers

$ids = $history->getByModSeq(1287, 1305, array(array('action', '==',  
'create')));
); // returns an array of integers
</code>

Limit to events within a parent resource
<code>
$ids = $history->getByModSeq(12876, 1305, array(), 'room1:shelf1');
); // returns an array of integers

$ids = $history->getByModSeq(12876, 1305, array(array('action', '==',  
'create')), 'room1:shelf1');
); // returns an array of integers
</code>

Get the last time a certain action happened to a resource

<code>
$ts = $history->getActionTimestamp('room1:shelf1', 'createitem');
</code>

Remove all histories for a certain parent guid, for example because a  
collection gets deleted

<code>
$history->removeByParent('room12');
</code>

Or remove a list of guids from history (not including child resources)

<code>
$history->removeByNames(array('room12:shelf1', 'room12:shelf2',  
'room12:shelf3'));
</code>

Get the last change to any child guid below a parent guid
<code>
$modseq = $history->getHighestModSeq('room1');
</code>

Get the latest entry for a guid by modseq
<code>
$entry = $history->getLatestEntry('room1');
</code>

or by timestamp
<code>
$entry = $history->getLatestEntry('room1', true);
</code>


++ Usage inside Horde applications

Use the Injector to get a configured instance of Horde_Core_History.

<code>$history = $GLOBALS['injector']->getInstance('Horde_History');</code>

Horde_Core_History wraps Horde_History instances. It defaults to the  
logged in user and delegates most calls to the actual backends.



----
Back to the ((Project|Project List)