|
1 <?php |
|
2 /* vim: set expandtab tabstop=4 shiftwidth=4: */ |
|
3 // +----------------------------------------------------------------------+ |
|
4 // | PHP Version 4 | |
|
5 // +----------------------------------------------------------------------+ |
|
6 // | Copyright (c) 1997-2002 The PHP Group | |
|
7 // +----------------------------------------------------------------------+ |
|
8 // | This source file is subject to version 2.02 of the PHP license, | |
|
9 // | that is bundled with this package in the file LICENSE, and is | |
|
10 // | available at through the world-wide-web at | |
|
11 // | http://www.php.net/license/2_02.txt. | |
|
12 // | If you did not receive a copy of the PHP license and are unable to | |
|
13 // | obtain it through the world-wide-web, please send a note to | |
|
14 // | license@php.net so we can mail you a copy immediately. | |
|
15 // +----------------------------------------------------------------------+ |
|
16 // | Authors: Stig Bakken <ssb@fast.no> | |
|
17 // | Tomas V.V.Cox <cox@idecnet.com> | |
|
18 // +----------------------------------------------------------------------+ |
|
19 // |
|
20 // $Id: dal.inc.php,v 1.1 2002/10/27 19:18:42 azurazu Exp $ |
|
21 // |
|
22 // Database independent query interface. |
|
23 // |
|
24 |
|
25 require_once "PEAR.php"; |
|
26 |
|
27 /* |
|
28 * The method mapErrorCode in each DB_dbtype implementation maps |
|
29 * native error codes to one of these. |
|
30 * |
|
31 * If you add an error code here, make sure you also add a textual |
|
32 * version of it in DB::errorMessage(). |
|
33 */ |
|
34 |
|
35 define("DB_OK", 1); |
|
36 define("DB_ERROR", -1); |
|
37 define("DB_ERROR_SYNTAX", -2); |
|
38 define("DB_ERROR_CONSTRAINT", -3); |
|
39 define("DB_ERROR_NOT_FOUND", -4); |
|
40 define("DB_ERROR_ALREADY_EXISTS", -5); |
|
41 define("DB_ERROR_UNSUPPORTED", -6); |
|
42 define("DB_ERROR_MISMATCH", -7); |
|
43 define("DB_ERROR_INVALID", -8); |
|
44 define("DB_ERROR_NOT_CAPABLE", -9); |
|
45 define("DB_ERROR_TRUNCATED", -10); |
|
46 define("DB_ERROR_INVALID_NUMBER", -11); |
|
47 define("DB_ERROR_INVALID_DATE", -12); |
|
48 define("DB_ERROR_DIVZERO", -13); |
|
49 define("DB_ERROR_NODBSELECTED", -14); |
|
50 define("DB_ERROR_CANNOT_CREATE", -15); |
|
51 define("DB_ERROR_CANNOT_DELETE", -16); |
|
52 define("DB_ERROR_CANNOT_DROP", -17); |
|
53 define("DB_ERROR_NOSUCHTABLE", -18); |
|
54 define("DB_ERROR_NOSUCHFIELD", -19); |
|
55 define("DB_ERROR_NEED_MORE_DATA", -20); |
|
56 define("DB_ERROR_NOT_LOCKED", -21); |
|
57 define("DB_ERROR_VALUE_COUNT_ON_ROW", -22); |
|
58 define("DB_ERROR_INVALID_DSN", -23); |
|
59 define("DB_ERROR_CONNECT_FAILED", -24); |
|
60 define("DB_ERROR_EXTENSION_NOT_FOUND",-25); |
|
61 define("DB_ERROR_ACCESS_VIOLATION", -26); |
|
62 define("DB_ERROR_NOSUCHDB", -27); |
|
63 |
|
64 /* |
|
65 * Warnings are not detected as errors by DB::isError(), and are not |
|
66 * fatal. You can detect whether an error is in fact a warning with |
|
67 * DB::isWarning(). |
|
68 * |
|
69 * @deprecated |
|
70 */ |
|
71 |
|
72 define('DB_WARNING', -1000); |
|
73 define('DB_WARNING_READ_ONLY', -1001); |
|
74 |
|
75 /* |
|
76 * These constants are used when storing information about prepared |
|
77 * statements (using the "prepare" method in DB_dbtype). |
|
78 * |
|
79 * The prepare/execute model in DB is mostly borrowed from the ODBC |
|
80 * extension, in a query the "?" character means a scalar parameter. |
|
81 * There are two extensions though, a "&" character means an opaque |
|
82 * parameter. An opaque parameter is simply a file name, the real |
|
83 * data are in that file (useful for putting uploaded files into your |
|
84 * database and such). The "!" char means a parameter that must be |
|
85 * left as it is. |
|
86 * They modify the quote behavoir: |
|
87 * DB_PARAM_SCALAR (?) => 'original string quoted' |
|
88 * DB_PARAM_OPAQUE (&) => 'string from file quoted' |
|
89 * DB_PARAM_MISC (!) => original string |
|
90 */ |
|
91 |
|
92 define('DB_PARAM_SCALAR', 1); |
|
93 define('DB_PARAM_OPAQUE', 2); |
|
94 define('DB_PARAM_MISC', 3); |
|
95 |
|
96 /* |
|
97 * These constants define different ways of returning binary data |
|
98 * from queries. Again, this model has been borrowed from the ODBC |
|
99 * extension. |
|
100 * |
|
101 * DB_BINMODE_PASSTHRU sends the data directly through to the browser |
|
102 * when data is fetched from the database. |
|
103 * DB_BINMODE_RETURN lets you return data as usual. |
|
104 * DB_BINMODE_CONVERT returns data as well, only it is converted to |
|
105 * hex format, for example the string "123" would become "313233". |
|
106 */ |
|
107 |
|
108 define('DB_BINMODE_PASSTHRU', 1); |
|
109 define('DB_BINMODE_RETURN', 2); |
|
110 define('DB_BINMODE_CONVERT', 3); |
|
111 |
|
112 /** |
|
113 * This is a special constant that tells DB the user hasn't specified |
|
114 * any particular get mode, so the default should be used. |
|
115 */ |
|
116 |
|
117 define('DB_FETCHMODE_DEFAULT', 0); |
|
118 |
|
119 /** |
|
120 * Column data indexed by numbers, ordered from 0 and up |
|
121 */ |
|
122 |
|
123 define('DB_FETCHMODE_ORDERED', 1); |
|
124 |
|
125 /** |
|
126 * Column data indexed by column names |
|
127 */ |
|
128 |
|
129 define('DB_FETCHMODE_ASSOC', 2); |
|
130 |
|
131 /** |
|
132 * Column data as object properties |
|
133 */ |
|
134 |
|
135 define('DB_FETCHMODE_OBJECT', 3); |
|
136 |
|
137 /** |
|
138 * For multi-dimensional results: normally the first level of arrays |
|
139 * is the row number, and the second level indexed by column number or name. |
|
140 * DB_FETCHMODE_FLIPPED switches this order, so the first level of arrays |
|
141 * is the column name, and the second level the row number. |
|
142 */ |
|
143 |
|
144 define('DB_FETCHMODE_FLIPPED', 4); |
|
145 |
|
146 /* for compatibility */ |
|
147 |
|
148 define('DB_GETMODE_ORDERED', DB_FETCHMODE_ORDERED); |
|
149 define('DB_GETMODE_ASSOC', DB_FETCHMODE_ASSOC); |
|
150 define('DB_GETMODE_FLIPPED', DB_FETCHMODE_FLIPPED); |
|
151 |
|
152 /** |
|
153 * these are constants for the tableInfo-function |
|
154 * they are bitwised or'ed. so if there are more constants to be defined |
|
155 * in the future, adjust DB_TABLEINFO_FULL accordingly |
|
156 */ |
|
157 |
|
158 define('DB_TABLEINFO_ORDER', 1); |
|
159 define('DB_TABLEINFO_ORDERTABLE', 2); |
|
160 define('DB_TABLEINFO_FULL', 3); |
|
161 |
|
162 /* |
|
163 * Used by autoPrepare() |
|
164 */ |
|
165 define('DB_AUTOQUERY_INSERT', 1); |
|
166 define('DB_AUTOQUERY_UPDATE', 2); |
|
167 |
|
168 |
|
169 /** |
|
170 * The main "DB" class is simply a container class with some static |
|
171 * methods for creating DB objects as well as some utility functions |
|
172 * common to all parts of DB. |
|
173 * |
|
174 * The object model of DB is as follows (indentation means inheritance): |
|
175 * |
|
176 * DB The main DB class. This is simply a utility class |
|
177 * with some "static" methods for creating DB objects as |
|
178 * well as common utility functions for other DB classes. |
|
179 * |
|
180 * DB_common The base for each DB implementation. Provides default |
|
181 * | implementations (in OO lingo virtual methods) for |
|
182 * | the actual DB implementations as well as a bunch of |
|
183 * | query utility functions. |
|
184 * | |
|
185 * +-DB_mysql The DB implementation for MySQL. Inherits DB_common. |
|
186 * When calling DB::factory or DB::connect for MySQL |
|
187 * connections, the object returned is an instance of this |
|
188 * class. |
|
189 * |
|
190 * @package DB |
|
191 * @author Stig Bakken <ssb@fast.no> |
|
192 * @since PHP 4.0 |
|
193 */ |
|
194 |
|
195 class DB |
|
196 { |
|
197 /** |
|
198 * Create a new DB connection object for the specified database |
|
199 * type |
|
200 * |
|
201 * @param string $type database type, for example "mysql" |
|
202 * |
|
203 * @return mixed a newly created DB object, or a DB error code on |
|
204 * error |
|
205 * |
|
206 * access public |
|
207 */ |
|
208 |
|
209 function &factory($type) |
|
210 { |
|
211 @include_once("DB/${type}.php"); |
|
212 |
|
213 $classname = "DB_${type}"; |
|
214 |
|
215 if (!class_exists($classname)) { |
|
216 return PEAR::raiseError(null, DB_ERROR_NOT_FOUND, |
|
217 null, null, null, 'DB_Error', true); |
|
218 } |
|
219 |
|
220 @$obj =& new $classname; |
|
221 |
|
222 return $obj; |
|
223 } |
|
224 |
|
225 /** |
|
226 * Create a new DB connection object and connect to the specified |
|
227 * database |
|
228 * |
|
229 * @param mixed $dsn "data source name", see the DB::parseDSN |
|
230 * method for a description of the dsn format. Can also be |
|
231 * specified as an array of the format returned by DB::parseDSN. |
|
232 * |
|
233 * @param mixed $options An associative array of option names and |
|
234 * their values. For backwards compatibility, this parameter may |
|
235 * also be a boolean that tells whether the connection should be |
|
236 * persistent. See DB_common::setOption for more information on |
|
237 * connection options. |
|
238 * |
|
239 * @return mixed a newly created DB connection object, or a DB |
|
240 * error object on error |
|
241 * |
|
242 * @see DB::parseDSN |
|
243 * @see DB::isError |
|
244 * @see DB_common::setOption |
|
245 */ |
|
246 function &connect($dsn, $options = false) |
|
247 { |
|
248 if (is_array($dsn)) { |
|
249 $dsninfo = $dsn; |
|
250 } else { |
|
251 $dsninfo = DB::parseDSN($dsn); |
|
252 } |
|
253 $type = $dsninfo["phptype"]; |
|
254 |
|
255 if (is_array($options) && isset($options["debug"]) && |
|
256 $options["debug"] >= 2) { |
|
257 // expose php errors with sufficient debug level |
|
258 include_once "DB/${type}.php"; |
|
259 } else { |
|
260 @include_once "DB/${type}.php"; |
|
261 } |
|
262 |
|
263 $classname = "DB_${type}"; |
|
264 if (!class_exists($classname)) { |
|
265 return PEAR::raiseError(null, DB_ERROR_NOT_FOUND, null, null, |
|
266 "Unable to include the DB/{$type}.php file for `$dsn'", |
|
267 'DB_Error', true); |
|
268 } |
|
269 |
|
270 @$obj =& new $classname; |
|
271 |
|
272 if (is_array($options)) { |
|
273 foreach ($options as $option => $value) { |
|
274 $test = $obj->setOption($option, $value); |
|
275 if (DB::isError($test)) { |
|
276 return $test; |
|
277 } |
|
278 } |
|
279 } else { |
|
280 $obj->setOption('persistent', $options); |
|
281 } |
|
282 $err = $obj->connect($dsninfo, $obj->getOption('persistent')); |
|
283 if (DB::isError($err)) { |
|
284 $err->addUserInfo($dsn); |
|
285 return $err; |
|
286 } |
|
287 |
|
288 return $obj; |
|
289 } |
|
290 |
|
291 /** |
|
292 * Return the DB API version |
|
293 * |
|
294 * @return int the DB API version number |
|
295 * |
|
296 * @access public |
|
297 */ |
|
298 function apiVersion() |
|
299 { |
|
300 return 2; |
|
301 } |
|
302 |
|
303 /** |
|
304 * Tell whether a result code from a DB method is an error |
|
305 * |
|
306 * @param int $value result code |
|
307 * |
|
308 * @return bool whether $value is an error |
|
309 * |
|
310 * @access public |
|
311 */ |
|
312 function isError($value) |
|
313 { |
|
314 return (is_object($value) && |
|
315 (get_class($value) == 'db_error' || |
|
316 is_subclass_of($value, 'db_error'))); |
|
317 } |
|
318 |
|
319 /** |
|
320 * Tell whether a value is a DB connection |
|
321 * |
|
322 * @param mixed $value value to test |
|
323 * |
|
324 * @return bool whether $value is a DB connection |
|
325 * |
|
326 * @access public |
|
327 */ |
|
328 function isConnection($value) |
|
329 { |
|
330 return (is_object($value) && |
|
331 is_subclass_of($value, 'db_common') && |
|
332 method_exists($value, 'simpleQuery')); |
|
333 } |
|
334 |
|
335 /** |
|
336 * Tell whether a query is a data manipulation query (insert, |
|
337 * update or delete) or a data definition query (create, drop, |
|
338 * alter, grant, revoke). |
|
339 * |
|
340 * @access public |
|
341 * |
|
342 * @param string $query the query |
|
343 * |
|
344 * @return boolean whether $query is a data manipulation query |
|
345 */ |
|
346 function isManip($query) |
|
347 { |
|
348 $manips = 'INSERT|UPDATE|DELETE|'.'REPLACE|CREATE|DROP|'. |
|
349 'ALTER|GRANT|REVOKE|'.'LOCK|UNLOCK'; |
|
350 if (preg_match('/^\s*"?('.$manips.')\s+/i', $query)) { |
|
351 return true; |
|
352 } |
|
353 return false; |
|
354 } |
|
355 |
|
356 /** |
|
357 * Return a textual error message for a DB error code |
|
358 * |
|
359 * @param integer $value error code |
|
360 * |
|
361 * @return string error message, or false if the error code was |
|
362 * not recognized |
|
363 */ |
|
364 function errorMessage($value) |
|
365 { |
|
366 static $errorMessages; |
|
367 if (!isset($errorMessages)) { |
|
368 $errorMessages = array( |
|
369 DB_ERROR => 'unknown error', |
|
370 DB_ERROR_ALREADY_EXISTS => 'already exists', |
|
371 DB_ERROR_CANNOT_CREATE => 'can not create', |
|
372 DB_ERROR_CANNOT_DELETE => 'can not delete', |
|
373 DB_ERROR_CANNOT_DROP => 'can not drop', |
|
374 DB_ERROR_CONSTRAINT => 'constraint violation', |
|
375 DB_ERROR_DIVZERO => 'division by zero', |
|
376 DB_ERROR_INVALID => 'invalid', |
|
377 DB_ERROR_INVALID_DATE => 'invalid date or time', |
|
378 DB_ERROR_INVALID_NUMBER => 'invalid number', |
|
379 DB_ERROR_MISMATCH => 'mismatch', |
|
380 DB_ERROR_NODBSELECTED => 'no database selected', |
|
381 DB_ERROR_NOSUCHFIELD => 'no such field', |
|
382 DB_ERROR_NOSUCHTABLE => 'no such table', |
|
383 DB_ERROR_NOT_CAPABLE => 'DB backend not capable', |
|
384 DB_ERROR_NOT_FOUND => 'not found', |
|
385 DB_ERROR_NOT_LOCKED => 'not locked', |
|
386 DB_ERROR_SYNTAX => 'syntax error', |
|
387 DB_ERROR_UNSUPPORTED => 'not supported', |
|
388 DB_ERROR_VALUE_COUNT_ON_ROW => 'value count on row', |
|
389 DB_ERROR_INVALID_DSN => 'invalid DSN', |
|
390 DB_ERROR_CONNECT_FAILED => 'connect failed', |
|
391 DB_OK => 'no error', |
|
392 DB_WARNING => 'unknown warning', |
|
393 DB_WARNING_READ_ONLY => 'read only', |
|
394 DB_ERROR_NEED_MORE_DATA => 'insufficient data supplied', |
|
395 DB_ERROR_EXTENSION_NOT_FOUND=> 'extension not found', |
|
396 DB_ERROR_NOSUCHDB => 'no such database', |
|
397 DB_ERROR_ACCESS_VIOLATION => 'insufficient permissions' |
|
398 ); |
|
399 } |
|
400 |
|
401 if (DB::isError($value)) { |
|
402 $value = $value->getCode(); |
|
403 } |
|
404 |
|
405 return isset($errorMessages[$value]) ? $errorMessages[$value] : $errorMessages[DB_ERROR]; |
|
406 } |
|
407 |
|
408 /** |
|
409 * Parse a data source name |
|
410 * |
|
411 * A array with the following keys will be returned: |
|
412 * phptype: Database backend used in PHP (mysql, odbc etc.) |
|
413 * dbsyntax: Database used with regards to SQL syntax etc. |
|
414 * protocol: Communication protocol to use (tcp, unix etc.) |
|
415 * hostspec: Host specification (hostname[:port]) |
|
416 * database: Database to use on the DBMS server |
|
417 * username: User name for login |
|
418 * password: Password for login |
|
419 * |
|
420 * The format of the supplied DSN is in its fullest form: |
|
421 * |
|
422 * phptype(dbsyntax)://username:password@protocol+hostspec/database |
|
423 * |
|
424 * Most variations are allowed: |
|
425 * |
|
426 * phptype://username:password@protocol+hostspec:110//usr/db_file.db |
|
427 * phptype://username:password@hostspec/database_name |
|
428 * phptype://username:password@hostspec |
|
429 * phptype://username@hostspec |
|
430 * phptype://hostspec/database |
|
431 * phptype://hostspec |
|
432 * phptype(dbsyntax) |
|
433 * phptype |
|
434 * |
|
435 * @param string $dsn Data Source Name to be parsed |
|
436 * |
|
437 * @return array an associative array |
|
438 * |
|
439 * @author Tomas V.V.Cox <cox@idecnet.com> |
|
440 */ |
|
441 function parseDSN($dsn) |
|
442 { |
|
443 if (is_array($dsn)) { |
|
444 return $dsn; |
|
445 } |
|
446 |
|
447 $parsed = array( |
|
448 'phptype' => false, |
|
449 'dbsyntax' => false, |
|
450 'username' => false, |
|
451 'password' => false, |
|
452 'protocol' => false, |
|
453 'hostspec' => false, |
|
454 'port' => false, |
|
455 'socket' => false, |
|
456 'database' => false |
|
457 ); |
|
458 |
|
459 // Find phptype and dbsyntax |
|
460 if (($pos = strpos($dsn, '://')) !== false) { |
|
461 $str = substr($dsn, 0, $pos); |
|
462 $dsn = substr($dsn, $pos + 3); |
|
463 } else { |
|
464 $str = $dsn; |
|
465 $dsn = NULL; |
|
466 } |
|
467 |
|
468 // Get phptype and dbsyntax |
|
469 // $str => phptype(dbsyntax) |
|
470 if (preg_match('|^(.+?)\((.*?)\)$|', $str, $arr)) { |
|
471 $parsed['phptype'] = $arr[1]; |
|
472 $parsed['dbsyntax'] = (empty($arr[2])) ? $arr[1] : $arr[2]; |
|
473 } else { |
|
474 $parsed['phptype'] = $str; |
|
475 $parsed['dbsyntax'] = $str; |
|
476 } |
|
477 |
|
478 if (empty($dsn)) { |
|
479 return $parsed; |
|
480 } |
|
481 |
|
482 // Get (if found): username and password |
|
483 // $dsn => username:password@protocol+hostspec/database |
|
484 if (($at = strrpos($dsn,'@')) !== false) { |
|
485 $str = substr($dsn, 0, $at); |
|
486 $dsn = substr($dsn, $at + 1); |
|
487 if (($pos = strpos($str, ':')) !== false) { |
|
488 $parsed['username'] = urldecode(substr($str, 0, $pos)); |
|
489 $parsed['password'] = urldecode(substr($str, $pos + 1)); |
|
490 } else { |
|
491 $parsed['username'] = urldecode($str); |
|
492 } |
|
493 } |
|
494 |
|
495 // Find protocol and hostspec |
|
496 |
|
497 // $dsn => proto(proto_opts)/database |
|
498 if (preg_match('|^([^(]+)\((.*?)\)/?(.*?)$|', $dsn, $match)) { |
|
499 $proto = $match[1]; |
|
500 $proto_opts = (!empty($match[2])) ? $match[2] : false; |
|
501 $dsn = $match[3]; |
|
502 |
|
503 // $dsn => protocol+hostspec/database (old format) |
|
504 } else { |
|
505 if (strpos($dsn, '+') !== false) { |
|
506 list($proto, $dsn) = explode('+', $dsn, 2); |
|
507 } |
|
508 if (strpos($dsn, '/') !== false) { |
|
509 list($proto_opts, $dsn) = explode('/', $dsn, 2); |
|
510 } else { |
|
511 $proto_opts = $dsn; |
|
512 $dsn = null; |
|
513 } |
|
514 } |
|
515 |
|
516 // process the different protocol options |
|
517 $parsed['protocol'] = (!empty($proto)) ? $proto : 'tcp'; |
|
518 $proto_opts = urldecode($proto_opts); |
|
519 if ($parsed['protocol'] == 'tcp') { |
|
520 if (strpos($proto_opts, ':') !== false) { |
|
521 list($parsed['hostspec'], $parsed['port']) = explode(':', $proto_opts); |
|
522 } else { |
|
523 $parsed['hostspec'] = $proto_opts; |
|
524 } |
|
525 } elseif ($parsed['protocol'] == 'unix') { |
|
526 $parsed['socket'] = $proto_opts; |
|
527 } |
|
528 |
|
529 // Get dabase if any |
|
530 // $dsn => database |
|
531 if (!empty($dsn)) { |
|
532 // /database |
|
533 if (($pos = strpos($dsn, '?')) === false) { |
|
534 $parsed['database'] = $dsn; |
|
535 // /database?param1=value1¶m2=value2 |
|
536 } else { |
|
537 $parsed['database'] = substr($dsn, 0, $pos); |
|
538 $dsn = substr($dsn, $pos + 1); |
|
539 if (strpos($dsn, '&') !== false) { |
|
540 $opts = explode('&', $dsn); |
|
541 } else { // database?param1=value1 |
|
542 $opts = array($dsn); |
|
543 } |
|
544 foreach ($opts as $opt) { |
|
545 list($key, $value) = explode('=', $opt); |
|
546 if (!isset($parsed[$key])) { // don't allow params overwrite |
|
547 $parsed[$key] = urldecode($value); |
|
548 } |
|
549 } |
|
550 } |
|
551 } |
|
552 |
|
553 return $parsed; |
|
554 } |
|
555 |
|
556 /** |
|
557 * Load a PHP database extension if it is not loaded already. |
|
558 * |
|
559 * @access public |
|
560 * |
|
561 * @param string $name the base name of the extension (without the .so or |
|
562 * .dll suffix) |
|
563 * |
|
564 * @return boolean true if the extension was already or successfully |
|
565 * loaded, false if it could not be loaded |
|
566 */ |
|
567 function assertExtension($name) |
|
568 { |
|
569 if (!extension_loaded($name)) { |
|
570 $dlext = OS_WINDOWS ? '.dll' : '.so'; |
|
571 @dl($name . $dlext); |
|
572 return extension_loaded($name); |
|
573 } |
|
574 return true; |
|
575 } |
|
576 } |
|
577 |
|
578 /** |
|
579 * DB_Error implements a class for reporting portable database error |
|
580 * messages. |
|
581 * |
|
582 * @package DB |
|
583 * @author Stig Bakken <ssb@fast.no> |
|
584 */ |
|
585 class DB_Error extends PEAR_Error |
|
586 { |
|
587 /** |
|
588 * DB_Error constructor. |
|
589 * |
|
590 * @param mixed $code DB error code, or string with error message. |
|
591 * @param integer $mode what "error mode" to operate in |
|
592 * @param integer $level what error level to use for $mode & PEAR_ERROR_TRIGGER |
|
593 * @param mixed $debuginfo additional debug info, such as the last query |
|
594 * |
|
595 * @access public |
|
596 * |
|
597 * @see PEAR_Error |
|
598 */ |
|
599 |
|
600 function DB_Error($code = DB_ERROR, $mode = PEAR_ERROR_RETURN, |
|
601 $level = E_USER_NOTICE, $debuginfo = null) |
|
602 { |
|
603 if (is_int($code)) { |
|
604 $this->PEAR_Error('DB Error: ' . DB::errorMessage($code), $code, $mode, $level, $debuginfo); |
|
605 } else { |
|
606 $this->PEAR_Error("DB Error: $code", DB_ERROR, $mode, $level, $debuginfo); |
|
607 } |
|
608 } |
|
609 } |
|
610 |
|
611 /** |
|
612 * This class implements a wrapper for a DB result set. |
|
613 * A new instance of this class will be returned by the DB implementation |
|
614 * after processing a query that returns data. |
|
615 * |
|
616 * @package DB |
|
617 * @author Stig Bakken <ssb@fast.no> |
|
618 */ |
|
619 |
|
620 class DB_result |
|
621 { |
|
622 var $dbh; |
|
623 var $result; |
|
624 var $row_counter = null; |
|
625 /** |
|
626 * for limit queries, the row to start fetching |
|
627 * @var integer |
|
628 */ |
|
629 var $limit_from = null; |
|
630 |
|
631 /** |
|
632 * for limit queries, the number of rows to fetch |
|
633 * @var integer |
|
634 */ |
|
635 var $limit_count = null; |
|
636 |
|
637 /** |
|
638 * DB_result constructor. |
|
639 * @param resource &$dbh DB object reference |
|
640 * @param resource $result result resource id |
|
641 */ |
|
642 |
|
643 function DB_result(&$dbh, $result, $options = array()) |
|
644 { |
|
645 $this->dbh = &$dbh; |
|
646 $this->result = $result; |
|
647 $this->limit_from = isset($options['limit_from']) ? $options['limit_from'] : null; |
|
648 $this->limit_count = isset($options['limit_count']) ? $options['limit_count'] : null; |
|
649 $this->limit_type = $dbh->features['limit']; |
|
650 $this->autofree = $dbh->options['autofree']; |
|
651 $this->fetchmode = $dbh->fetchmode; |
|
652 $this->fetchmode_object_class = $dbh->fetchmode_object_class; |
|
653 } |
|
654 |
|
655 /** |
|
656 * Fetch and return a row of data (it uses driver->fetchInto for that) |
|
657 * @param int $fetchmode format of fetched row |
|
658 * @param int $rownum the row number to fetch |
|
659 * |
|
660 * @return array a row of data, NULL on no more rows or PEAR_Error on error |
|
661 * |
|
662 * @access public |
|
663 */ |
|
664 function fetchRow($fetchmode = DB_FETCHMODE_DEFAULT, $rownum=null) |
|
665 { |
|
666 if ($fetchmode === DB_FETCHMODE_DEFAULT) { |
|
667 $fetchmode = $this->fetchmode; |
|
668 } |
|
669 if ($fetchmode === DB_FETCHMODE_OBJECT) { |
|
670 $fetchmode = DB_FETCHMODE_ASSOC; |
|
671 $object_class = $this->fetchmode_object_class; |
|
672 } |
|
673 if ($this->limit_from !== null) { |
|
674 if ($this->row_counter === null) { |
|
675 $this->row_counter = $this->limit_from; |
|
676 // Skip rows |
|
677 if ($this->limit_type == false) { |
|
678 $i = 0; |
|
679 while ($i++ < $this->limit_from) { |
|
680 $this->dbh->fetchInto($this->result, $arr, $fetchmode); |
|
681 } |
|
682 } |
|
683 } |
|
684 if ($this->row_counter >= ( |
|
685 $this->limit_from + $this->limit_count)) |
|
686 { |
|
687 return null; |
|
688 } |
|
689 if ($this->limit_type == 'emulate') { |
|
690 $rownum = $this->row_counter; |
|
691 } |
|
692 |
|
693 $this->row_counter++; |
|
694 } |
|
695 $res = $this->dbh->fetchInto($this->result, $arr, $fetchmode, $rownum); |
|
696 if ($res !== DB_OK) { |
|
697 if ($res == null && $this->autofree) { |
|
698 $this->free(); |
|
699 } |
|
700 return $res; |
|
701 } |
|
702 if (isset($object_class)) { |
|
703 // default mode specified in DB_common::fetchmode_object_class property |
|
704 if ($object_class == 'stdClass') { |
|
705 $ret = (object) $arr; |
|
706 } else { |
|
707 $ret =& new $object_class($arr); |
|
708 } |
|
709 return $ret; |
|
710 } |
|
711 return $arr; |
|
712 } |
|
713 |
|
714 /** |
|
715 * Fetch a row of data into an existing variable. |
|
716 * |
|
717 * @param mixed &$arr reference to data containing the row |
|
718 * @param integer $fetchmod format of fetched row |
|
719 * @param integer $rownum the row number to fetch |
|
720 * |
|
721 * @return mixed DB_OK on success, NULL on no more rows or |
|
722 * a DB_Error object on error |
|
723 * |
|
724 * @access public |
|
725 */ |
|
726 function fetchInto(&$arr, $fetchmode = DB_FETCHMODE_DEFAULT, $rownum=null) |
|
727 { |
|
728 if ($fetchmode === DB_FETCHMODE_DEFAULT) { |
|
729 $fetchmode = $this->fetchmode; |
|
730 } |
|
731 if ($fetchmode === DB_FETCHMODE_OBJECT) { |
|
732 $fetchmode = DB_FETCHMODE_ASSOC; |
|
733 $object_class = $this->fetchmode_object_class; |
|
734 } |
|
735 if ($this->limit_from !== null) { |
|
736 if ($this->row_counter === null) { |
|
737 $this->row_counter = $this->limit_from; |
|
738 // Skip rows |
|
739 if ($this->limit_type == false) { |
|
740 $i = 0; |
|
741 while ($i++ < $this->limit_from) { |
|
742 $this->dbh->fetchInto($this->result, $arr, $fetchmode); |
|
743 } |
|
744 } |
|
745 } |
|
746 if ($this->row_counter >= ( |
|
747 $this->limit_from + $this->limit_count)) |
|
748 { |
|
749 return null; |
|
750 } |
|
751 if ($this->limit_type == 'emulate') { |
|
752 $rownum = $this->row_counter; |
|
753 } |
|
754 |
|
755 $this->row_counter++; |
|
756 } |
|
757 $res = $this->dbh->fetchInto($this->result, $arr, $fetchmode, $rownum); |
|
758 if (($res === DB_OK) && isset($object_class)) { |
|
759 // default mode specified in DB_common::fetchmode_object_class property |
|
760 if ($object_class == 'stdClass') { |
|
761 $arr = (object) $arr; |
|
762 } else { |
|
763 $arr = new $object_class($arr); |
|
764 } |
|
765 } elseif ($res == null && $this->autofree) { |
|
766 $this->free(); |
|
767 } |
|
768 return $res; |
|
769 } |
|
770 |
|
771 /** |
|
772 * Get the the number of columns in a result set. |
|
773 * |
|
774 * @return int the number of columns, or a DB error |
|
775 * |
|
776 * @access public |
|
777 */ |
|
778 function numCols() |
|
779 { |
|
780 return $this->dbh->numCols($this->result); |
|
781 } |
|
782 |
|
783 /** |
|
784 * Get the number of rows in a result set. |
|
785 * |
|
786 * @return int the number of rows, or a DB error |
|
787 * |
|
788 * @access public |
|
789 */ |
|
790 function numRows() |
|
791 { |
|
792 return $this->dbh->numRows($this->result); |
|
793 } |
|
794 |
|
795 /** |
|
796 * Get the next result if a batch of queries was executed. |
|
797 * |
|
798 * @return bool true if a new result is available or false if not. |
|
799 * |
|
800 * @access public |
|
801 */ |
|
802 function nextResult() |
|
803 { |
|
804 return $this->dbh->nextResult($this->result); |
|
805 } |
|
806 |
|
807 /** |
|
808 * Frees the resources allocated for this result set. |
|
809 * @return int error code |
|
810 * |
|
811 * @access public |
|
812 */ |
|
813 function free() |
|
814 { |
|
815 $err = $this->dbh->freeResult($this->result); |
|
816 if(DB::isError($err)) { |
|
817 return $err; |
|
818 } |
|
819 $this->result = false; |
|
820 return true; |
|
821 } |
|
822 |
|
823 /** |
|
824 * @deprecated |
|
825 */ |
|
826 function tableInfo($mode = null) |
|
827 { |
|
828 return $this->dbh->tableInfo($this->result, $mode); |
|
829 } |
|
830 |
|
831 /** |
|
832 * returns the actual row number |
|
833 * @return integer |
|
834 */ |
|
835 function getRowCounter() |
|
836 { |
|
837 return $this->row_counter; |
|
838 } |
|
839 } |
|
840 |
|
841 /** |
|
842 * Pear DB Row Object |
|
843 * @see DB_common::setFetchMode() |
|
844 */ |
|
845 class DB_row |
|
846 { |
|
847 /** |
|
848 * constructor |
|
849 * |
|
850 * @param resource row data as array |
|
851 */ |
|
852 function DB_row(&$arr) |
|
853 { |
|
854 for (reset($arr); $key = key($arr); next($arr)) { |
|
855 $this->$key = &$arr[$key]; |
|
856 } |
|
857 } |
|
858 } |
|
859 |
|
860 ?> |