source: trunk/lib/Version.inc.php @ 502

Last change on this file since 502 was 502, checked in by anonymous, 9 years ago

Many minor fixes during pulso development
File size: 19.8 KB
Line 
1<?php
2/**
3 * The Strangecode Codebase - a general application development framework for PHP
4 * For details visit the project site: <http://trac.strangecode.com/codebase/>
5 * Copyright 2001-2012 Strangecode, LLC
6 *
7 * This file is part of The Strangecode Codebase.
8 *
9 * The Strangecode Codebase is free software: you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as published by the
11 * Free Software Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * The Strangecode Codebase is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
17 * details.
18 *
19 * You should have received a copy of the GNU General Public License along with
20 * The Strangecode Codebase. If not, see <http://www.gnu.org/licenses/>.
21 */
22
23/**
24 * Version.inc.php
25 *
26 * The Version class provides a system for saving, reviewing, and
27 * restoring versions of a record of any DB table. All the data in the record is
28 * serialized, compressed, and saved in a blob in the version_tbl. Restoring a
29 * version simply does a REPLACE INTO of the data. It is very simple, and works
30 * with multiple database tables, but the drawback is that relationships for
31 * a record cannot be retained. For example, an article from an article_tbl can
32 * be saved, but not categories associated to the record in a category_article_tbl.
33 * The restored article will simple retain the relationships that the previous
34 * current article had.
35 *
36 * @author  Quinn Comendant <quinn@strangecode.com>
37 * @version 2.1
38 */
39class Version
40{
41
42    // A place to keep an object instance for the singleton pattern.
43    protected static $instance = null;
44
45    // Configuration of this object.
46    protected $_params = array(
47        'max_qty' => 100, // Never have more than this many versions of each record.
48        'min_qty' => 25, // Keep at least this many versions of each record.
49        'min_days' => 7, // Keep ALL versions within this many days, even if MORE than min_qty.
50        'db_table' => 'version_tbl',
51
52        // Automatically create table and verify columns. Better set to false after site launch.
53        // This value is overwritten by the $app->getParam('db_create_tables') setting if it is available.
54        'create_table' => true,
55        // If true, makes an exact comparison of saved vs. live table schemas. If false, just checks that the saved columns are available.
56        'db_schema_strict' => true,
57    );
58
59    // Auth_SQL object from which to access a current user_id.
60    protected $_auth;
61
62    /**
63     * This method enforces the singleton pattern for this class.
64     *
65     * @return  object  Reference to the global Lock object.
66     * @access  public
67     * @static
68     */
69    public static function &getInstance($auth_object)
70    {
71        if (self::$instance === null) {
72            self::$instance = new self($auth_object);
73        }
74
75        return self::$instance;
76    }
77
78    /**
79     * Constructor. Pass an Auth object on which to perform user lookups.
80     *
81     * @param mixed  $auth_object  An Auth_SQL object.
82     */
83    public function __construct($auth_object)
84    {
85        $app =& App::getInstance();
86
87        if (!method_exists($auth_object, 'get') || !method_exists($auth_object, 'getUsername')) {
88            trigger_error('Constructor not provided a valid Auth_* object.', E_USER_ERROR);
89        }
90
91        $this->_auth = $auth_object;
92
93        // Get create tables config from global context.
94        if (!is_null($app->getParam('db_create_tables'))) {
95            $this->setParam(array('create_table' => $app->getParam('db_create_tables')));
96        }
97    }
98
99    /**
100     * Setup the database table for this class.
101     *
102     * @access  public
103     * @author  Quinn Comendant <quinn@strangecode.com>
104     * @since   26 Aug 2005 17:09:36
105     */
106    public function initDB($recreate_db=false)
107    {
108        $app =& App::getInstance();
109        $db =& DB::getInstance();
110
111        static $_db_tested = false;
112
113        if ($recreate_db || !$_db_tested && $this->getParam('create_table')) {
114            if ($recreate_db) {
115                $db->query("DROP TABLE IF EXISTS " . $this->getParam('db_table'));
116                $app->logMsg(sprintf('Dropping and recreating table %s.', $this->getParam('db_table')), LOG_INFO, __FILE__, __LINE__);
117            }
118            $db->query("CREATE TABLE IF NOT EXISTS " . $db->escapeString($this->getParam('db_table')) . " (
119                version_id INT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
120                record_table VARCHAR(255) NOT NULL DEFAULT '',
121                record_key VARCHAR(255) NOT NULL DEFAULT '',
122                record_val VARCHAR(255) NOT NULL DEFAULT '',
123                version_data MEDIUMBLOB NOT NULL,
124                version_title VARCHAR(255) NOT NULL DEFAULT '',
125                version_number SMALLINT(11) UNSIGNED NOT NULL DEFAULT '0',
126                version_notes VARCHAR(255) NOT NULL DEFAULT '',
127                saved_by_user_id SMALLINT(11) NOT NULL DEFAULT '0',
128                version_datetime DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
129                KEY record_table (record_table),
130                KEY record_key (record_key),
131                KEY record_val (record_val)
132            )");
133
134            if (!$db->columnExists($this->getParam('db_table'), array(
135                'version_id',
136                'record_table',
137                'record_key',
138                'record_val',
139                'version_data',
140                'version_title',
141                'version_number',
142                'version_notes',
143                'saved_by_user_id',
144                'version_datetime',
145            ), false, false)) {
146                $app->logMsg(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), LOG_ALERT, __FILE__, __LINE__);
147                trigger_error(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), E_USER_ERROR);
148            }
149        }
150        $_db_tested = true;
151    }
152
153    /**
154     * Set the params of this object.
155     *
156     * @param  array $params   Array of param keys and values to set.
157     */
158    public function setParam($params=null)
159    {
160        if (isset($params) && is_array($params)) {
161            // Merge new parameters with old overriding only those passed.
162            $this->_params = array_merge($this->_params, $params);
163        }
164    }
165
166    /**
167     * Return the value of a parameter, if it exists.
168     *
169     * @access public
170     * @param string $param        Which parameter to return.
171     * @return mixed               Configured parameter value.
172     */
173    public function getParam($param)
174    {
175        $app =& App::getInstance();
176
177        if (array_key_exists($param, $this->_params)) {
178            return $this->_params[$param];
179        } else {
180            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
181            return null;
182        }
183    }
184
185    /**
186     * Saves a version of the current record into the version table.
187     *
188     * @param string $record_table  The table containing the record.
189     * @param string $record_key    The key column for the record.
190     * @param string $record_val    The value of the key column for the record.
191     * @param string $title         The title of this record. Only used for human presentation.
192     *
193     * @return int                  The id for the version (mysql last insert id).
194     */
195    public function create($record_table, $record_key, $record_val, $title='', $notes='')
196    {
197        $app =& App::getInstance();
198        $db =& DB::getInstance();
199
200        $this->initDB();
201
202        // Get current record.
203        if (!$record = $this->getCurrent($record_table, $record_key, $record_val)) {
204            $app->logMsg(sprintf('Could not create %s version, record not found: %s, %s, %s.', $title, $record_table, $record_key, $record_val), LOG_ERR, __FILE__, __LINE__);
205            return false;
206        }
207
208        // Get previous version_number.
209        $qid = $db->query("
210            SELECT MAX(version_number) FROM " . $db->escapeString($this->getParam('db_table')) . "
211            WHERE record_table = '" . $db->escapeString($record_table) . "'
212            AND record_key = '" . $db->escapeString($record_key) . "'
213            AND record_val = '" . $db->escapeString($record_val) . "'
214        ");
215        list($last_version_number) = mysql_fetch_row($qid);
216
217        // Clean-up old versions.
218        $this->deleteOld($record_table, $record_key, $record_val);
219
220        // Save as new version.
221        // TODO: after MySQL 5.0.23 is released this query could benefit from INSERT DELAYED.
222        $db->query("
223            INSERT INTO " . $db->escapeString($this->getParam('db_table')) . " (
224                record_table,
225                record_key,
226                record_val,
227                version_data,
228                version_title,
229                version_number,
230                version_notes,
231                saved_by_user_id,
232                version_datetime
233            ) VALUES (
234                '" . $db->escapeString($record_table) . "',
235                '" . $db->escapeString($record_key) . "',
236                '" . $db->escapeString($record_val) . "',
237                '" . $db->escapeString(gzcompress(serialize($record), 9)) . "',
238                '" . $db->escapeString($title) . "',
239                '" . $db->escapeString($last_version_number + 1) . "',
240                '" . $db->escapeString($notes) . "',
241                '" . $db->escapeString($this->_auth->get('user_id')) . "',
242                NOW()
243            )
244        ");
245
246        return mysql_insert_id($db->getDBH());
247    }
248
249    /**
250     * Copy a version back into it's original table.
251     *
252     * @param string $version_id    The id of the version to restore.
253     *
254     * @return int                  The id for the version (mysql last insert id).
255     */
256    public function restore($version_id)
257    {
258        $app =& App::getInstance();
259        $db =& DB::getInstance();
260
261        $this->initDB();
262
263        // Get version data.
264        $qid = $db->query("
265            SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . "
266            WHERE version_id = '" . $db->escapeString($version_id) . "'
267        ");
268        if (!$record = mysql_fetch_assoc($qid)) {
269            $app->raiseMsg(sprintf(_("Version %s%s not found."), $version_id, (empty($record['version_title']) ? '' : ' (' . $record['version_title'] . ')')), MSG_WARNING, __FILE__, __LINE__);
270            $app->logMsg(sprintf('Version %s%s not found.', $version_id, (empty($record['version_title']) ? '' : ' (' . $record['version_title'] . ')')), LOG_WARNING, __FILE__, __LINE__);
271            return false;
272        }
273        $data = unserialize(gzuncompress($record['version_data']));
274
275        // Ensure saved db columns match current table schema.
276        if (!$db->columnExists($record['record_table'], array_keys($data), $this->getParam('db_schema_strict'))) {
277            $app->raiseMsg(sprintf(_("Version %s%s is not compatible with the current database table."), $version_id, (empty($record['version_title']) ? '' : ' (' . $record['version_title'] . ')')), MSG_ERR, __FILE__, __LINE__);
278            $app->logMsg(sprintf('Version %s%s restoration failed, DB schema does not match for table %s.', $version_id, (empty($record['version_title']) ? '' : ' (' . $record['version_title'] . ')'), $record['record_table']), LOG_ALERT, __FILE__, __LINE__);
279            return false;
280        }
281
282        // SQLize the keys of the specified versioned record.
283        $replace_keys = join(",\n", array_map(array($db, 'escapeString'), array_keys($data)));
284
285        // SQLize the keys of the values of the specified versioned record. (These are more complex because we need to account for SQL null values.)
286        $replace_values = '';
287        $comma = '';
288        foreach ($data as $v) {
289            $replace_values .= is_null($v) ? "$comma\nNULL" : "$comma\n'" . $db->escapeString($v) . "'";
290            $comma = ',';
291        }
292
293        // Disable foreign_key_checks to prevent ON DELETE triggers or restrictions.
294        $db->query("SET SESSION foreign_key_checks = 0");
295        // Replace current record with specified versioned record. Consider converting this SQL to use INSERT 
 ON DUPLICATE KEY UPDATE 

296        $db->query("
297        REPLACE INTO " . $record['record_table'] . " (
298                $replace_keys
299            ) VALUES (
300                $replace_values
301            );
302        ");
303        // Re-enable foreign_key_checks.
304        $db->query("SET SESSION foreign_key_checks = 1");
305
306        return $record;
307    }
308
309    /**
310     * Version garbage collection. Deletes versions older than min_days
311     * when quantity of versions exceeds min_qty. If quantity
312     * exceeds 100 within min_days, the oldest are deleted to bring the
313     * quantity back down to min_qty.
314     *
315     * @param string $record_table  The table containing the record.
316     * @param string $record_key    The key column for the record.
317     * @param string $record_val    The value of the key column for the record.
318     *
319     * @return mixed                Array of versions, or false if none.
320     */
321    public function deleteOld($record_table, $record_key, $record_val)
322    {
323        $db =& DB::getInstance();
324
325        $this->initDB();
326
327        // Get total number of versions for this record.
328        $qid = $db->query("
329            SELECT COUNT(*) FROM " . $db->escapeString($this->getParam('db_table')) . "
330            WHERE record_table = '" . $db->escapeString($record_table) . "'
331            AND record_key = '" . $db->escapeString($record_key) . "'
332            AND record_val = '" . $db->escapeString($record_val) . "'
333        ");
334        list($v_count) = mysql_fetch_row($qid);
335
336        if ($v_count > $this->getParam('min_qty')) {
337            if ($v_count > $this->getParam('max_qty')) {
338                // To prevent a record bomb, limit max number of versions to max_qty.
339                // First query for oldest records, selecting enough to bring total number down to min_qty.
340                $qid = $db->query("
341                    SELECT version_id FROM " . $db->escapeString($this->getParam('db_table')) . "
342                    WHERE record_table = '" . $db->escapeString($record_table) . "'
343                    AND record_key = '" . $db->escapeString($record_key) . "'
344                    AND record_val = '" . $db->escapeString($record_val) . "'
345                    ORDER BY version_datetime ASC
346                    LIMIT " . ($v_count - $this->getParam('min_qty')) . "
347                ");
348                while (list($old_id) = mysql_fetch_row($qid)) {
349                    $old_versions[] = $old_id;
350                }
351                $db->query("
352                    DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
353                    WHERE version_id IN ('" . join("','", $old_versions) . "')
354                ");
355            } else {
356                // Delete versions older than min_days, while still keeping min_qty.
357                $qid = $db->query("
358                    SELECT version_id FROM " . $db->escapeString($this->getParam('db_table')) . "
359                    WHERE record_table = '" . $db->escapeString($record_table) . "'
360                    AND record_key = '" . $db->escapeString($record_key) . "'
361                    AND record_val = '" . $db->escapeString($record_val) . "'
362                    AND DATE_ADD(version_datetime, INTERVAL '" . $this->getParam('min_days') . "' DAY) < NOW()
363                    ORDER BY version_datetime ASC
364                    LIMIT " . ($v_count - $this->getParam('min_qty')) . "
365                ");
366                while (list($old_id) = mysql_fetch_row($qid)) {
367                    $old_versions[] = $old_id;
368                }
369                if (sizeof($old_versions) > 0) {
370                    $db->query("
371                        DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
372                        WHERE version_id IN ('" . join("','", $old_versions) . "')
373                    ");
374                }
375            }
376        }
377    }
378
379    /**
380     * Get a list of versions of specified record.
381     *
382     * @param string $record_table  The table containing the record.
383     * @param string $record_key    The key column for the record.
384     * @param string $record_val    The value of the key column for the record.
385     *
386     * @return mixed                Array of versions, or false if none.
387     */
388    public function getList($record_table, $record_key, $record_val)
389    {
390        $db =& DB::getInstance();
391
392        $this->initDB();
393
394        // Get versions of this record.
395        $qid = $db->query("
396            SELECT
397                version_id,
398                saved_by_user_id,
399                version_datetime,
400                version_title,
401                version_number,
402                version_notes
403            FROM " . $db->escapeString($this->getParam('db_table')) . "
404            WHERE record_table = '" . $db->escapeString($record_table) . "'
405            AND record_key = '" . $db->escapeString($record_key) . "'
406            AND record_val = '" . $db->escapeString($record_val) . "'
407            ORDER BY version_datetime DESC
408        ");
409        $versions = array();
410        while ($row = mysql_fetch_assoc($qid)) {
411            // Get admin usernames.
412            $row['editor'] = $this->_auth->getUsername($row['saved_by_user_id']);
413            $versions[] = $row;
414        }
415        return $versions;
416    }
417
418    /**
419     * Get the version record for a specified version id.
420     *
421     * @param string $version_id    The id of the version to restore.
422     *
423     * @return mixed                Array of data saved in version, or false if none.
424     */
425    public function getVerson($version_id)
426    {
427        $db =& DB::getInstance();
428
429        $this->initDB();
430
431        // Get version data.
432        $qid = $db->query("
433            SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . "
434            WHERE version_id = '" . $db->escapeString($version_id) . "'
435        ");
436        return mysql_fetch_assoc($qid);
437    }
438
439    /**
440     * Get the data stored for a specified version id.
441     *
442     * @param string $version_id    The id of the version to restore.
443     *
444     * @return mixed                Array of data saved in version, or false if none.
445     */
446    public function getData($version_id)
447    {
448        $db =& DB::getInstance();
449
450        $this->initDB();
451
452        // Get version data.
453        $qid = $db->query("
454            SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . "
455            WHERE version_id = '" . $db->escapeString($version_id) . "'
456        ");
457        $record = mysql_fetch_assoc($qid);
458        if (isset($record['version_data'])) {
459            return unserialize(gzuncompress($record['version_data']));
460        } else {
461            return false;
462        }
463    }
464
465    /**
466     * Get the current record data from the original table.
467     *
468     * @param string $version_id    The id of the version to restore.
469     *
470     * @return mixed                Array of data saved in version, or false if none.
471     */
472    public function getCurrent($record_table, $record_key, $record_val)
473    {
474        $db =& DB::getInstance();
475        $app =& App::getInstance();
476
477        $this->initDB();
478
479        if (!$record_table || !$record_key || !$record_val) {
480            $app->logMsg(sprintf('Invalid current version args: %s, %s, %s.', $record_table, $record_key, $record_val), LOG_ERR, __FILE__, __LINE__);
481            return false;
482        }
483
484        $qid = $db->query("
485            SELECT * FROM " . $db->escapeString($record_table) . "
486            WHERE " . $db->escapeString($record_key) . " = '" . $db->escapeString($record_val) . "'
487        ");
488        if ($record = mysql_fetch_assoc($qid)) {
489            return $record;
490        } else {
491            return false;
492        }
493    }
494
495
496} // End of class.
Note: See TracBrowser for help on using the repository browser.