2 /*=====================================================================*\
3 || ###################################################################
4 || # app [#]issoversion[#]
5 || # Copyright ©2002-[#]year[#] Iris Studios, Inc.
7 || # This program is free software; you can redistribute it and/or modify
8 || # it under the terms of the GNU General Public License as published by
9 || # the Free Software Foundation; version [#]gpl[#] of the License.
11 || # This program is distributed in the hope that it will be useful, but
12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
16 || # You should have received a copy of the GNU General Public License along
17 || # with this program; if not, write to the Free Software Foundation, Inc.,
18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
19 || ###################################################################
20 \*=====================================================================*/
23 * Abstract Database Layer
30 * Abstract Database Layer
32 * This class provides an abstract template for all RDBMS layers. All
33 * ISSO abstraction layers should inherit this class. It provides error
34 * reporting, SQL analysis, and general connection functionality.
37 * [required] ISSO_DB_LAYER - The name of the DB layer module used in the application
38 * ISSO_SHOW_QUERIES_LIVE - Show queries in page output as they are sent
40 * @author Iris Studios, Inc.
41 * @copyright Copyright ©2002 - [#]year[#], Iris Studios, Inc.
49 * Framework registry object
56 * Determines whether or not errors should be shown
60 var $showerrors = true
;
63 * Current error number
70 * Description of current error
77 * Currend open MySQL connexion
91 * Current query string
98 * History of all executed queryies
102 var $history = array();
105 * Command mapping list
109 var $commands = array(
110 'pconnect' => '%server %user %password %database',
111 'connect' => '%server %user %password %database',
112 'query' => '%link %query',
113 'error_num' => '%link',
114 'error_str' => '%link',
115 'escape_string' => '%link %string',
116 'escape_binary' => '%string',
117 'unescape_binary' => '%string',
118 'fetch_assoc' => '%result',
119 'fetch_row' => '%result',
120 'fetch_object' => '%result',
121 'free_result' => '%result',
122 'insert_id' => '%link',
123 'num_rows' => '%result',
124 'affected_rows' => '%result'
127 // ###################################################################
131 function __construct(&$registry)
133 $this->registry
=& $registry;
135 // because ivars and call_user_func() are conspiring against us...
136 foreach ($this->commands
AS $key => $string)
138 if (strpos($string, '$this->') !== false
)
140 $this->commands
["$key"] = array($this, str_replace('$this->', '', $string));
145 // ###################################################################
147 * (PHP 4) Constructor
149 function DB_Abstract(&$registry)
151 $this->__construct($registry);
154 // ###################################################################
156 * Initializes the class and all subclasses under a common package name
160 * @return string The package name
162 function init_as_package()
164 if (!defined('ISSO_DB_LAYER'))
166 define('ISSO_DB_LAYER', get_class($this));
167 trigger_error('ISSO_DB_LAYER was defined automatically by DB::init_as_package(). Define the constant yourself to remove this warning', E_USER_WARNING
);
173 // ###################################################################
175 * Connect to a the specified database
179 * @param string Server name
180 * @param string User name
181 * @param string Password
182 * @param string Database name
183 * @param bool Use p-connect?
185 * @return bool Result of connect
187 function connect($server, $user, $password, $database, $pconnect)
189 $this->registry
->check_isso_fields(get_class($this));
191 if ($this->dblink
== false
)
193 $this->dblink
= call_user_func(($pconnect ?
$this->commands
['pconnect'] : $this->commands
['connect']), $server, $user, $password, $database);
195 if ($this->dblink
== false
)
197 $this->error('DB-Link == false, cannot connect');
205 // ###################################################################
207 * Send a query to the open database link
211 * @param string Query string
213 * @return integer Result
215 function query($string)
219 $this->querystr
= $string;
220 $this->result
= @call_user_func($this->commands
['query'], $this->dblink
, $string);
224 $this->error('Invalid SQL query');
227 $this->history
[] = $history = array('query' => $string, 'time' => ($this->registry
->is_loaded('functions') ?
$this->registry
->modules
['functions']->fetch_microtime_diff($time) : 0), 'trace' => $this->registry
->format_debug_trace(debug_backtrace()));
229 if (defined('ISSO_SHOW_QUERIES_LIVE'))
231 if (constant('ISSO_SHOW_QUERIES_LIVE'))
233 print($this->construct_query_debug($history));
237 return $this->result
;
240 // ###################################################################
242 * Escape a string (depending on character set, if supported)
246 * @param string String to be escaped
248 * @return string Escaped string
250 function escape_string($string)
252 return call_user_func($this->commands
['escape_string'], $this->dblink
, $string);
255 // ###################################################################
257 * Escapes a binary string for insertion into the database
261 * @param string Unescaped data
263 * @return string Escaped binary data
265 function escape_binary($binary)
267 return call_user_func($this->commands
['escape_binary'], $binary);
270 // ###################################################################
272 * Unescapes a binary string that was fetched from the database
276 * @param string Escaped data
278 * @return string Unescaped binary data
280 function unescape_binary($binary)
282 return call_user_func($this->commands
['unescape_binary'], $binary);
285 // ###################################################################
287 * Fetch the query result as an array
291 * @param integer Result
292 * @param bool Return an associative array?
294 * @return array A row of the query result
296 function fetch_array($result, $assoc = true
)
298 return call_user_func($this->commands
[ ($assoc ?
'fetch_assoc' : 'fetch_row') ], $result);
301 // ###################################################################
303 * Fetch the query result as an object
307 * @param integer Result
309 * @return object An object with the query result
311 function fetch_object($result)
313 return call_user_func($this->commands
['fetch_object'], $result);
316 // ###################################################################
318 * Send a query and return the first row of the results
322 * @param string Query string
323 * @param string Result return function (in the database layer)
325 * @return mixed Results in variable formats
327 function query_first($string, $callback = 'fetch_array')
329 $resource = $this->query($string);
332 $return = $this->$callback($resource);
333 $this->free_result($resource);
342 // ###################################################################
344 * Free the current query result
348 * @param integer Result
350 function free_result($result)
352 call_user_func($this->commands
['free_result'], $result);
353 $this->result
= null
;
354 $this->querystr
= '';
357 // ###################################################################
359 * Fetch the unique ID of the record just inserted
363 * @return integer Insert-ID
367 return call_user_func($this->commands
['insert_id'], $this->dblink
);
370 // ###################################################################
372 * Fetch the number of rows in the result
376 * @param integer Result
378 * @return integer Number of rows
380 function num_rows($result)
382 return call_user_func($this->commands
['num_rows'], $result);
385 // ###################################################################
387 * Fetch the number of rows affected by the query
391 * @param integer Result
393 * @return integer Number of affected rows
395 function affected_rows($result)
397 return call_user_func($this->commands
['affected_rows'], $result);
400 // ###################################################################
402 * Sends the command to start a transaction. This command should never
403 * be reached as it's always overridden
407 function transaction_start()
409 trigger_error('DB_Abstract::transaction_start() needs to be overridden when subclassed', E_USER_ERROR
);
412 // ###################################################################
414 * Sends the command to set this as a savepoint. This command should never
415 * be reached as it's always overridden
419 * @param string Named savepoint
421 function transaction_savepoint($name)
423 trigger_error('DB_Abstract::transaction_savepoint() needs to be overridden when subclassed', E_USER_ERROR
);
426 // ###################################################################
428 * Sends the command to rollback to a given savepoint. This command
429 * should never be reached as it's always overridden
433 * @param string Named savepoint
435 function transaction_rollback($name)
437 trigger_error('DB_Abstract::transaction_rollback() needs to be overridden when subclassed', E_USER_ERROR
);
440 // ###################################################################
442 * Sends the command to commit the entire transaction. This command
443 * should never be reached as it's always overridden
447 function transaction_commit($name)
449 trigger_error('DB_Abstract::transaction_commit() needs to be overridden when subclassed', E_USER_ERROR
);
452 // ###################################################################
454 * Constructs a table of query information output that is used in some
455 * other modules to display a list of queries. This merely formats
456 * a DB->history array entry nicely
460 * @param array An entry from DB->history
462 * @return string A formatted table block
464 function construct_query_debug($query)
466 $block = "<strong>Query:</strong>\n\n<div>" . $this->registry
->entity_encode($query['query']) . "</div>\n";
467 $block .= "<tr style=\"background-color: #FFFFFF; text-align: left\">\n\t<td>\n\t\t";
468 $block .= "<strong>Time:</strong> $query[time]<br />\n\t\t<br />\n\t\t";
469 $block .= "<strong>Backtrace:</strong>\n\t\t<div>" . implode("<br />\n", $query['trace']) . "</div>\n\t</td>\n</tr>";
471 return $this->registry
->message('Query Debug', $block, 1, true
, false
, 0);
474 // ###################################################################
476 * Error wrapper for ISSO->message()
480 * @param string User defined error message
482 function error($message)
484 if ($this->showerrors
)
488 $this->errnum
= call_user_func($this->commands
['error_num'], $this->dblink
);
489 $this->errstr
= call_user_func($this->commands
['error_str'], $this->dblink
);
492 $style['code'] = 'font-family: \'Courier New\', Courier, mono; font-size: 11px;';
494 $message_prepped = "<blockquote>\n<p>";
495 $message_prepped .= "\n\t» <strong>Query:</strong>\n<br /> <pre style=\"$style[code]\">" . htmlspecialchars($this->querystr
) ."</pre>\n<br />";
496 $message_prepped .= "\n\t» <strong>Error Number:</strong> <span style=\"$style[code]\">" . $this->errnum
. "</span>\n<br />";
497 $message_prepped .= "\n\t» <strong>Error Message:</strong> <span style=\"$style[code]\">" . $this->errstr
. "</span>\n<br />";
498 $message_prepped .= "\n\t» <strong>Additional Notes:</strong> <span style=\"$style[code]\">" . $message . "</span>\n<br />";
499 $message_prepped .= "\n\t» <strong>File:</strong> <span style=\"$style[code]\">" . $_SERVER['PHP_SELF'] . "</span>\n";
500 $message_prepped .= "\n</p>\n</blockquote>";
502 $this->registry
->message('Database Error in `<em>' . $this->registry
->application
. '</em>`', $message_prepped, 3);
508 /*=====================================================================*\
509 || ###################################################################
512 || ###################################################################
513 \*=====================================================================*/