source: trunk/lib/Prefs.inc.php @ 331

Last change on this file since 331 was 331, checked in by quinn, 16 years ago

Truncating output from getDump when used for logging.
File size: 14.4 KB
Line 
1<?php
2/**
3 * Prefs.inc.php
4 * code by strangecode :: www.strangecode.com :: this document contains copyrighted information
5 *
6 * Prefs provides an API for saving arbitrary values in a user's session.
7 * Session prefs can be stored into a database with the optional save() and load() methods.
8 *
9 * @author  Quinn Comendant <quinn@strangecode.com>
10 * @version 2.1
11 *
12 * Example of use:
13---------------------------------------------------------------------
14// Load preferences for the user's session.
15require_once 'codebase/lib/Prefs.inc.php';
16$prefs = new Prefs('my-namespace');
17$prefs->setParam(array(
18    'persistent' => $auth->isLoggedIn(),
19    'user_id' => $auth->get('user_id'),
20));
21$prefs->setDefaults(array(
22    'search_num_results' => 25,
23    'datalog_num_entries' => 25,
24));
25$prefs->load();
26
27// Update preferences. Make sure to validate this input first!
28$prefs->set('search_num_results', getFormData('search_num_results'));
29$prefs->set('datalog_num_entries', getFormData('datalog_num_entries'));
30$prefs->save();
31
32---------------------------------------------------------------------
33 */
34class Prefs {
35
36    // Namespace of this instance of Prefs.
37    var $_ns;
38
39    // Configuration parameters for this object.
40    var $_params = array(
41       
42        // Enable database storage. If this is false, all prefs will live only as long as the session.
43        'persistent' => false,
44       
45        // The current user_id for which to load/save persistent preferences.
46        'user_id' => null,
47       
48        // How long before we force a reload of the persistent prefs data? 3600 = once every hour.
49        'load_timeout' => 3600,
50       
51        // Name of database table to store persistent prefs.
52        'db_table' => 'pref_tbl',
53
54        // Automatically create table and verify columns. Better set to false after site launch.
55        'create_table' => true,
56    );
57
58    /**
59     * Prefs constructor.
60     */
61    function Prefs($namespace='')
62    {
63        $app =& App::getInstance();
64
65        $this->_ns = $namespace;
66       
67        // Initialized the prefs array.
68        if (!isset($_SESSION['_prefs'][$this->_ns])) {
69            $this->clear();
70        }
71
72        // Get create tables config from global context.
73        if (!is_null($app->getParam('db_create_tables'))) {
74            $this->setParam(array('create_table' => $app->getParam('db_create_tables')));
75        }
76    }
77
78    /**
79     * Setup the database table for this class.
80     *
81     * @access  public
82     * @author  Quinn Comendant <quinn@strangecode.com>
83     * @since   04 Jun 2006 16:41:42
84     */
85    function initDB($recreate_db=false)
86    {
87        $app =& App::getInstance();
88        $db =& DB::getInstance();
89
90        static $_db_tested = false;
91
92        if ($recreate_db || !$_db_tested && $this->getParam('create_table')) {
93            if ($recreate_db) {
94                $db->query("DROP TABLE IF EXISTS " . $this->getParam('db_table'));
95                $app->logMsg(sprintf('Dropping and recreating table %s.', $this->getParam('db_table')), LOG_INFO, __FILE__, __LINE__);
96            }
97            $db->query("CREATE TABLE IF NOT EXISTS " . $db->escapeString($this->getParam('db_table')) . " (
98                user_id VARCHAR(32) NOT NULL DEFAULT '',
99                pref_namespace VARCHAR(32) NOT NULL DEFAULT '',
100                pref_key VARCHAR(64) NOT NULL DEFAULT '',
101                pref_value TEXT,
102                PRIMARY KEY (user_id, pref_namespace, pref_key)
103            )");
104
105            if (!$db->columnExists($this->getParam('db_table'), array(
106                'user_id',
107                'pref_namespace',
108                'pref_key',
109                'pref_value',
110            ), false, false)) {
111                $app->logMsg(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), LOG_ALERT, __FILE__, __LINE__);
112                trigger_error(sprintf('Database table %s has invalid columns. Please update this table manually.', $this->getParam('db_table')), E_USER_ERROR);
113            }
114        }
115        $_db_tested = true;
116    }
117
118    /**
119     * Set the params of this object.
120     *
121     * @param  array $params   Array of param keys and values to set.
122     */
123    function setParam($params=null)
124    {
125        if (isset($params) && is_array($params)) {
126            // Merge new parameters with old overriding only those passed.
127            $this->_params = array_merge($this->_params, $params);
128        }
129    }
130
131    /**
132     * Return the value of a parameter, if it exists.
133     *
134     * @access public
135     * @param string $param        Which parameter to return.
136     * @return mixed               Configured parameter value.
137     */
138    function getParam($param)
139    {
140        $app =& App::getInstance();
141   
142        if (isset($this->_params[$param])) {
143            return $this->_params[$param];
144        } else {
145            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
146            return null;
147        }
148    }
149
150    /**
151     * Sets the default values for preferences. If a preference is not explicitly
152     * set, the value set here will be used. Can be called multiple times to merge additional
153     * defaults together.
154     *
155     * @param  array $defaults  Array of key-value pairs
156     */
157    function setDefaults($defaults)
158    {
159        if (isset($defaults) && is_array($defaults)) {
160            $_SESSION['_prefs'][$this->_ns]['defaults'] = array_merge($_SESSION['_prefs'][$this->_ns]['defaults'], $defaults);
161        }
162    }
163
164    /**
165     * Store a key-value pair in the session. If the value is different than what is set by setDefaults
166     * the value will be scheduled to be saved in the database.
167     * This function determines what data is saved to the database. Ensure clean values!
168     *
169     * @param  string $key          The name of the preference to modify.
170     * @param  string $val          The new value for this preference.
171     * @param  bool   $persistent   Save this value forever? Set to false and value will exist as long as the session is in use.
172     */
173    function set($key, $val)
174    {
175        $app =& App::getInstance();
176
177        if ('' == $key) {
178            $app->logMsg(sprintf('Key is empty (provided with value: %s)', $val), LOG_NOTICE, __FILE__, __LINE__);
179            return false;
180        }
181       
182        // Set a persistent perference if...
183        // - there isn't a default.
184        // - the new value is different than the default
185        // - there is a previously existing persistent key.
186        if (!isset($_SESSION['_prefs'][$this->_ns]['defaults'][$key]) || $_SESSION['_prefs'][$this->_ns]['defaults'][$key] != $val || isset($_SESSION['_prefs'][$this->_ns]['persistent'][$key])) {
187            $_SESSION['_prefs'][$this->_ns]['persistent'][$key] = $val;           
188            $app->logMsg(sprintf('Setting preference %s => %s', $key, truncate(getDump($val, true), 128, 'end')), LOG_DEBUG, __FILE__, __LINE__);
189        } else {
190            $app->logMsg(sprintf('Not setting preference %s => %s', $key, truncate(getDump($val, true), 128, 'end')), LOG_DEBUG, __FILE__, __LINE__);
191        }
192    }
193
194    /**
195     * Returns the value of the requested preference. Persistent values take precedence, but if none is set
196     * a default value is returned, or if not that, null.
197     *
198     * @param string $key       The name of the preference to retrieve.
199     *
200     * @return string           The value of the preference.
201     */
202    function get($key)
203    {
204        $app =& App::getInstance();
205        if (isset($_SESSION['_prefs'][$this->_ns]['persistent']) && array_key_exists($key, $_SESSION['_prefs'][$this->_ns]['persistent'])) {
206            $app->logMsg(sprintf('Found %s in persistent', $key), LOG_DEBUG, __FILE__, __LINE__);
207            return $_SESSION['_prefs'][$this->_ns]['persistent'][$key];
208        } else if (isset($_SESSION['_prefs'][$this->_ns]['defaults']) && array_key_exists($key, $_SESSION['_prefs'][$this->_ns]['defaults'])) {
209            $app->logMsg(sprintf('Found %s in defaults', $key), LOG_DEBUG, __FILE__, __LINE__);
210            return $_SESSION['_prefs'][$this->_ns]['defaults'][$key];
211        } else {
212            $app->logMsg(sprintf('Key not found in prefs cache: %s', $key), LOG_DEBUG, __FILE__, __LINE__);
213            return null;
214        }
215    }
216
217    /**
218     * To see if a preference has been set.
219     *
220     * @param string $key       The name of the preference to check.
221     * @return boolean          True if the preference isset and not empty false otherwise.
222     */
223    function exists($key)
224    {
225        return array_key_exists($key, $_SESSION['_prefs'][$this->_ns]['persistent']);
226    }
227
228    /**
229     * Clear a set preference value. This will also remove the value from the database.
230     *
231     * @param string $key       The name of the preference to delete.
232     */
233    function delete($key)
234    {
235        unset($_SESSION['_prefs'][$this->_ns]['persistent'][$key]);
236    }
237
238    /**
239     * Resets the $_SESSION cache. This should be executed with the same consideration
240     * as $auth->clear(), such as when logging out.
241     */
242    function clear($focus='all')
243    {
244        switch ($focus) {
245        case 'all' :
246            $_SESSION['_prefs'][$this->_ns] = array(
247                'loaded' => false,
248                'load_datetime' => '1970-01-01',
249                'defaults' => array(),
250                'persistent' => array(),
251            );
252            break;
253
254        case 'defaults' :
255            $_SESSION['_prefs'][$this->_ns]['defaults'] = array();
256            break;
257
258        case 'persistent' :
259            $_SESSION['_prefs'][$this->_ns]['persistent'] = array();
260            break;
261        }
262    }
263   
264    /*
265    * Retrieves all prefs from the database and stores them in the $_SESSION.
266    *
267    * @access   public
268    * @param    bool    $force  Set to always load from database, regardless if _isLoaded() or not.
269    * @return   bool    True if loading succeeded.
270    * @author   Quinn Comendant <quinn@strangecode.com>
271    * @version  1.0
272    * @since    04 Jun 2006 16:56:53
273    */
274    function load($force=false)
275    {
276        $app =& App::getInstance();
277        $db =& DB::getInstance();
278       
279        // Skip this method if not using the db.
280        if (true !== $this->getParam('persistent')) {
281            return true;
282        }
283
284        $this->initDB();
285
286        // Prefs already loaded for this session.
287        if (!$force && $this->_isLoaded()) {
288            return true;
289        }
290
291        // User_id must not be empty.
292        if ('' == $this->getParam('user_id')) {
293            $app->logMsg(sprintf('Cannot save prefs because user_id not set.', null), LOG_WARNING, __FILE__, __LINE__);
294            return false;
295        }
296       
297        // Clear existing cache.
298        $this->clear('persistent');
299       
300        // Retrieve all prefs for this user and namespace.
301        $qid = $db->query("
302            SELECT pref_key, pref_value
303            FROM " . $db->escapeString($this->getParam('db_table')) . "
304            WHERE user_id = '" . $db->escapeString($this->getParam('user_id')) . "'
305            AND pref_namespace = '" . $db->escapeString($this->_ns) . "'
306            LIMIT 10000
307        ");
308        while (list($key, $val) = mysql_fetch_row($qid)) {
309            $_SESSION['_prefs'][$this->_ns]['persistent'][$key] = unserialize($val);
310        }
311       
312        $app->logMsg(sprintf('Loaded %s prefs from database.', mysql_num_rows($qid)), LOG_DEBUG, __FILE__, __LINE__);
313       
314        // Data loaded only once per session.
315        $_SESSION['_prefs'][$this->_ns]['loaded'] = true;
316        $_SESSION['_prefs'][$this->_ns]['load_datetime'] = date('Y-m-d H:i:s');
317       
318        return true;
319    }
320   
321    /*
322    * Returns true if the prefs had been loaded from the database into the $_SESSION recently.
323    * This function is simply a check so the database isn't access every page load.
324    *
325    * @access   private
326    * @return   bool    True if prefs are loaded.
327    * @author   Quinn Comendant <quinn@strangecode.com>
328    * @version  1.0
329    * @since    04 Jun 2006 17:12:44
330    */
331    function _isLoaded()
332    {
333        if (isset($_SESSION['_prefs'][$this->_ns]['load_datetime'])
334        && strtotime($_SESSION['_prefs'][$this->_ns]['load_datetime']) > time() - $this->getParam('load_timeout')
335        && isset($_SESSION['_prefs'][$this->_ns]['loaded']) 
336        && true === $_SESSION['_prefs'][$this->_ns]['loaded']) {
337            return true;
338        } else {
339            return false;
340        }
341    }
342   
343    /*
344    * Saves all prefs stored in the $_SESSION into the database.
345    *
346    * @access   public
347    * @return   bool    True if prefs exist and were saved.
348    * @author   Quinn Comendant <quinn@strangecode.com>
349    * @version  1.0
350    * @since    04 Jun 2006 17:19:56
351    */
352    function save()
353    {
354        $app =& App::getInstance();
355        $db =& DB::getInstance();
356       
357        // Skip this method if not using the db.
358        if (true !== $this->getParam('persistent')) {
359            return true;
360        }
361       
362        // User_id must not be empty.
363        if ('' == $this->getParam('user_id')) {
364            $app->logMsg(sprintf('Cannot save prefs because user_id not set.', null), LOG_WARNING, __FILE__, __LINE__);
365            return false;
366        }
367
368        $this->initDB();
369
370        if (isset($_SESSION['_prefs'][$this->_ns]['persistent']) && is_array($_SESSION['_prefs'][$this->_ns]['persistent']) && !empty($_SESSION['_prefs'][$this->_ns]['persistent'])) {
371            // Delete old prefs from database.
372            $db->query("
373                DELETE FROM " . $db->escapeString($this->getParam('db_table')) . "
374                WHERE user_id = '" . $db->escapeString($this->getParam('user_id')) . "'
375                AND pref_namespace = '" . $db->escapeString($this->_ns) . "'
376            ");
377           
378            // Insert new prefs.
379            $insert_values = array();
380            foreach ($_SESSION['_prefs'][$this->_ns]['persistent'] as $key => $val) {
381                $insert_values[] = sprintf("('%s', '%s', '%s', '%s')", 
382                    $db->escapeString($this->getParam('user_id')), 
383                    $db->escapeString($this->_ns), 
384                    $db->escapeString($key), 
385                    $db->escapeString(serialize($val))
386                );
387            }
388            // TODO: after MySQL 5.0.23 is released this query could benefit from INSERT DELAYED.
389            $db->query("
390                INSERT INTO " . $db->escapeString($this->getParam('db_table')) . "
391                (user_id, pref_namespace, pref_key, pref_value)
392                VALUES " . join(', ', $insert_values) . "
393            ");
394           
395            $app->logMsg(sprintf('Saved %s prefs to database.', sizeof($insert_values)), LOG_DEBUG, __FILE__, __LINE__);
396            return true;
397        }
398       
399        return false;
400    }
401}
402
403
404?>
Note: See TracBrowser for help on using the repository browser.