source: trunk/lib/DB.inc.php @ 71

Last change on this file since 71 was 71, checked in by scdev, 18 years ago

minor misc bug fixes
File size: 12.2 KB
Line 
1<?php
2/**
3 * DB.inc.php
4 * code by strangecode :: www.strangecode.com :: this document contains copyrighted information
5 *
6 * DB abstraction layer.
7 *
8 * @author  Quinn Comendant <quinn@strangecode.com>
9 * @version 1.0.1
10 */
11
12class DB {
13
14    // If DB::connect has successfully opened a db connection.
15    var $_connected = false;
16
17    // Database handler.
18    var $dbh;
19
20    // Hash of DB parameters.
21    var $_params = array();
22
23    // Default parameters.
24    var $_param_defaults = array(
25
26        // DB passwords should be set as apache environment variables in httpd.conf, readable only by root.
27        'db_server' => 'localhost',
28        'db_name' => null,
29        'db_user' => null,
30        'db_pass' => null,
31
32        // Debugging.
33        'db_always_debug' => false, // TRUE = display all SQL queries.
34        'db_debug' => false, // TRUE = display db errors.
35        'db_die_on_failure' => false, // TRUE = script stops on db error.
36    );
37
38    // Translate between HTML and MySQL character set names.
39    var $mysql_character_sets = array(
40        'utf-8' => 'utf8',
41        'iso-8859-1' => 'latin1',
42    );
43
44    // Caches.
45    var $existing_tables;
46    var $table_columns;
47
48    /**
49     * This method enforces the singleton pattern for this class.
50     *
51     * @return  object  Reference to the global SessionCache object.
52     * @access  public
53     * @static
54     */
55    function &getInstance()
56    {
57        static $instance = null;
58
59        if ($instance === null) {
60            $instance = new DB();
61        }
62
63        return $instance;
64    }
65
66    /**
67     * Constructor.
68     */
69    function DB()
70    {
71        // Initialize default params.
72        if (isset($params) && is_array($params)) {
73            // Merge new parameters with old overriding only those passed.
74            $this->_params = array_merge($this->_params, $params);
75        }
76    }
77
78    /**
79     * Set (or overwrite existing) parameters by passing an array of new parameters.
80     *
81     * @access public
82     *
83     * @param  array    $params     Array of parameters (key => val pairs).
84     */
85    function setParam($params)
86    {
87        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
88            $this =& DB::getInstance();
89        }
90
91        if (isset($params) && is_array($params)) {
92            // Merge new parameters with old overriding only those passed.
93            $this->_params = array_merge($this->_params, $params);
94        } else {
95            App::logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
96        }
97    }
98
99    /**
100     * Return the value of a parameter.
101     *
102     * @access  public
103     *
104     * @param   string  $param      The key of the parameter to return.
105     *
106     * @return  mixed               Parameter value.
107     */
108    function getParam($param)
109    {
110        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
111            $this =& DB::getInstance();
112        }
113
114        if (isset($this->_params[$param])) {
115            return $this->_params[$param];
116        } else {
117            App::logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
118            return null;
119        }
120    }
121
122    /**
123     * Connect to database with credentials in params.
124     *
125     * @access  public
126     * @author  Quinn Comendant <quinn@strangecode.com>
127     * @since   28 Aug 2005 14:02:49
128     */
129    function connect()
130    {
131        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
132            $this =& DB::getInstance();
133        }
134
135        if (!$this->getParam('db_name') || !$this->getParam('db_user') || !$this->getParam('db_pass')) {
136            App::logMsg('Database credentials missing.', LOG_EMERG, __FILE__, __LINE__);
137            return false;
138        }
139
140        // Connect to database. Always create a new link to the server.
141        if ($this->dbh = mysql_connect($this->getParam('db_server'), $this->getParam('db_user'), $this->getParam('db_pass'), true)) {
142            // Select database
143            mysql_select_db($this->getParam('db_name'), $this->dbh);
144        }
145
146        // Test for connection errors.
147        if (!$this->dbh || mysql_error($this->dbh)) {
148            $mysql_error_msg = $this->dbh ? 'Codebase MySQL error: (' . mysql_errno($this->dbh) . ') ' . mysql_error($this->dbh) : 'Codebase MySQL error: Could not connect to server.';
149            App::logMsg($mysql_error_msg, LOG_EMERG, __FILE__, __LINE__);
150
151            // Print helpful or pretty error?
152            if ($this->getParam('db_debug')) {
153                echo $mysql_error_msg . "\n";
154            } else {
155                echo _("This page is temporarily unavailable. It should be back up in a few minutes.");
156            }
157
158            // Die or continue without connection?
159            if ($this->getParam('db_die_on_failure')) {
160                echo "\n\n<!-- Script execution stopped out of embarrassment. -->";
161                die;
162            } else {
163                return false;
164            }
165        }
166
167        // DB connection success!
168        $this->_connected = true;
169
170        // Tell MySQL what character set we're useing. Available only on MySQL verions > 4.01.01.
171        $this->query("/*!40101 SET NAMES '" . $this->mysql_character_sets[strtolower(App::getParam('character_set'))] . "' */");
172
173        return true;
174    }
175
176    /**
177     * Close db connection.
178     *
179     * @access  public
180     * @author  Quinn Comendant <quinn@strangecode.com>
181     * @since   28 Aug 2005 14:32:01
182     */
183    function close()
184    {
185        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
186            $this =& DB::getInstance();
187        }
188
189        if (!$this->_connected) {
190            return false;
191        }
192
193        mysql_close($this->dbh);
194    }
195
196    /**
197     * Return the current database handler.
198     *
199     * @access  public
200     * @return  resource Current value of $this->dbh.
201     * @author  Quinn Comendant <quinn@strangecode.com>
202     * @since   20 Aug 2005 13:50:36
203     */
204    function getDBH()
205    {
206        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
207            $this =& DB::getInstance();
208        }
209
210        if (!$this->_connected) {
211            return false;
212        }
213
214        return $this->dbh;
215    }
216
217    /**
218     * Returns connection status
219     *
220     * @access  public
221     * @author  Quinn Comendant <quinn@strangecode.com>
222     * @since   28 Aug 2005 14:58:09
223     */
224    function isConnected()
225    {
226        return $this->_connected;
227    }
228   
229    /**
230     * Returns a properly escaped string using mysql_real_escape_string() with the current connection's charset.
231     *
232     * @access  public
233     * @param   string  $string     Input string to be sent as SQL query.
234     * @return  string              Escaped string from mysql_real_escape_string()
235     * @author  Quinn Comendant <quinn@strangecode.com>
236     * @since   06 Mar 2006 16:41:32
237     */
238    function escapeString($string)
239    {
240        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
241            $this =& DB::getInstance();
242        }
243        return mysql_real_escape_string($string, $this->dbh);
244    }
245
246    /**
247     * A wrapper for mysql_query. Allows us to set the database link_identifier,
248     * to trap errors and ease debugging.
249     *
250     * @param  string  $query   The SQL query to execute
251     * @param  bool    $debug   If true, prints debugging info
252     * @return resource         Query identifier
253     */
254    function query($query, $debug=false)
255    {
256        static $_query_count = 0;
257
258        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
259            $this =& DB::getInstance();
260        }
261
262        if (!$this->_connected) {
263           return false;
264        }
265
266        $_query_count++;
267        $debugqry = preg_replace("/\n[\t ]+/", "\n", $query);
268        if ($this->getParam('db_always_debug') || $debug) {
269            echo "<!-- ----------------- Query $_query_count ---------------------\n$debugqry\n-->\n";
270        }
271
272        // Execute!
273        $qid = mysql_query($query, $this->dbh);
274
275        // Error checking.
276        if (!$qid || mysql_error($this->dbh)) {
277            if ($this->getParam('db_debug')) {
278                echo '<pre style="padding:2em; background:#ddd; font:9px monaco;">' . wordwrap(mysql_error($this->dbh)) . '<hr>' . htmlspecialchars($debugqry) . '</pre>';
279            } else {
280                echo _("This page is temporarily unavailable. It should be back up in a few minutes.");
281            }
282            App::logMsg(sprintf('MySQL error %s: %s in query: %s', mysql_errno($this->dbh), mysql_error($this->dbh), $debugqry), LOG_EMERG, __FILE__, __LINE__);
283            if ($this->getParam('db_die_on_failure')) {
284                echo "\n\n<!-- Script execution stopped out of embarrassment. -->";
285                die;
286            }
287        }
288
289        return $qid;
290    }
291
292    /**
293     * Loads a list of tables in the current database into an array, and returns
294     * true if the requested table is found. Use this function to enable/disable
295     * funtionality based upon the current available db tables or to dynamically
296     * create tables if missing.
297     *
298     * @param  string $table    The name of the table to search.
299     * @param  bool   $strict   Get fresh table info (in case DB changed).
300     * @return bool    true if given $table exists.
301     */
302    function tableExists($table, $use_cached_results=true)
303    {
304        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
305            $this =& DB::getInstance();
306        }
307
308        if (!$this->_connected) {
309            return false;
310        }
311
312        if (!isset($this->existing_tables) || !$use_cached_results) {
313            $this->existing_tables = array();
314            $qid = $this->query("SHOW TABLES");
315            while (list($row) = mysql_fetch_row($qid)) {
316                $this->existing_tables[] = $row;
317            }
318        }
319        if (in_array($table, $this->existing_tables)) {
320            return true;
321        } else {
322            App::logMsg(sprintf('nonexistent DB table: %s.%s', $this->getParam('db_name'), $table), LOG_ALERT, __FILE__, __LINE__);
323            return false;
324        }
325    }
326
327    /**
328     * Tests if the given array of columns exists in the specified table.
329     *
330     * @param  string $table    The name of the table to search.
331     * @param  array  $columns  An array of column names.
332     * @param  bool   $strict   Exact schema match, or are additional fields in the table okay?
333     * @param  bool   $strict   Get fresh table info (in case DB changed).
334     * @return bool    true if given $table exists.
335     */
336    function columnExists($table, $columns, $strict=true, $use_cached_results=true)
337    {
338        if (!isset($this) || !is_a($this, 'DB') && !is_subclass_of($this, 'DB')) {
339            $this =& DB::getInstance();
340        }
341
342        if (!$this->_connected) {
343            return false;
344        }
345
346        // Ensure the table exists.
347        if (!$this->tableExists($table, $use_cached_results)) {
348            return false;
349        }
350
351        // For single-value columns.
352        if (!is_array($columns)) {
353            $columns = array($columns);
354        }
355
356        if (!isset($this->table_columns[$table]) || !$use_cached_results) {
357            // Populate and cache array of current columns for this table.
358            $this->table_columns[$table] = array();
359            $qid = $this->query("DESCRIBE $table");
360            while ($row = mysql_fetch_row($qid)) {
361                $this->table_columns[$table][] = $row[0];
362            }
363        }
364
365        if ($strict) {
366            // Do an exact comparison of table schemas.
367            sort($columns);
368            sort($this->table_columns[$table]);
369            return $this->table_columns[$table] == $columns;
370        } else {
371            // Only check that the specified columns are available in the table.
372            $match_columns = array_intersect($this->table_columns[$table], $columns);
373            sort($columns);
374            sort($match_columns);
375            return $match_columns == $columns;
376        }
377    }
378
379    /**
380     * Reset cached items.
381     *
382     * @access  public
383     * @author  Quinn Comendant <quinn@strangecode.com>
384     * @since   28 Aug 2005 22:10:50
385     */
386    function resetCache()
387    {
388        $this->existing_tables = null;
389        $this->table_columns = null;
390    }
391
392} // End.
393
394?>
Note: See TracBrowser for help on using the repository browser.