 |
Xataface 2.0
Xataface Application Framework
|
|
Xataface 2.0
Xataface Application Framework
|
Public Member Functions | |
| logRecord (&$record, $comments='', $lang=null, $state=null) | |
| logField (&$record, $fieldname, $history_id) | |
| logTableName ($tablename) | |
| updateHistoryTable ($tablename) | |
| createHistoryTable ($tablename) | |
| getDiffs ($tablename, $id1, $id2=null, $fieldname=null) | |
| getDiffsByDate (&$record, $date1, $date2=null, $lang=null, $fieldname=null) | |
| restore (&$record, $id, $fieldname=null) | |
| restoreField (&$record, &$old_record, $id, $fieldname) | |
| restoreToDate (&$record, $date, $lang=null, $fieldname=null) | |
| getPreviousVersion (&$record, $date, $lang=null, $fieldname=null, $idonly=false) | |
| getRecordById ($tablename, $id) | |
| getHistoryLog (&$record, $lang=null, $limit=100) | |
| findMatchingSnapshots ($record, $query, $idsOnly=true) | |
Data Fields | |
| $meta_fields | |
Manages the history of records. This class will record the state of each record in the database by copying it to a 'history' table. A separate history table is created for each table in the database.
In addition to storing all of the information in the subject table (the table that is being backed up), the history table stores the language of the record, the username of the user performing the update, some optional state information, a comments field and a modified timestamp to track when the record is from.
This class can be used to restore records to a previous state.
Usage:
$ht = new Dataface_HistoryTool(); $record = df_get_record('Profiles', array('id'=>10)); // get the profile with ID 10. $ht->restoreToDate($record, '2004-5-10'); // restores the record to the way it was on 2004-5-10
History tables are created to follow the following naming convention. The history table for the table named 'Foo' would be called 'Foo__history'. If Foo contains a container field whose files are saved in the folder /path/to/foo then their history files (the backups for the history table) will be stored in /path/to/foo/.dataface_history/ with the file name the same as the history id (The value of the history__id column for that entry.
History is automatically stored if the [history] section is present in the conf.ini file. If it is not, you can manually record the history for a record using the logRecord method as follows: $ht = new Dataface_HistoryTool(); $hid = $ht->logRecord($record); // $hid is the id of the history record.
$historyRecord = $ht->getRecordById($record->_table->tablename, $hid); // obtains the Dataface_Record for the corresponding record of the history // table. // $historyRecord and $record should contain nearly identical values, // except that $historyRecord contains extra history information // like timestamps etc.
You can obtain a previous version of a record without actually restoring the database record to that version using the getPreviousVersion() method: $historyTool = new Dataface_HistoryTool(); $record = df_get_record('Profiles', array('id'=>10)); $old_record = $ht->getPreviousVersion($record, '2004-10-10'); // Now $old_record is a Dataface_Record object for the "Profiles" table //representing the status of $record on 2004-10-10.
Definition at line 64 of file HistoryTool.php.
| createHistoryTable | ( | $ | tablename | ) |
Creates a history table corresponding to the given table.
| string | $tablename | The name of the table whose history table is to be created. |
Definition at line 288 of file HistoryTool.php.
| findMatchingSnapshots | ( | $ | record, |
| $ | query, | ||
| $ | idsOnly = true |
||
| ) |
Returns an array of history ids of history records that match the given query.
Definition at line 676 of file HistoryTool.php.
| getDiffs | ( | $ | tablename, |
| $ | id1, | ||
| $ | id2 = null, |
||
| $ | fieldname = null |
||
| ) |
Gets an HTML diff output between the records at $id1 and $id2 respectively, where $id1 and $id2 are history ids from the history__id column of the history table.
| string | $tablename | The name of the base table. |
| integer | $id1 | The id number of the first record (from the history__id column) |
| integer | $id2 | The id of the second record (from the history__id column) |
| string | $fieldname | Optional name of a field to return. |
Definition at line 335 of file HistoryTool.php.
| getDiffsByDate | ( | &$ | record, |
| $ | date1, | ||
| $ | date2 = null, |
||
| $ | lang = null, |
||
| $ | fieldname = null |
||
| ) |
Gets the changes for a given record between dates.
| Dataface_Record | &$record | The record we are checking for changes on. This is a record of the base table, and not its history table. |
| string | $date1 | The start date as an SQL date string (e.g. YYYY-MM-DD) |
| string | $date2 | The end date as an SQL date string (e.g. YYYY-MM-DD) |
| string | $lang | The 2-digit language code of the language we are using. |
| string | $fieldname | Optional fieldname |
Definition at line 392 of file HistoryTool.php.
| getHistoryLog | ( | &$ | record, |
| $ | lang = null, |
||
| $ | limit = 100 |
||
| ) |
Returns an array of the meta fields from the history table in descending order of modified date.
| Dataface_Record | &$record | The record we wish to obtain history for. |
| string | $lang | The 2-digit language code. |
| integer | $limit | The maximum number of records to return. null for unlimited. |
Definition at line 643 of file HistoryTool.php.
| getPreviousVersion | ( | &$ | record, |
| $ | date, | ||
| $ | lang = null, |
||
| $ | fieldname = null, |
||
| $ | idonly = false |
||
| ) |
Returns a previous version of the given record.
| Dataface_Record | &$record | The record whose previous version we are interested in. |
| string | $date | The MySQL date to obtain. Returns the most recent record on or before this date. (e.g. YYYY-MM-DD HH:MM:SS) |
| string | $fieldname | If we only want the previous version of a single field we can include it here. |
| boolean | $idonly | If this is set to true then only the history id of the appropriate record will be returned. |
Definition at line 576 of file HistoryTool.php.
| getRecordById | ( | $ | tablename, |
| $ | id | ||
| ) |
Obtains a record from the history table given the value in the history__id column.
| string | $tablename | The name of the base table. |
| integer | $id | The id (history__id column value). |
Definition at line 620 of file HistoryTool.php.
| logField | ( | &$ | record, |
| $ | fieldname, | ||
| $ | history_id | ||
| ) |
Performs extra logging steps for fields. This method is called by logRecord(). In particular for container fields, this will copy the container's files into the hidden .dataface_history subdirectory of the container field's save path.
| Dataface_Record | &$record | The record whose field is being logged. |
| string | $fieldname | The name of the field to perform extra steps for. |
| integer | $history_id | The id of the history record for the record that is being logged. |
Definition at line 166 of file HistoryTool.php.
| logRecord | ( | &$ | record, |
| $ | comments = '', |
||
| $ | lang = null, |
||
| $ | state = null |
||
| ) |
Backs up a record to the history table. This will automatically happen when using Dataface_IO::save() if the [history] section exists in the conf.ini file.
| Dataface_Record | &$record | The record that is being backed up. |
| string | $comments | Comments about this version to be stored. |
| string | $lang | The 2-digit language code of which language to use to back up this record. If none is specified then the current language of the system will be used. |
| integer | $state | Unused as yet. Was intended to store state/workflow information.. but .. |
Definition at line 94 of file HistoryTool.php.
| logTableName | ( | $ | tablename | ) |
Given a table name - this returns the name of the table's history table.
| string | $tablename | The name of the table whose history we want. |
Definition at line 226 of file HistoryTool.php.
| restore | ( | &$ | record, |
| $ | id, | ||
| $ | fieldname = null |
||
| ) |
Restores an old version of the given record, from the history table.
Definition at line 461 of file HistoryTool.php.
| restoreField | ( | &$ | record, |
| &$ | old_record, | ||
| $ | id, | ||
| $ | fieldname | ||
| ) |
Performs extra steps to restore particular fields. Any steps outside of copying the field values form the history table back to the main table. In particular container fields need to have their files copied back from the history subdirectory into the container field's save path.
| Dataface_Record | &$record | The record whose field we are restoring. |
| Dataface_Record | &$old_record | The record as is was before the restore. |
| integer | $id | The History id (The value in the history__id column) |
| string | $fieldname | The name of the field to restore. |
Definition at line 504 of file HistoryTool.php.
| restoreToDate | ( | &$ | record, |
| $ | date, | ||
| $ | lang = null, |
||
| $ | fieldname = null |
||
| ) |
Restores a record to a particular date.
| Dataface_Record | &$record | The record to be restored. |
| string | $date | The date to restore to as a MySQL date string (e.g. YYYY-MM-DD HH:MM:SS) |
| string | $lang | The 2-digit language code of the version to restore. |
| string | $fieldname | If we are only restoring a single field we include the name here. |
Definition at line 539 of file HistoryTool.php.
| updateHistoryTable | ( | $ | tablename | ) |
Updates the history table for a particular table so that it exists and contains all of the correct columns.
Definition at line 234 of file HistoryTool.php.
| $meta_fields |
array(
'history__id'=>array('Type'=>'int(11)', 'Extra'=>'auto_increment'),
'history__language'=> array('Type'=>'varchar(2)'),
'history__comments'=> array('Type'=>'text'),
'history__user'=>array('Type'=>'varchar(32)'),
'history__state'=>array('Type'=>'int(5)'),
'history__modified'=>array('Type'=>'datetime')
)
The fields that should appear in every history table.
Definition at line 69 of file HistoryTool.php.
1.7.4