source: trunk/lib/Lock.inc.php @ 719

Last change on this file since 719 was 718, checked in by anonymous, 4 years ago

Minor fixes
File size: 16.5 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 * Lock.inc.php
25 *
26 * The Lock class provides a system for locking abstract DB rows.
27 *
28 * @author  Quinn Comendant <quinn@strangecode.com>
29 * @version 2.1
30 */
31class Lock
32{
33    // A place to keep an object instance for the singleton pattern.
34    protected static $instance = null;
35
36    // Configuration of this object.
37    protected $_params = array(
38        // The time required to pass before a user can forcibly unlock a locked record.
39        'timeout' => 600,
40
41        // The time after which a record will automatically become unlocked.
42        'auto_timeout' => 1800,
43
44        // The URL to the lock script.
45        'error_url' => '/lock.php',
46
47        // The name of the database table to store locks.
48        'db_table' => 'lock_tbl',
49
50        // Automatically create table and verify columns. Better set to false after site launch.
51        // This value is overwritten by the $app->getParam('db_create_tables') setting if it is available.
52        'create_table' => true,
53    );
54
55    // Store lock data from DB.
56    protected $data = array();
57
58    // Auth_SQL object from which to access a current user_id.
59    protected $_auth = null;
60
61    /**
62     * This method enforces the singleton pattern for this class.
63     *
64     * @return  object  Reference to the global Lock object.
65     * @access  public
66     * @static
67     */
68    public static function &getInstance($auth_object=null)
69    {
70        if (self::$instance === null) {
71            self::$instance = new self($auth_object);
72        }
73
74        return self::$instance;
75    }
76
77    /**
78     * Constructor. Pass an Auth object on which to perform user lookups.
79     *
80     * @param mixed  $auth_object  An Auth_SQL or Auth_FILE object.
81     */
82    public function __construct($auth_object=null)
83    {
84        $app =& App::getInstance();
85
86        if (!is_null($auth_object) || is_null($this->_auth)) {
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
94        // Get create tables config from global context.
95        if (!is_null($app->getParam('db_create_tables'))) {
96            $this->setParam(array('create_table' => $app->getParam('db_create_tables')));
97        }
98    }
99
100    /**
101     * Setup the database table for this class.
102     *
103     * @access  public
104     * @author  Quinn Comendant <quinn@strangecode.com>
105     * @since   26 Aug 2005 17:09:36
106     */
107    public function initDB($recreate_db=false)
108    {
109        $app =& App::getInstance();
110        $db =& DB::getInstance();
111
112        static $_db_tested = false;
113
114        if ($recreate_db || !$_db_tested && $this->getParam('create_table')) {
115            if ($recreate_db) {
116                $db->query("DROP TABLE IF EXISTS " . $this->getParam('db_table'));
117                $app->logMsg(sprintf('Dropping and recreating table %s.', $this->getParam('db_table')), LOG_INFO, __FILE__, __LINE__);
118            }
119            $db->query(sprintf("CREATE TABLE IF NOT EXISTS %s (
120                lock_id INT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
121                record_table varchar(255) NOT NULL default '',
122                record_key varchar(255) NOT NULL default '',
123                record_val varchar(255) NOT NULL default '',
124                title varchar(255) NOT NULL default '',
125                set_by_admin_id smallint(11) NOT NULL default '0',
126                lock_datetime datetime NOT NULL default '%s 00:00:00',
127                KEY record_table (record_table),
128                KEY record_key (record_key),
129                KEY record_val (record_val)
130            )", $db->escapeString($this->getParam('db_table')), $db->getParam('zero_date')));
131
132            if (!$db->columnExists($this->getParam('db_table'), array(
133                'lock_id',
134                'record_table',
135                'record_key',
136                'record_val',
137                'title',
138                'set_by_admin_id',
139                'lock_datetime',
140            ), false, false)) {
141                $app->logMsg(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), LOG_ALERT, __FILE__, __LINE__);
142                trigger_error(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), E_USER_ERROR);
143            }
144        }
145        $_db_tested = true;
146    }
147
148    /**
149     * Set the params of this object.
150     *
151     * @param  array $params   Array of param keys and values to set.
152     */
153    public function setParam($params=null)
154    {
155        if (isset($params) && is_array($params)) {
156            // Merge new parameters with old overriding only those passed.
157            $this->_params = array_merge($this->_params, $params);
158        }
159    }
160
161    /**
162     * Return the value of a parameter, if it exists.
163     *
164     * @access public
165     * @param string $param        Which parameter to return.
166     * @return mixed               Configured parameter value.
167     */
168    public function getParam($param)
169    {
170        $app =& App::getInstance();
171
172        if (array_key_exists($param, $this->_params)) {
173            return $this->_params[$param];
174        } else {
175            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
176            return null;
177        }
178    }
179
180    /**
181     * Select the lock to manipulate.
182     *
183     * @param mixed  $record_table_or_lock_id  The table containing the record to lock,
184     *                                         or a numeric lock_id.
185     * @param string $record_key  The key column for the record to lock.
186     * @param string $record_val  The value of the key column for the record to lock.
187     */
188    public function select($record_table_or_lock_id, $record_key=null, $record_val=null)
189    {
190        $app =& App::getInstance();
191        $db =& DB::getInstance();
192
193        $this->initDB();
194
195        // Expire old locks.
196        $this->_auto_timeout();
197
198        if (is_numeric($record_table_or_lock_id) && !isset($record_key) && !isset($record_val)) {
199            // Get lock data by lock_id.
200            $qid = $db->query("
201                SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . "
202                WHERE lock_id = '" . $db->escapeString($record_table_or_lock_id) . "'
203            ");
204        } else {
205            // Get lock data by record specs
206            $qid = $db->query("
207                SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . "
208                WHERE record_table = '" . $db->escapeString($record_table_or_lock_id) . "'
209                AND record_key = '" . $db->escapeString($record_key) . "'
210                AND record_val = '" . $db->escapeString($record_val) . "'
211            ");
212        }
213        if ($this->data = mysql_fetch_assoc($qid)) {
214            $app->logMsg(sprintf('Selecting %slocked record: %s %s %s', ($this->data['set_by_admin_id'] == $this->_auth->get('user_id') ? 'self-' : ''), $record_table_or_lock_id, $record_key, $record_val), LOG_DEBUG, __FILE__, __LINE__);
215            // FIXME: What if admin set lock, but public user is current lock user?
216            $this->data['editor'] = $this->_auth->getUsername($this->data['set_by_admin_id']);
217            return true;
218        } else {
219            return false;
220        }
221    }
222
223    /**
224     * Returns true if the record we instantiated with is locked.
225     *
226     * @return bool            True if locked.
227     */
228    public function isLocked()
229    {
230        return isset($this->data['lock_id']);
231    }
232
233    /**
234     * Returns the status of who set the lock. Use this to ignore locks set by
235     * the current user.
236     *
237     * @return bool            True if current user set the lock.
238     */
239    public function isMine()
240    {
241        $db =& DB::getInstance();
242
243        $this->initDB();
244
245        if ($this->isLocked()) {
246            $qid = $db->query("SELECT * FROM " . $db->escapeString($this->getParam('db_table')) . " WHERE lock_id = '" . $db->escapeString($this->data['lock_id']) . "'");
247            if ($lock = mysql_fetch_assoc($qid)) {
248                return ($lock['set_by_admin_id'] == $this->_auth->get('user_id'));
249            } else {
250                return false;
251            }
252        } else {
253            return false;
254        }
255    }
256
257    /**
258     * Create a new lock for the specified table/key/value.
259     *
260     * @param string $record_table  The table containing the record to lock.
261     * @param string $record_key  The key column for the record to lock.
262     * @param string $record_val  The value of the key column for the record to lock.
263     * @param string $title       A title to apply to the lock, for display purposes.
264     *
265     * @return int            The id for the lock (mysql last insert id).
266     */
267    public function set($record_table, $record_key, $record_val, $title='')
268    {
269        $db =& DB::getInstance();
270
271        $this->initDB();
272
273        if ($this->_auth->get('user_id') == '' || filter_var($this->_auth->get('user_id'), FILTER_VALIDATE_INT) === false) {
274            $app->logMsg(sprintf("auth->get('user_id') returns a non-integer: %s", $this->_auth->get('user_id')), LOG_ERR, __FILE__, __LINE__);
275            return false;
276        }
277
278        // Expire old locks.
279        $this->_auto_timeout();
280
281        // Remove previous locks if exist. Is this better than using a REPLACE INTO?
282        $db->query("
283            DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
284            WHERE record_table = '" . $db->escapeString($record_table) . "'
285            AND record_key = '" . $db->escapeString($record_key) . "'
286            AND record_val = '" . $db->escapeString($record_val) . "'
287        ");
288
289        // Set new lock.
290        $db->query("
291            INSERT INTO " . $db->escapeString($this->getParam('db_table')) . " (
292                record_table,
293                record_key,
294                record_val,
295                title,
296                set_by_admin_id,
297                lock_datetime
298            ) VALUES (
299                '" . $db->escapeString($record_table) . "',
300                '" . $db->escapeString($record_key) . "',
301                '" . $db->escapeString($record_val) . "',
302                '" . $db->escapeString($title) . "',
303                '" . $db->escapeString($this->_auth->get('user_id')) . "',
304                NOW()
305            )
306        ");
307        $lock_id = mysql_insert_id($db->getDBH());
308
309        // Must register this locked record as the current.
310        $this->select($lock_id);
311
312        return $lock_id;
313    }
314
315    /**
316     * Unlock the currently selected record.
317     */
318    public function remove()
319    {
320        $app =& App::getInstance();
321        $db =& DB::getInstance();
322
323        $this->initDB();
324
325        // Expire old locks.
326        $this->_auto_timeout();
327
328        if (!$this->isLocked()) {
329            // No lock selected.
330            return false;
331        }
332
333        // Delete a specific lock.
334        $db->query("
335            DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
336            WHERE lock_id = '" . $db->escapeString($this->data['lock_id']) . "'
337        ");
338
339        $app->logMsg(sprintf('Removing lock: %s', $this->data['lock_id']), LOG_DEBUG, __FILE__, __LINE__);
340        return true;
341    }
342
343    /**
344     * Unlock all records, or all records for a specified user.
345     */
346    public function removeAll($user_id=null)
347    {
348        $app =& App::getInstance();
349        $db =& DB::getInstance();
350
351        $this->initDB();
352
353        // Expire old locks.
354        $this->_auto_timeout();
355
356        if (isset($user_id)) {
357            // Delete specific user's locks.
358            $db->query("DELETE FROM " . $db->escapeString($this->getParam('db_table')) . " WHERE set_by_admin_id = '" . $db->escapeString($user_id) . "'");
359            $app->logMsg(sprintf('Record locks owned by user %s have been deleted', $this->_auth->getUsername($user_id)), LOG_DEBUG, __FILE__, __LINE__);
360        } else {
361            // Delete ALL locks.
362            $db->query("DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "");
363            $app->logMsg(sprintf('All record locks deleted by user %s', $this->_auth->get('username')), LOG_DEBUG, __FILE__, __LINE__);
364        }
365    }
366
367    /**
368     * Deletes all locks that are older than auto_timeout.
369     */
370    public function _auto_timeout()
371    {
372        $db =& DB::getInstance();
373
374        static $_timeout_run = false;
375
376        $this->initDB();
377
378        if (!$_timeout_run) {
379            // Delete all old locks.
380            $db->query("
381                DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
382                WHERE DATE_ADD(lock_datetime, INTERVAL '" . $db->escapeString($this->getParam('auto_timeout')) . "' SECOND) < NOW()
383            ");
384            $_timeout_run = true;
385        }
386    }
387
388    /**
389     * Redirect to record lock error page.
390     */
391    public function dieErrorPage()
392    {
393        $app =& App::getInstance();
394
395        $app->dieURL($this->getParam('error_url'), array('lock_id' => $this->data['lock_id'], 'boomerang' => urlencode(getenv('REQUEST_URI'))));
396    }
397
398    /**
399     * Print error page. This method is probably not used anywhere; instead, we're including this via the template codebase/services/templates/lock.ihtml
400     */
401    public function printErrorHTML()
402    {
403        $app =& App::getInstance();
404        ?>
405        <form method="post" action="<?php echo oTxt($_SERVER['PHP_SELF']); ?>">
406            <?php $app->printHiddenSession() ?>
407            <input type="hidden" name="lock_id" value="<?php echo $this->getID(); ?>" />
408            <div id="sc-msg" class="sc-msg">
409                <div class="sc-msg-notice">
410                <?php printf(_("<em>%s</em> is currently being edited by %s (%d minutes elapsed). You cannot modify this database record while it is locked. Please try again later."),
411                    ucfirst($this->getTitle()),
412                    $this->getEditor(),
413                    date('i', $this->getSecondsElapsed() + 60)
414                ); ?>
415                </div>
416                <?php if ($this->getSecondsElapsed() >= $this->getParam('timeout')) { ?>
417                    <div class="sc-msg-notice"><?php printf(_("You can forcibly unlock the record if you believe the editing session has expired. You might want to confirm with %s before doing this."), $this->getEditor()) ?></div>
418                    <div class="sc-msg-notice">
419                        <input type="submit" name="unlock" value="<?php echo _("Unlock"); ?>" />
420                        <input type="submit" name="cancel" value="<?php echo _("Cancel"); ?>" />
421                    </div>
422                <?php } else { ?>
423                    <div class="sc-msg-notice">
424                        <input type="submit" name="cancel" value="<?php echo _("Cancel"); ?>" />
425                    </div>
426                <?php } ?>
427            </div>
428        </form>
429        <?php
430    }
431
432    /**
433     * Return lock_id of locked record.
434     */
435    public function getID()
436    {
437        return $this->data['lock_id'];
438    }
439
440    /**
441     * Return title of locked record.
442     */
443    public function getTitle()
444    {
445        return $this->data['title'];
446    }
447
448    /**
449     * Return administrator username for locked record.
450     */
451    public function getEditor()
452    {
453        return $this->data['editor'];
454    }
455
456    /**
457     * Return total seconds since the record was locked.
458     */
459    public function getSecondsElapsed()
460    {
461        if (isset($this->data['lock_datetime']) && false !== ($lock_timestamp = strtotime($this->data['lock_datetime'])) && $lock_timestamp < time()) {
462            return time() - $lock_timestamp;
463        } else {
464            return 0;
465        }
466    }
467
468
469} // End of class.
Note: See TracBrowser for help on using the repository browser.