| 1 | <?php |
---|
| 2 | |
---|
| 3 | /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ |
---|
| 4 | |
---|
| 5 | /** |
---|
| 6 | * Database independent query interface |
---|
| 7 | * |
---|
| 8 | * PHP versions 4 and 5 |
---|
| 9 | * |
---|
| 10 | * LICENSE: This source file is subject to version 3.0 of the PHP license |
---|
| 11 | * that is available through the world-wide-web at the following URI: |
---|
| 12 | * http://www.php.net/license/3_0.txt. If you did not receive a copy of |
---|
| 13 | * the PHP License and are unable to obtain it through the web, please |
---|
| 14 | * send a note to license@php.net so we can mail you a copy immediately. |
---|
| 15 | * |
---|
| 16 | * @category Database |
---|
| 17 | * @package DB |
---|
| 18 | * @author Stig Bakken <ssb@php.net> |
---|
| 19 | * @author Tomas V.V.Cox <cox@idecnet.com> |
---|
| 20 | * @author Daniel Convissor <danielc@php.net> |
---|
| 21 | * @copyright 1997-2005 The PHP Group |
---|
| 22 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
---|
| 23 | * @version CVS: $Id$ |
---|
| 24 | * @link http://pear.php.net/package/DB |
---|
| 25 | */ |
---|
| 26 | |
---|
| 27 | /** |
---|
| 28 | * Obtain the PEAR class so it can be extended from |
---|
| 29 | */ |
---|
| 30 | |
---|
| 31 | if(!defined('DB_PHP_DIR')) { |
---|
| 32 | $DB_PHP_DIR = realpath(dirname( __FILE__)); |
---|
| 33 | define("DB_PHP_DIR", $DB_PHP_DIR); |
---|
| 34 | } |
---|
| 35 | |
---|
| 36 | require_once DB_PHP_DIR . '/PEAR.php'; |
---|
| 37 | |
---|
| 38 | // {{{ constants |
---|
| 39 | // {{{ error codes |
---|
| 40 | |
---|
| 41 | /**#@+ |
---|
| 42 | * One of PEAR DB's portable error codes. |
---|
| 43 | * @see DB_common::errorCode(), DB::errorMessage() |
---|
| 44 | * |
---|
| 45 | * {@internal If you add an error code here, make sure you also add a textual |
---|
| 46 | * version of it in DB::errorMessage().}} |
---|
| 47 | */ |
---|
| 48 | |
---|
| 49 | /** |
---|
| 50 | * The code returned by many methods upon success |
---|
| 51 | */ |
---|
| 52 | define('DB_OK', 1); |
---|
| 53 | |
---|
| 54 | /** |
---|
| 55 | * Unkown error |
---|
| 56 | */ |
---|
| 57 | define('DB_ERROR', -1); |
---|
| 58 | |
---|
| 59 | /** |
---|
| 60 | * Syntax error |
---|
| 61 | */ |
---|
| 62 | define('DB_ERROR_SYNTAX', -2); |
---|
| 63 | |
---|
| 64 | /** |
---|
| 65 | * Tried to insert a duplicate value into a primary or unique index |
---|
| 66 | */ |
---|
| 67 | define('DB_ERROR_CONSTRAINT', -3); |
---|
| 68 | |
---|
| 69 | /** |
---|
| 70 | * An identifier in the query refers to a non-existant object |
---|
| 71 | */ |
---|
| 72 | define('DB_ERROR_NOT_FOUND', -4); |
---|
| 73 | |
---|
| 74 | /** |
---|
| 75 | * Tried to create a duplicate object |
---|
| 76 | */ |
---|
| 77 | define('DB_ERROR_ALREADY_EXISTS', -5); |
---|
| 78 | |
---|
| 79 | /** |
---|
| 80 | * The current driver does not support the action you attempted |
---|
| 81 | */ |
---|
| 82 | define('DB_ERROR_UNSUPPORTED', -6); |
---|
| 83 | |
---|
| 84 | /** |
---|
| 85 | * The number of parameters does not match the number of placeholders |
---|
| 86 | */ |
---|
| 87 | define('DB_ERROR_MISMATCH', -7); |
---|
| 88 | |
---|
| 89 | /** |
---|
| 90 | * A literal submitted did not match the data type expected |
---|
| 91 | */ |
---|
| 92 | define('DB_ERROR_INVALID', -8); |
---|
| 93 | |
---|
| 94 | /** |
---|
| 95 | * The current DBMS does not support the action you attempted |
---|
| 96 | */ |
---|
| 97 | define('DB_ERROR_NOT_CAPABLE', -9); |
---|
| 98 | |
---|
| 99 | /** |
---|
| 100 | * A literal submitted was too long so the end of it was removed |
---|
| 101 | */ |
---|
| 102 | define('DB_ERROR_TRUNCATED', -10); |
---|
| 103 | |
---|
| 104 | /** |
---|
| 105 | * A literal number submitted did not match the data type expected |
---|
| 106 | */ |
---|
| 107 | define('DB_ERROR_INVALID_NUMBER', -11); |
---|
| 108 | |
---|
| 109 | /** |
---|
| 110 | * A literal date submitted did not match the data type expected |
---|
| 111 | */ |
---|
| 112 | define('DB_ERROR_INVALID_DATE', -12); |
---|
| 113 | |
---|
| 114 | /** |
---|
| 115 | * Attempt to divide something by zero |
---|
| 116 | */ |
---|
| 117 | define('DB_ERROR_DIVZERO', -13); |
---|
| 118 | |
---|
| 119 | /** |
---|
| 120 | * A database needs to be selected |
---|
| 121 | */ |
---|
| 122 | define('DB_ERROR_NODBSELECTED', -14); |
---|
| 123 | |
---|
| 124 | /** |
---|
| 125 | * Could not create the object requested |
---|
| 126 | */ |
---|
| 127 | define('DB_ERROR_CANNOT_CREATE', -15); |
---|
| 128 | |
---|
| 129 | /** |
---|
| 130 | * Could not drop the database requested because it does not exist |
---|
| 131 | */ |
---|
| 132 | define('DB_ERROR_CANNOT_DROP', -17); |
---|
| 133 | |
---|
| 134 | /** |
---|
| 135 | * An identifier in the query refers to a non-existant table |
---|
| 136 | */ |
---|
| 137 | define('DB_ERROR_NOSUCHTABLE', -18); |
---|
| 138 | |
---|
| 139 | /** |
---|
| 140 | * An identifier in the query refers to a non-existant column |
---|
| 141 | */ |
---|
| 142 | define('DB_ERROR_NOSUCHFIELD', -19); |
---|
| 143 | |
---|
| 144 | /** |
---|
| 145 | * The data submitted to the method was inappropriate |
---|
| 146 | */ |
---|
| 147 | define('DB_ERROR_NEED_MORE_DATA', -20); |
---|
| 148 | |
---|
| 149 | /** |
---|
| 150 | * The attempt to lock the table failed |
---|
| 151 | */ |
---|
| 152 | define('DB_ERROR_NOT_LOCKED', -21); |
---|
| 153 | |
---|
| 154 | /** |
---|
| 155 | * The number of columns doesn't match the number of values |
---|
| 156 | */ |
---|
| 157 | define('DB_ERROR_VALUE_COUNT_ON_ROW', -22); |
---|
| 158 | |
---|
| 159 | /** |
---|
| 160 | * The DSN submitted has problems |
---|
| 161 | */ |
---|
| 162 | define('DB_ERROR_INVALID_DSN', -23); |
---|
| 163 | |
---|
| 164 | /** |
---|
| 165 | * Could not connect to the database |
---|
| 166 | */ |
---|
| 167 | define('DB_ERROR_CONNECT_FAILED', -24); |
---|
| 168 | |
---|
| 169 | /** |
---|
| 170 | * The PHP extension needed for this DBMS could not be found |
---|
| 171 | */ |
---|
| 172 | define('DB_ERROR_EXTENSION_NOT_FOUND',-25); |
---|
| 173 | |
---|
| 174 | /** |
---|
| 175 | * The present user has inadequate permissions to perform the task requestd |
---|
| 176 | */ |
---|
| 177 | define('DB_ERROR_ACCESS_VIOLATION', -26); |
---|
| 178 | |
---|
| 179 | /** |
---|
| 180 | * The database requested does not exist |
---|
| 181 | */ |
---|
| 182 | define('DB_ERROR_NOSUCHDB', -27); |
---|
| 183 | |
---|
| 184 | /** |
---|
| 185 | * Tried to insert a null value into a column that doesn't allow nulls |
---|
| 186 | */ |
---|
| 187 | define('DB_ERROR_CONSTRAINT_NOT_NULL',-29); |
---|
| 188 | /**#@-*/ |
---|
| 189 | |
---|
| 190 | |
---|
| 191 | // }}} |
---|
| 192 | // {{{ prepared statement-related |
---|
| 193 | |
---|
| 194 | |
---|
| 195 | /**#@+ |
---|
| 196 | * Identifiers for the placeholders used in prepared statements. |
---|
| 197 | * @see DB_common::prepare() |
---|
| 198 | */ |
---|
| 199 | |
---|
| 200 | /** |
---|
| 201 | * Indicates a scalar (<kbd>?</kbd>) placeholder was used |
---|
| 202 | * |
---|
| 203 | * Quote and escape the value as necessary. |
---|
| 204 | */ |
---|
| 205 | define('DB_PARAM_SCALAR', 1); |
---|
| 206 | |
---|
| 207 | /** |
---|
| 208 | * Indicates an opaque (<kbd>&</kbd>) placeholder was used |
---|
| 209 | * |
---|
| 210 | * The value presented is a file name. Extract the contents of that file |
---|
| 211 | * and place them in this column. |
---|
| 212 | */ |
---|
| 213 | define('DB_PARAM_OPAQUE', 2); |
---|
| 214 | |
---|
| 215 | /** |
---|
| 216 | * Indicates a misc (<kbd>!</kbd>) placeholder was used |
---|
| 217 | * |
---|
| 218 | * The value should not be quoted or escaped. |
---|
| 219 | */ |
---|
| 220 | define('DB_PARAM_MISC', 3); |
---|
| 221 | /**#@-*/ |
---|
| 222 | |
---|
| 223 | |
---|
| 224 | // }}} |
---|
| 225 | // {{{ binary data-related |
---|
| 226 | |
---|
| 227 | |
---|
| 228 | /**#@+ |
---|
| 229 | * The different ways of returning binary data from queries. |
---|
| 230 | */ |
---|
| 231 | |
---|
| 232 | /** |
---|
| 233 | * Sends the fetched data straight through to output |
---|
| 234 | */ |
---|
| 235 | define('DB_BINMODE_PASSTHRU', 1); |
---|
| 236 | |
---|
| 237 | /** |
---|
| 238 | * Lets you return data as usual |
---|
| 239 | */ |
---|
| 240 | define('DB_BINMODE_RETURN', 2); |
---|
| 241 | |
---|
| 242 | /** |
---|
| 243 | * Converts the data to hex format before returning it |
---|
| 244 | * |
---|
| 245 | * For example the string "123" would become "313233". |
---|
| 246 | */ |
---|
| 247 | define('DB_BINMODE_CONVERT', 3); |
---|
| 248 | /**#@-*/ |
---|
| 249 | |
---|
| 250 | |
---|
| 251 | // }}} |
---|
| 252 | // {{{ fetch modes |
---|
| 253 | |
---|
| 254 | |
---|
| 255 | /**#@+ |
---|
| 256 | * Fetch Modes. |
---|
| 257 | * @see DB_common::setFetchMode() |
---|
| 258 | */ |
---|
| 259 | |
---|
| 260 | /** |
---|
| 261 | * Indicates the current default fetch mode should be used |
---|
| 262 | * @see DB_common::$fetchmode |
---|
| 263 | */ |
---|
| 264 | define('DB_FETCHMODE_DEFAULT', 0); |
---|
| 265 | |
---|
| 266 | /** |
---|
| 267 | * Column data indexed by numbers, ordered from 0 and up |
---|
| 268 | */ |
---|
| 269 | define('DB_FETCHMODE_ORDERED', 1); |
---|
| 270 | |
---|
| 271 | /** |
---|
| 272 | * Column data indexed by column names |
---|
| 273 | */ |
---|
| 274 | define('DB_FETCHMODE_ASSOC', 2); |
---|
| 275 | |
---|
| 276 | /** |
---|
| 277 | * Column data as object properties |
---|
| 278 | */ |
---|
| 279 | define('DB_FETCHMODE_OBJECT', 3); |
---|
| 280 | |
---|
| 281 | /** |
---|
| 282 | * For multi-dimensional results, make the column name the first level |
---|
| 283 | * of the array and put the row number in the second level of the array |
---|
| 284 | * |
---|
| 285 | * This is flipped from the normal behavior, which puts the row numbers |
---|
| 286 | * in the first level of the array and the column names in the second level. |
---|
| 287 | */ |
---|
| 288 | define('DB_FETCHMODE_FLIPPED', 4); |
---|
| 289 | /**#@-*/ |
---|
| 290 | |
---|
| 291 | /**#@+ |
---|
| 292 | * Old fetch modes. Left here for compatibility. |
---|
| 293 | */ |
---|
| 294 | define('DB_GETMODE_ORDERED', DB_FETCHMODE_ORDERED); |
---|
| 295 | define('DB_GETMODE_ASSOC', DB_FETCHMODE_ASSOC); |
---|
| 296 | define('DB_GETMODE_FLIPPED', DB_FETCHMODE_FLIPPED); |
---|
| 297 | /**#@-*/ |
---|
| 298 | |
---|
| 299 | |
---|
| 300 | // }}} |
---|
| 301 | // {{{ tableInfo() && autoPrepare()-related |
---|
| 302 | |
---|
| 303 | |
---|
| 304 | /**#@+ |
---|
| 305 | * The type of information to return from the tableInfo() method. |
---|
| 306 | * |
---|
| 307 | * Bitwised constants, so they can be combined using <kbd>|</kbd> |
---|
| 308 | * and removed using <kbd>^</kbd>. |
---|
| 309 | * |
---|
| 310 | * @see DB_common::tableInfo() |
---|
| 311 | * |
---|
| 312 | * {@internal Since the TABLEINFO constants are bitwised, if more of them are |
---|
| 313 | * added in the future, make sure to adjust DB_TABLEINFO_FULL accordingly.}} |
---|
| 314 | */ |
---|
| 315 | define('DB_TABLEINFO_ORDER', 1); |
---|
| 316 | define('DB_TABLEINFO_ORDERTABLE', 2); |
---|
| 317 | define('DB_TABLEINFO_FULL', 3); |
---|
| 318 | /**#@-*/ |
---|
| 319 | |
---|
| 320 | |
---|
| 321 | /**#@+ |
---|
| 322 | * The type of query to create with the automatic query building methods. |
---|
| 323 | * @see DB_common::autoPrepare(), DB_common::autoExecute() |
---|
| 324 | */ |
---|
| 325 | define('DB_AUTOQUERY_INSERT', 1); |
---|
| 326 | define('DB_AUTOQUERY_UPDATE', 2); |
---|
| 327 | /**#@-*/ |
---|
| 328 | |
---|
| 329 | |
---|
| 330 | // }}} |
---|
| 331 | // {{{ portability modes |
---|
| 332 | |
---|
| 333 | |
---|
| 334 | /**#@+ |
---|
| 335 | * Portability Modes. |
---|
| 336 | * |
---|
| 337 | * Bitwised constants, so they can be combined using <kbd>|</kbd> |
---|
| 338 | * and removed using <kbd>^</kbd>. |
---|
| 339 | * |
---|
| 340 | * @see DB_common::setOption() |
---|
| 341 | * |
---|
| 342 | * {@internal Since the PORTABILITY constants are bitwised, if more of them are |
---|
| 343 | * added in the future, make sure to adjust DB_PORTABILITY_ALL accordingly.}} |
---|
| 344 | */ |
---|
| 345 | |
---|
| 346 | /** |
---|
| 347 | * Turn off all portability features |
---|
| 348 | */ |
---|
| 349 | define('DB_PORTABILITY_NONE', 0); |
---|
| 350 | |
---|
| 351 | /** |
---|
| 352 | * Convert names of tables and fields to lower case |
---|
| 353 | * when using the get*(), fetch*() and tableInfo() methods |
---|
| 354 | */ |
---|
| 355 | define('DB_PORTABILITY_LOWERCASE', 1); |
---|
| 356 | |
---|
| 357 | /** |
---|
| 358 | * Right trim the data output by get*() and fetch*() |
---|
| 359 | */ |
---|
| 360 | define('DB_PORTABILITY_RTRIM', 2); |
---|
| 361 | |
---|
| 362 | /** |
---|
| 363 | * Force reporting the number of rows deleted |
---|
| 364 | */ |
---|
| 365 | define('DB_PORTABILITY_DELETE_COUNT', 4); |
---|
| 366 | |
---|
| 367 | /** |
---|
| 368 | * Enable hack that makes numRows() work in Oracle |
---|
| 369 | */ |
---|
| 370 | define('DB_PORTABILITY_NUMROWS', 8); |
---|
| 371 | |
---|
| 372 | /** |
---|
| 373 | * Makes certain error messages in certain drivers compatible |
---|
| 374 | * with those from other DBMS's |
---|
| 375 | * |
---|
| 376 | * + mysql, mysqli: change unique/primary key constraints |
---|
| 377 | * DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT |
---|
| 378 | * |
---|
| 379 | * + odbc(access): MS's ODBC driver reports 'no such field' as code |
---|
| 380 | * 07001, which means 'too few parameters.' When this option is on |
---|
| 381 | * that code gets mapped to DB_ERROR_NOSUCHFIELD. |
---|
| 382 | */ |
---|
| 383 | define('DB_PORTABILITY_ERRORS', 16); |
---|
| 384 | |
---|
| 385 | /** |
---|
| 386 | * Convert null values to empty strings in data output by |
---|
| 387 | * get*() and fetch*() |
---|
| 388 | */ |
---|
| 389 | define('DB_PORTABILITY_NULL_TO_EMPTY', 32); |
---|
| 390 | |
---|
| 391 | /** |
---|
| 392 | * Turn on all portability features |
---|
| 393 | */ |
---|
| 394 | define('DB_PORTABILITY_ALL', 63); |
---|
| 395 | /**#@-*/ |
---|
| 396 | |
---|
| 397 | // }}} |
---|
| 398 | |
---|
| 399 | |
---|
| 400 | // }}} |
---|
| 401 | // {{{ class DB |
---|
| 402 | |
---|
| 403 | /** |
---|
| 404 | * Database independent query interface |
---|
| 405 | * |
---|
| 406 | * The main "DB" class is simply a container class with some static |
---|
| 407 | * methods for creating DB objects as well as some utility functions |
---|
| 408 | * common to all parts of DB. |
---|
| 409 | * |
---|
| 410 | * The object model of DB is as follows (indentation means inheritance): |
---|
| 411 | * <pre> |
---|
| 412 | * DB The main DB class. This is simply a utility class |
---|
| 413 | * with some "static" methods for creating DB objects as |
---|
| 414 | * well as common utility functions for other DB classes. |
---|
| 415 | * |
---|
| 416 | * DB_common The base for each DB implementation. Provides default |
---|
| 417 | * | implementations (in OO lingo virtual methods) for |
---|
| 418 | * | the actual DB implementations as well as a bunch of |
---|
| 419 | * | query utility functions. |
---|
| 420 | * | |
---|
| 421 | * +-DB_mysql The DB implementation for MySQL. Inherits DB_common. |
---|
| 422 | * When calling DB::factory or DB::connect for MySQL |
---|
| 423 | * connections, the object returned is an instance of this |
---|
| 424 | * class. |
---|
| 425 | * </pre> |
---|
| 426 | * |
---|
| 427 | * @category Database |
---|
| 428 | * @package DB |
---|
| 429 | * @author Stig Bakken <ssb@php.net> |
---|
| 430 | * @author Tomas V.V.Cox <cox@idecnet.com> |
---|
| 431 | * @author Daniel Convissor <danielc@php.net> |
---|
| 432 | * @copyright 1997-2005 The PHP Group |
---|
| 433 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
---|
| 434 | * @version Release: @package_version@ |
---|
| 435 | * @link http://pear.php.net/package/DB |
---|
| 436 | */ |
---|
| 437 | class DB |
---|
| 438 | { |
---|
| 439 | // {{{ &factory() |
---|
| 440 | |
---|
| 441 | /** |
---|
| 442 | * Create a new DB object for the specified database type but don't |
---|
| 443 | * connect to the database |
---|
| 444 | * |
---|
| 445 | * @param string $type the database type (eg "mysql") |
---|
| 446 | * @param array $options an associative array of option names and values |
---|
| 447 | * |
---|
| 448 | * @return object a new DB object. A DB_Error object on failure. |
---|
| 449 | * |
---|
| 450 | * @see DB_common::setOption() |
---|
| 451 | */ |
---|
| 452 | function &factory($type, $options = false) |
---|
| 453 | { |
---|
| 454 | if (!is_array($options)) { |
---|
| 455 | $options = array('persistent' => $options); |
---|
| 456 | } |
---|
| 457 | |
---|
| 458 | if (isset($options['debug']) && $options['debug'] >= 2) { |
---|
| 459 | // expose php errors with sufficient debug level |
---|
| 460 | include_once DB_PHP_DIR . "/DB/{$type}.php"; |
---|
| 461 | } else { |
---|
| 462 | @include_once DB_PHP_DIR . "/DB/{$type}.php"; |
---|
| 463 | } |
---|
| 464 | |
---|
| 465 | $classname = "DB_${type}"; |
---|
| 466 | |
---|
| 467 | if (!class_exists($classname)) { |
---|
| 468 | $tmp = PEAR::raiseError(null, DB_ERROR_NOT_FOUND, null, null, |
---|
| 469 | "Unable to include the DB/{$type}.php" |
---|
| 470 | . " file for '$dsn'", |
---|
| 471 | 'DB_Error', true); |
---|
| 472 | return $tmp; |
---|
| 473 | } |
---|
| 474 | |
---|
| 475 | @$obj =& new $classname; |
---|
| 476 | |
---|
| 477 | foreach ($options as $option => $value) { |
---|
| 478 | $test = $obj->setOption($option, $value); |
---|
| 479 | if (DB::isError($test)) { |
---|
| 480 | return $test; |
---|
| 481 | } |
---|
| 482 | } |
---|
| 483 | |
---|
| 484 | return $obj; |
---|
| 485 | } |
---|
| 486 | |
---|
| 487 | // }}} |
---|
| 488 | // {{{ &connect() |
---|
| 489 | |
---|
| 490 | /** |
---|
| 491 | * Create a new DB object including a connection to the specified database |
---|
| 492 | * |
---|
| 493 | * Example 1. |
---|
| 494 | * <code> |
---|
| 495 | * require_once 'DB.php'; |
---|
| 496 | * |
---|
| 497 | * $dsn = 'pgsql://user:password@host/database'; |
---|
| 498 | * $options = array( |
---|
| 499 | * 'debug' => 2, |
---|
| 500 | * 'portability' => DB_PORTABILITY_ALL, |
---|
| 501 | * ); |
---|
| 502 | * |
---|
| 503 | * $db =& DB::connect($dsn, $options); |
---|
| 504 | * if (PEAR::isError($db)) { |
---|
| 505 | * die($db->getMessage()); |
---|
| 506 | * } |
---|
| 507 | * </code> |
---|
| 508 | * |
---|
| 509 | * @param mixed $dsn the string "data source name" or array in the |
---|
| 510 | * format returned by DB::parseDSN() |
---|
| 511 | * @param array $options an associative array of option names and values |
---|
| 512 | * |
---|
| 513 | * @return object a new DB object. A DB_Error object on failure. |
---|
| 514 | * |
---|
| 515 | * @uses DB_dbase::connect(), DB_fbsql::connect(), DB_ibase::connect(), |
---|
| 516 | * DB_ifx::connect(), DB_msql::connect(), DB_mssql::connect(), |
---|
| 517 | * DB_mysql::connect(), DB_mysqli::connect(), DB_oci8::connect(), |
---|
| 518 | * DB_odbc::connect(), DB_pgsql::connect(), DB_sqlite::connect(), |
---|
| 519 | * DB_sybase::connect() |
---|
| 520 | * |
---|
| 521 | * @uses DB::parseDSN(), DB_common::setOption(), PEAR::isError() |
---|
| 522 | */ |
---|
| 523 | function &connect($dsn, $options = array()) |
---|
| 524 | { |
---|
| 525 | $dsninfo = DB::parseDSN($dsn); |
---|
| 526 | $type = $dsninfo['phptype']; |
---|
| 527 | |
---|
| 528 | if (!is_array($options)) { |
---|
| 529 | /* |
---|
| 530 | * For backwards compatibility. $options used to be boolean, |
---|
| 531 | * indicating whether the connection should be persistent. |
---|
| 532 | */ |
---|
| 533 | $options = array('persistent' => $options); |
---|
| 534 | } |
---|
| 535 | |
---|
| 536 | if (isset($options['debug']) && $options['debug'] >= 2) { |
---|
| 537 | // expose php errors with sufficient debug level |
---|
| 538 | include_once DB_PHP_DIR . "/DB/${type}.php"; |
---|
| 539 | } else { |
---|
| 540 | @include_once DB_PHP_DIR . "/DB/${type}.php"; |
---|
| 541 | } |
---|
| 542 | |
---|
| 543 | $classname = "DB_${type}"; |
---|
| 544 | if (!class_exists($classname)) { |
---|
| 545 | $tmp = PEAR::raiseError(null, DB_ERROR_NOT_FOUND, null, null, |
---|
| 546 | "Unable to include the DB/{$type}.php" |
---|
| 547 | . " file for '$dsn'", |
---|
| 548 | 'DB_Error', true); |
---|
| 549 | return $tmp; |
---|
| 550 | } |
---|
| 551 | |
---|
| 552 | @$obj =& new $classname; |
---|
| 553 | |
---|
| 554 | foreach ($options as $option => $value) { |
---|
| 555 | $test = $obj->setOption($option, $value); |
---|
| 556 | if (DB::isError($test)) { |
---|
| 557 | return $test; |
---|
| 558 | } |
---|
| 559 | } |
---|
| 560 | |
---|
| 561 | $err = $obj->connect($dsninfo, $obj->getOption('persistent')); |
---|
| 562 | if (DB::isError($err)) { |
---|
| 563 | $err->addUserInfo($dsn); |
---|
| 564 | return $err; |
---|
| 565 | } |
---|
| 566 | |
---|
| 567 | return $obj; |
---|
| 568 | } |
---|
| 569 | |
---|
| 570 | // }}} |
---|
| 571 | // {{{ apiVersion() |
---|
| 572 | |
---|
| 573 | /** |
---|
| 574 | * Return the DB API version |
---|
| 575 | * |
---|
| 576 | * @return string the DB API version number |
---|
| 577 | */ |
---|
| 578 | function apiVersion() |
---|
| 579 | { |
---|
| 580 | return '@package_version@'; |
---|
| 581 | } |
---|
| 582 | |
---|
| 583 | // }}} |
---|
| 584 | // {{{ isError() |
---|
| 585 | |
---|
| 586 | /** |
---|
| 587 | * Determines if a variable is a DB_Error object |
---|
| 588 | * |
---|
| 589 | * @param mixed $value the variable to check |
---|
| 590 | * |
---|
| 591 | * @return bool whether $value is DB_Error object |
---|
| 592 | */ |
---|
| 593 | function isError($value) |
---|
| 594 | { |
---|
| 595 | return is_a($value, 'DB_Error'); |
---|
| 596 | } |
---|
| 597 | |
---|
| 598 | // }}} |
---|
| 599 | // {{{ isConnection() |
---|
| 600 | |
---|
| 601 | /** |
---|
| 602 | * Determines if a value is a DB_<driver> object |
---|
| 603 | * |
---|
| 604 | * @param mixed $value the value to test |
---|
| 605 | * |
---|
| 606 | * @return bool whether $value is a DB_<driver> object |
---|
| 607 | */ |
---|
| 608 | function isConnection($value) |
---|
| 609 | { |
---|
| 610 | return (is_object($value) && |
---|
| 611 | is_subclass_of($value, 'db_common') && |
---|
| 612 | method_exists($value, 'simpleQuery')); |
---|
| 613 | } |
---|
| 614 | |
---|
| 615 | // }}} |
---|
| 616 | // {{{ isManip() |
---|
| 617 | |
---|
| 618 | /** |
---|
| 619 | * Tell whether a query is a data manipulation or data definition query |
---|
| 620 | * |
---|
| 621 | * Examples of data manipulation queries are INSERT, UPDATE and DELETE. |
---|
| 622 | * Examples of data definition queries are CREATE, DROP, ALTER, GRANT, |
---|
| 623 | * REVOKE. |
---|
| 624 | * |
---|
| 625 | * @param string $query the query |
---|
| 626 | * |
---|
| 627 | * @return boolean whether $query is a data manipulation query |
---|
| 628 | */ |
---|
| 629 | function isManip($query) |
---|
| 630 | { |
---|
| 631 | $manips = 'INSERT|UPDATE|DELETE|REPLACE|' |
---|
| 632 | . 'CREATE|DROP|' |
---|
| 633 | . 'LOAD DATA|SELECT .* INTO|COPY|' |
---|
| 634 | . 'ALTER|GRANT|REVOKE|' |
---|
| 635 | . 'LOCK|UNLOCK'; |
---|
| 636 | if (preg_match('/^\s*"?(' . $manips . ')\s+/i', $query)) { |
---|
| 637 | return true; |
---|
| 638 | } |
---|
| 639 | return false; |
---|
| 640 | } |
---|
| 641 | |
---|
| 642 | // }}} |
---|
| 643 | // {{{ errorMessage() |
---|
| 644 | |
---|
| 645 | /** |
---|
| 646 | * Return a textual error message for a DB error code |
---|
| 647 | * |
---|
| 648 | * @param integer $value the DB error code |
---|
| 649 | * |
---|
| 650 | * @return string the error message or false if the error code was |
---|
| 651 | * not recognized |
---|
| 652 | */ |
---|
| 653 | function errorMessage($value) |
---|
| 654 | { |
---|
| 655 | static $errorMessages; |
---|
| 656 | if (!isset($errorMessages)) { |
---|
| 657 | $errorMessages = array( |
---|
| 658 | DB_ERROR => 'unknown error', |
---|
| 659 | DB_ERROR_ACCESS_VIOLATION => 'insufficient permissions', |
---|
| 660 | DB_ERROR_ALREADY_EXISTS => 'already exists', |
---|
| 661 | DB_ERROR_CANNOT_CREATE => 'can not create', |
---|
| 662 | DB_ERROR_CANNOT_DROP => 'can not drop', |
---|
| 663 | DB_ERROR_CONNECT_FAILED => 'connect failed', |
---|
| 664 | DB_ERROR_CONSTRAINT => 'constraint violation', |
---|
| 665 | DB_ERROR_CONSTRAINT_NOT_NULL=> 'null value violates not-null constraint', |
---|
| 666 | DB_ERROR_DIVZERO => 'division by zero', |
---|
| 667 | DB_ERROR_EXTENSION_NOT_FOUND=> 'extension not found', |
---|
| 668 | DB_ERROR_INVALID => 'invalid', |
---|
| 669 | DB_ERROR_INVALID_DATE => 'invalid date or time', |
---|
| 670 | DB_ERROR_INVALID_DSN => 'invalid DSN', |
---|
| 671 | DB_ERROR_INVALID_NUMBER => 'invalid number', |
---|
| 672 | DB_ERROR_MISMATCH => 'mismatch', |
---|
| 673 | DB_ERROR_NEED_MORE_DATA => 'insufficient data supplied', |
---|
| 674 | DB_ERROR_NODBSELECTED => 'no database selected', |
---|
| 675 | DB_ERROR_NOSUCHDB => 'no such database', |
---|
| 676 | DB_ERROR_NOSUCHFIELD => 'no such field', |
---|
| 677 | DB_ERROR_NOSUCHTABLE => 'no such table', |
---|
| 678 | DB_ERROR_NOT_CAPABLE => 'DB backend not capable', |
---|
| 679 | DB_ERROR_NOT_FOUND => 'not found', |
---|
| 680 | DB_ERROR_NOT_LOCKED => 'not locked', |
---|
| 681 | DB_ERROR_SYNTAX => 'syntax error', |
---|
| 682 | DB_ERROR_UNSUPPORTED => 'not supported', |
---|
| 683 | DB_ERROR_TRUNCATED => 'truncated', |
---|
| 684 | DB_ERROR_VALUE_COUNT_ON_ROW => 'value count on row', |
---|
| 685 | DB_OK => 'no error', |
---|
| 686 | ); |
---|
| 687 | } |
---|
| 688 | |
---|
| 689 | if (DB::isError($value)) { |
---|
| 690 | $value = $value->getCode(); |
---|
| 691 | } |
---|
| 692 | |
---|
| 693 | return isset($errorMessages[$value]) ? $errorMessages[$value] |
---|
| 694 | : $errorMessages[DB_ERROR]; |
---|
| 695 | } |
---|
| 696 | |
---|
| 697 | // }}} |
---|
| 698 | // {{{ parseDSN() |
---|
| 699 | |
---|
| 700 | /** |
---|
| 701 | * Parse a data source name |
---|
| 702 | * |
---|
| 703 | * Additional keys can be added by appending a URI query string to the |
---|
| 704 | * end of the DSN. |
---|
| 705 | * |
---|
| 706 | * The format of the supplied DSN is in its fullest form: |
---|
| 707 | * <code> |
---|
| 708 | * phptype(dbsyntax)://username:password@protocol+hostspec/database?option=8&another=true |
---|
| 709 | * </code> |
---|
| 710 | * |
---|
| 711 | * Most variations are allowed: |
---|
| 712 | * <code> |
---|
| 713 | * phptype://username:password@protocol+hostspec:110//usr/db_file.db?mode=0644 |
---|
| 714 | * phptype://username:password@hostspec/database_name |
---|
| 715 | * phptype://username:password@hostspec |
---|
| 716 | * phptype://username@hostspec |
---|
| 717 | * phptype://hostspec/database |
---|
| 718 | * phptype://hostspec |
---|
| 719 | * phptype(dbsyntax) |
---|
| 720 | * phptype |
---|
| 721 | * </code> |
---|
| 722 | * |
---|
| 723 | * @param string $dsn Data Source Name to be parsed |
---|
| 724 | * |
---|
| 725 | * @return array an associative array with the following keys: |
---|
| 726 | * + phptype: Database backend used in PHP (mysql, odbc etc.) |
---|
| 727 | * + dbsyntax: Database used with regards to SQL syntax etc. |
---|
| 728 | * + protocol: Communication protocol to use (tcp, unix etc.) |
---|
| 729 | * + hostspec: Host specification (hostname[:port]) |
---|
| 730 | * + database: Database to use on the DBMS server |
---|
| 731 | * + username: User name for login |
---|
| 732 | * + password: Password for login |
---|
| 733 | */ |
---|
| 734 | function parseDSN($dsn) |
---|
| 735 | { |
---|
| 736 | $parsed = array( |
---|
| 737 | 'phptype' => false, |
---|
| 738 | 'dbsyntax' => false, |
---|
| 739 | 'username' => false, |
---|
| 740 | 'password' => false, |
---|
| 741 | 'protocol' => false, |
---|
| 742 | 'hostspec' => false, |
---|
| 743 | 'port' => false, |
---|
| 744 | 'socket' => false, |
---|
| 745 | 'database' => false, |
---|
| 746 | ); |
---|
| 747 | |
---|
| 748 | if (is_array($dsn)) { |
---|
| 749 | $dsn = array_merge($parsed, $dsn); |
---|
| 750 | if (!$dsn['dbsyntax']) { |
---|
| 751 | $dsn['dbsyntax'] = $dsn['phptype']; |
---|
| 752 | } |
---|
| 753 | return $dsn; |
---|
| 754 | } |
---|
| 755 | |
---|
| 756 | // Find phptype and dbsyntax |
---|
| 757 | if (($pos = strpos($dsn, '://')) !== false) { |
---|
| 758 | $str = substr($dsn, 0, $pos); |
---|
| 759 | $dsn = substr($dsn, $pos + 3); |
---|
| 760 | } else { |
---|
| 761 | $str = $dsn; |
---|
| 762 | $dsn = null; |
---|
| 763 | } |
---|
| 764 | |
---|
| 765 | // Get phptype and dbsyntax |
---|
| 766 | // $str => phptype(dbsyntax) |
---|
| 767 | if (preg_match('|^(.+?)\((.*?)\)$|', $str, $arr)) { |
---|
| 768 | $parsed['phptype'] = $arr[1]; |
---|
| 769 | $parsed['dbsyntax'] = !$arr[2] ? $arr[1] : $arr[2]; |
---|
| 770 | } else { |
---|
| 771 | $parsed['phptype'] = $str; |
---|
| 772 | $parsed['dbsyntax'] = $str; |
---|
| 773 | } |
---|
| 774 | |
---|
| 775 | if (!count($dsn)) { |
---|
| 776 | return $parsed; |
---|
| 777 | } |
---|
| 778 | |
---|
| 779 | // Get (if found): username and password |
---|
| 780 | // $dsn => username:password@protocol+hostspec/database |
---|
| 781 | if (($at = strrpos($dsn,'@')) !== false) { |
---|
| 782 | $str = substr($dsn, 0, $at); |
---|
| 783 | $dsn = substr($dsn, $at + 1); |
---|
| 784 | if (($pos = strpos($str, ':')) !== false) { |
---|
| 785 | $parsed['username'] = rawurldecode(substr($str, 0, $pos)); |
---|
| 786 | $parsed['password'] = rawurldecode(substr($str, $pos + 1)); |
---|
| 787 | } else { |
---|
| 788 | $parsed['username'] = rawurldecode($str); |
---|
| 789 | } |
---|
| 790 | } |
---|
| 791 | |
---|
| 792 | // Find protocol and hostspec |
---|
| 793 | |
---|
| 794 | if (preg_match('|^([^(]+)\((.*?)\)/?(.*?)$|', $dsn, $match)) { |
---|
| 795 | // $dsn => proto(proto_opts)/database |
---|
| 796 | $proto = $match[1]; |
---|
| 797 | $proto_opts = $match[2] ? $match[2] : false; |
---|
| 798 | $dsn = $match[3]; |
---|
| 799 | |
---|
| 800 | } else { |
---|
| 801 | // $dsn => protocol+hostspec/database (old format) |
---|
| 802 | if (strpos($dsn, '+') !== false) { |
---|
| 803 | list($proto, $dsn) = explode('+', $dsn, 2); |
---|
| 804 | } |
---|
| 805 | if (strpos($dsn, '/') !== false) { |
---|
| 806 | list($proto_opts, $dsn) = explode('/', $dsn, 2); |
---|
| 807 | } else { |
---|
| 808 | $proto_opts = $dsn; |
---|
| 809 | $dsn = null; |
---|
| 810 | } |
---|
| 811 | } |
---|
| 812 | |
---|
| 813 | // process the different protocol options |
---|
| 814 | $parsed['protocol'] = (!empty($proto)) ? $proto : 'tcp'; |
---|
| 815 | $proto_opts = rawurldecode($proto_opts); |
---|
| 816 | if ($parsed['protocol'] == 'tcp') { |
---|
| 817 | if (strpos($proto_opts, ':') !== false) { |
---|
| 818 | list($parsed['hostspec'], |
---|
| 819 | $parsed['port']) = explode(':', $proto_opts); |
---|
| 820 | } else { |
---|
| 821 | $parsed['hostspec'] = $proto_opts; |
---|
| 822 | } |
---|
| 823 | } elseif ($parsed['protocol'] == 'unix') { |
---|
| 824 | $parsed['socket'] = $proto_opts; |
---|
| 825 | } |
---|
| 826 | |
---|
| 827 | // Get dabase if any |
---|
| 828 | // $dsn => database |
---|
| 829 | if ($dsn) { |
---|
| 830 | if (($pos = strpos($dsn, '?')) === false) { |
---|
| 831 | // /database |
---|
| 832 | $parsed['database'] = rawurldecode($dsn); |
---|
| 833 | } else { |
---|
| 834 | // /database?param1=value1¶m2=value2 |
---|
| 835 | $parsed['database'] = rawurldecode(substr($dsn, 0, $pos)); |
---|
| 836 | $dsn = substr($dsn, $pos + 1); |
---|
| 837 | if (strpos($dsn, '&') !== false) { |
---|
| 838 | $opts = explode('&', $dsn); |
---|
| 839 | } else { // database?param1=value1 |
---|
| 840 | $opts = array($dsn); |
---|
| 841 | } |
---|
| 842 | foreach ($opts as $opt) { |
---|
| 843 | list($key, $value) = explode('=', $opt); |
---|
| 844 | if (!isset($parsed[$key])) { |
---|
| 845 | // don't allow params overwrite |
---|
| 846 | $parsed[$key] = rawurldecode($value); |
---|
| 847 | } |
---|
| 848 | } |
---|
| 849 | } |
---|
| 850 | } |
---|
| 851 | |
---|
| 852 | return $parsed; |
---|
| 853 | } |
---|
| 854 | |
---|
| 855 | // }}} |
---|
| 856 | } |
---|
| 857 | |
---|
| 858 | // }}} |
---|
| 859 | // {{{ class DB_Error |
---|
| 860 | |
---|
| 861 | /** |
---|
| 862 | * DB_Error implements a class for reporting portable database error |
---|
| 863 | * messages |
---|
| 864 | * |
---|
| 865 | * @category Database |
---|
| 866 | * @package DB |
---|
| 867 | * @author Stig Bakken <ssb@php.net> |
---|
| 868 | * @copyright 1997-2005 The PHP Group |
---|
| 869 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
---|
| 870 | * @version Release: @package_version@ |
---|
| 871 | * @link http://pear.php.net/package/DB |
---|
| 872 | */ |
---|
| 873 | class DB_Error extends PEAR_Error |
---|
| 874 | { |
---|
| 875 | // {{{ constructor |
---|
| 876 | |
---|
| 877 | /** |
---|
| 878 | * DB_Error constructor |
---|
| 879 | * |
---|
| 880 | * @param mixed $code DB error code, or string with error message |
---|
| 881 | * @param int $mode what "error mode" to operate in |
---|
| 882 | * @param int $level what error level to use for $mode & |
---|
| 883 | * PEAR_ERROR_TRIGGER |
---|
| 884 | * @param mixed $debuginfo additional debug info, such as the last query |
---|
| 885 | * |
---|
| 886 | * @see PEAR_Error |
---|
| 887 | */ |
---|
| 888 | function DB_Error($code = DB_ERROR, $mode = PEAR_ERROR_RETURN, |
---|
| 889 | $level = E_USER_NOTICE, $debuginfo = null) |
---|
| 890 | { |
---|
| 891 | if (is_int($code)) { |
---|
| 892 | $this->PEAR_Error('DB Error: ' . DB::errorMessage($code), $code, |
---|
| 893 | $mode, $level, $debuginfo); |
---|
| 894 | } else { |
---|
| 895 | $this->PEAR_Error("DB Error: $code", DB_ERROR, |
---|
| 896 | $mode, $level, $debuginfo); |
---|
| 897 | } |
---|
| 898 | } |
---|
| 899 | |
---|
| 900 | // }}} |
---|
| 901 | } |
---|
| 902 | |
---|
| 903 | // }}} |
---|
| 904 | // {{{ class DB_result |
---|
| 905 | |
---|
| 906 | /** |
---|
| 907 | * This class implements a wrapper for a DB result set |
---|
| 908 | * |
---|
| 909 | * A new instance of this class will be returned by the DB implementation |
---|
| 910 | * after processing a query that returns data. |
---|
| 911 | * |
---|
| 912 | * @category Database |
---|
| 913 | * @package DB |
---|
| 914 | * @author Stig Bakken <ssb@php.net> |
---|
| 915 | * @copyright 1997-2005 The PHP Group |
---|
| 916 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
---|
| 917 | * @version Release: @package_version@ |
---|
| 918 | * @link http://pear.php.net/package/DB |
---|
| 919 | */ |
---|
| 920 | class DB_result |
---|
| 921 | { |
---|
| 922 | // {{{ properties |
---|
| 923 | |
---|
| 924 | /** |
---|
| 925 | * Should results be freed automatically when there are no more rows? |
---|
| 926 | * @var boolean |
---|
| 927 | * @see DB_common::$options |
---|
| 928 | */ |
---|
| 929 | var $autofree; |
---|
| 930 | |
---|
| 931 | /** |
---|
| 932 | * A reference to the DB_<driver> object |
---|
| 933 | * @var object |
---|
| 934 | */ |
---|
| 935 | var $dbh; |
---|
| 936 | |
---|
| 937 | /** |
---|
| 938 | * The current default fetch mode |
---|
| 939 | * @var integer |
---|
| 940 | * @see DB_common::$fetchmode |
---|
| 941 | */ |
---|
| 942 | var $fetchmode; |
---|
| 943 | |
---|
| 944 | /** |
---|
| 945 | * The name of the class into which results should be fetched when |
---|
| 946 | * DB_FETCHMODE_OBJECT is in effect |
---|
| 947 | * |
---|
| 948 | * @var string |
---|
| 949 | * @see DB_common::$fetchmode_object_class |
---|
| 950 | */ |
---|
| 951 | var $fetchmode_object_class; |
---|
| 952 | |
---|
| 953 | /** |
---|
| 954 | * The number of rows to fetch from a limit query |
---|
| 955 | * @var integer |
---|
| 956 | */ |
---|
| 957 | var $limit_count = null; |
---|
| 958 | |
---|
| 959 | /** |
---|
| 960 | * The row to start fetching from in limit queries |
---|
| 961 | * @var integer |
---|
| 962 | */ |
---|
| 963 | var $limit_from = null; |
---|
| 964 | |
---|
| 965 | /** |
---|
| 966 | * The execute parameters that created this result |
---|
| 967 | * @var array |
---|
| 968 | * @since Property available since Release 1.7.0 |
---|
| 969 | */ |
---|
| 970 | var $parameters; |
---|
| 971 | |
---|
| 972 | /** |
---|
| 973 | * The query string that created this result |
---|
| 974 | * |
---|
| 975 | * Copied here incase it changes in $dbh, which is referenced |
---|
| 976 | * |
---|
| 977 | * @var string |
---|
| 978 | * @since Property available since Release 1.7.0 |
---|
| 979 | */ |
---|
| 980 | var $query; |
---|
| 981 | |
---|
| 982 | /** |
---|
| 983 | * The query result resource id created by PHP |
---|
| 984 | * @var resource |
---|
| 985 | */ |
---|
| 986 | var $result; |
---|
| 987 | |
---|
| 988 | /** |
---|
| 989 | * The present row being dealt with |
---|
| 990 | * @var integer |
---|
| 991 | */ |
---|
| 992 | var $row_counter = null; |
---|
| 993 | |
---|
| 994 | /** |
---|
| 995 | * The prepared statement resource id created by PHP in $dbh |
---|
| 996 | * |
---|
| 997 | * This resource is only available when the result set was created using |
---|
| 998 | * a driver's native execute() method, not PEAR DB's emulated one. |
---|
| 999 | * |
---|
| 1000 | * Copied here incase it changes in $dbh, which is referenced |
---|
| 1001 | * |
---|
| 1002 | * {@internal Mainly here because the InterBase/Firebird API is only |
---|
| 1003 | * able to retrieve data from result sets if the statemnt handle is |
---|
| 1004 | * still in scope.}} |
---|
| 1005 | * |
---|
| 1006 | * @var resource |
---|
| 1007 | * @since Property available since Release 1.7.0 |
---|
| 1008 | */ |
---|
| 1009 | var $statement; |
---|
| 1010 | |
---|
| 1011 | |
---|
| 1012 | // }}} |
---|
| 1013 | // {{{ constructor |
---|
| 1014 | |
---|
| 1015 | /** |
---|
| 1016 | * This constructor sets the object's properties |
---|
| 1017 | * |
---|
| 1018 | * @param object &$dbh the DB object reference |
---|
| 1019 | * @param resource $result the result resource id |
---|
| 1020 | * @param array $options an associative array with result options |
---|
| 1021 | * |
---|
| 1022 | * @return void |
---|
| 1023 | */ |
---|
| 1024 | function DB_result(&$dbh, $result, $options = array()) |
---|
| 1025 | { |
---|
| 1026 | $this->autofree = $dbh->options['autofree']; |
---|
| 1027 | $this->dbh = &$dbh; |
---|
| 1028 | $this->fetchmode = $dbh->fetchmode; |
---|
| 1029 | $this->fetchmode_object_class = $dbh->fetchmode_object_class; |
---|
| 1030 | $this->parameters = $dbh->last_parameters; |
---|
| 1031 | $this->query = $dbh->last_query; |
---|
| 1032 | $this->result = $result; |
---|
| 1033 | $this->statement = empty($dbh->last_stmt) ? null : $dbh->last_stmt; |
---|
| 1034 | foreach ($options as $key => $value) { |
---|
| 1035 | $this->setOption($key, $value); |
---|
| 1036 | } |
---|
| 1037 | } |
---|
| 1038 | |
---|
| 1039 | /** |
---|
| 1040 | * Set options for the DB_result object |
---|
| 1041 | * |
---|
| 1042 | * @param string $key the option to set |
---|
| 1043 | * @param mixed $value the value to set the option to |
---|
| 1044 | * |
---|
| 1045 | * @return void |
---|
| 1046 | */ |
---|
| 1047 | function setOption($key, $value = null) |
---|
| 1048 | { |
---|
| 1049 | switch ($key) { |
---|
| 1050 | case 'limit_from': |
---|
| 1051 | $this->limit_from = $value; |
---|
| 1052 | break; |
---|
| 1053 | case 'limit_count': |
---|
| 1054 | $this->limit_count = $value; |
---|
| 1055 | } |
---|
| 1056 | } |
---|
| 1057 | |
---|
| 1058 | // }}} |
---|
| 1059 | // {{{ fetchRow() |
---|
| 1060 | |
---|
| 1061 | /** |
---|
| 1062 | * Fetch a row of data and return it by reference into an array |
---|
| 1063 | * |
---|
| 1064 | * The type of array returned can be controlled either by setting this |
---|
| 1065 | * method's <var>$fetchmode</var> parameter or by changing the default |
---|
| 1066 | * fetch mode setFetchMode() before calling this method. |
---|
| 1067 | * |
---|
| 1068 | * There are two options for standardizing the information returned |
---|
| 1069 | * from databases, ensuring their values are consistent when changing |
---|
| 1070 | * DBMS's. These portability options can be turned on when creating a |
---|
| 1071 | * new DB object or by using setOption(). |
---|
| 1072 | * |
---|
| 1073 | * + <var>DB_PORTABILITY_LOWERCASE</var> |
---|
| 1074 | * convert names of fields to lower case |
---|
| 1075 | * |
---|
| 1076 | * + <var>DB_PORTABILITY_RTRIM</var> |
---|
| 1077 | * right trim the data |
---|
| 1078 | * |
---|
| 1079 | * @param int $fetchmode the constant indicating how to format the data |
---|
| 1080 | * @param int $rownum the row number to fetch (index starts at 0) |
---|
| 1081 | * |
---|
| 1082 | * @return mixed an array or object containing the row's data, |
---|
| 1083 | * NULL when the end of the result set is reached |
---|
| 1084 | * or a DB_Error object on failure. |
---|
| 1085 | * |
---|
| 1086 | * @see DB_common::setOption(), DB_common::setFetchMode() |
---|
| 1087 | */ |
---|
| 1088 | function &fetchRow($fetchmode = DB_FETCHMODE_DEFAULT, $rownum = null) |
---|
| 1089 | { |
---|
| 1090 | if ($fetchmode === DB_FETCHMODE_DEFAULT) { |
---|
| 1091 | $fetchmode = $this->fetchmode; |
---|
| 1092 | } |
---|
| 1093 | if ($fetchmode === DB_FETCHMODE_OBJECT) { |
---|
| 1094 | $fetchmode = DB_FETCHMODE_ASSOC; |
---|
| 1095 | $object_class = $this->fetchmode_object_class; |
---|
| 1096 | } |
---|
| 1097 | if ($this->limit_from !== null) { |
---|
| 1098 | if ($this->row_counter === null) { |
---|
| 1099 | $this->row_counter = $this->limit_from; |
---|
| 1100 | // Skip rows |
---|
| 1101 | if ($this->dbh->features['limit'] === false) { |
---|
| 1102 | $i = 0; |
---|
| 1103 | while ($i++ < $this->limit_from) { |
---|
| 1104 | $this->dbh->fetchInto($this->result, $arr, $fetchmode); |
---|
| 1105 | } |
---|
| 1106 | } |
---|
| 1107 | } |
---|
| 1108 | if ($this->row_counter >= ($this->limit_from + $this->limit_count)) |
---|
| 1109 | { |
---|
| 1110 | if ($this->autofree) { |
---|
| 1111 | $this->free(); |
---|
| 1112 | } |
---|
| 1113 | $tmp = null; |
---|
| 1114 | return $tmp; |
---|
| 1115 | } |
---|
| 1116 | if ($this->dbh->features['limit'] === 'emulate') { |
---|
| 1117 | $rownum = $this->row_counter; |
---|
| 1118 | } |
---|
| 1119 | $this->row_counter++; |
---|
| 1120 | } |
---|
| 1121 | $res = $this->dbh->fetchInto($this->result, $arr, $fetchmode, $rownum); |
---|
| 1122 | if ($res === DB_OK) { |
---|
| 1123 | if (isset($object_class)) { |
---|
| 1124 | // The default mode is specified in the |
---|
| 1125 | // DB_common::fetchmode_object_class property |
---|
| 1126 | if ($object_class == 'stdClass') { |
---|
| 1127 | $arr = (object) $arr; |
---|
| 1128 | } else { |
---|
| 1129 | $arr = &new $object_class($arr); |
---|
| 1130 | } |
---|
| 1131 | } |
---|
| 1132 | return $arr; |
---|
| 1133 | } |
---|
| 1134 | if ($res == null && $this->autofree) { |
---|
| 1135 | $this->free(); |
---|
| 1136 | } |
---|
| 1137 | return $res; |
---|
| 1138 | } |
---|
| 1139 | |
---|
| 1140 | // }}} |
---|
| 1141 | // {{{ fetchInto() |
---|
| 1142 | |
---|
| 1143 | /** |
---|
| 1144 | * Fetch a row of data into an array which is passed by reference |
---|
| 1145 | * |
---|
| 1146 | * The type of array returned can be controlled either by setting this |
---|
| 1147 | * method's <var>$fetchmode</var> parameter or by changing the default |
---|
| 1148 | * fetch mode setFetchMode() before calling this method. |
---|
| 1149 | * |
---|
| 1150 | * There are two options for standardizing the information returned |
---|
| 1151 | * from databases, ensuring their values are consistent when changing |
---|
| 1152 | * DBMS's. These portability options can be turned on when creating a |
---|
| 1153 | * new DB object or by using setOption(). |
---|
| 1154 | * |
---|
| 1155 | * + <var>DB_PORTABILITY_LOWERCASE</var> |
---|
| 1156 | * convert names of fields to lower case |
---|
| 1157 | * |
---|
| 1158 | * + <var>DB_PORTABILITY_RTRIM</var> |
---|
| 1159 | * right trim the data |
---|
| 1160 | * |
---|
| 1161 | * @param array &$arr the variable where the data should be placed |
---|
| 1162 | * @param int $fetchmode the constant indicating how to format the data |
---|
| 1163 | * @param int $rownum the row number to fetch (index starts at 0) |
---|
| 1164 | * |
---|
| 1165 | * @return mixed DB_OK if a row is processed, NULL when the end of the |
---|
| 1166 | * result set is reached or a DB_Error object on failure |
---|
| 1167 | * |
---|
| 1168 | * @see DB_common::setOption(), DB_common::setFetchMode() |
---|
| 1169 | */ |
---|
| 1170 | function fetchInto(&$arr, $fetchmode = DB_FETCHMODE_DEFAULT, $rownum = null) |
---|
| 1171 | { |
---|
| 1172 | if ($fetchmode === DB_FETCHMODE_DEFAULT) { |
---|
| 1173 | $fetchmode = $this->fetchmode; |
---|
| 1174 | } |
---|
| 1175 | if ($fetchmode === DB_FETCHMODE_OBJECT) { |
---|
| 1176 | $fetchmode = DB_FETCHMODE_ASSOC; |
---|
| 1177 | $object_class = $this->fetchmode_object_class; |
---|
| 1178 | } |
---|
| 1179 | if ($this->limit_from !== null) { |
---|
| 1180 | if ($this->row_counter === null) { |
---|
| 1181 | $this->row_counter = $this->limit_from; |
---|
| 1182 | // Skip rows |
---|
| 1183 | if ($this->dbh->features['limit'] === false) { |
---|
| 1184 | $i = 0; |
---|
| 1185 | while ($i++ < $this->limit_from) { |
---|
| 1186 | $this->dbh->fetchInto($this->result, $arr, $fetchmode); |
---|
| 1187 | } |
---|
| 1188 | } |
---|
| 1189 | } |
---|
| 1190 | if ($this->row_counter >= ( |
---|
| 1191 | $this->limit_from + $this->limit_count)) |
---|
| 1192 | { |
---|
| 1193 | if ($this->autofree) { |
---|
| 1194 | $this->free(); |
---|
| 1195 | } |
---|
| 1196 | return null; |
---|
| 1197 | } |
---|
| 1198 | if ($this->dbh->features['limit'] === 'emulate') { |
---|
| 1199 | $rownum = $this->row_counter; |
---|
| 1200 | } |
---|
| 1201 | |
---|
| 1202 | $this->row_counter++; |
---|
| 1203 | } |
---|
| 1204 | $res = $this->dbh->fetchInto($this->result, $arr, $fetchmode, $rownum); |
---|
| 1205 | if ($res === DB_OK) { |
---|
| 1206 | if (isset($object_class)) { |
---|
| 1207 | // default mode specified in the |
---|
| 1208 | // DB_common::fetchmode_object_class property |
---|
| 1209 | if ($object_class == 'stdClass') { |
---|
| 1210 | $arr = (object) $arr; |
---|
| 1211 | } else { |
---|
| 1212 | $arr = new $object_class($arr); |
---|
| 1213 | } |
---|
| 1214 | } |
---|
| 1215 | return DB_OK; |
---|
| 1216 | } |
---|
| 1217 | if ($res == null && $this->autofree) { |
---|
| 1218 | $this->free(); |
---|
| 1219 | } |
---|
| 1220 | return $res; |
---|
| 1221 | } |
---|
| 1222 | |
---|
| 1223 | // }}} |
---|
| 1224 | // {{{ numCols() |
---|
| 1225 | |
---|
| 1226 | /** |
---|
| 1227 | * Get the the number of columns in a result set |
---|
| 1228 | * |
---|
| 1229 | * @return int the number of columns. A DB_Error object on failure. |
---|
| 1230 | */ |
---|
| 1231 | function numCols() |
---|
| 1232 | { |
---|
| 1233 | return $this->dbh->numCols($this->result); |
---|
| 1234 | } |
---|
| 1235 | |
---|
| 1236 | // }}} |
---|
| 1237 | // {{{ numRows() |
---|
| 1238 | |
---|
| 1239 | /** |
---|
| 1240 | * Get the number of rows in a result set |
---|
| 1241 | * |
---|
| 1242 | * @return int the number of rows. A DB_Error object on failure. |
---|
| 1243 | */ |
---|
| 1244 | function numRows() |
---|
| 1245 | { |
---|
| 1246 | if ($this->dbh->features['numrows'] === 'emulate' |
---|
| 1247 | && $this->dbh->options['portability'] & DB_PORTABILITY_NUMROWS) |
---|
| 1248 | { |
---|
| 1249 | if ($this->dbh->features['prepare']) { |
---|
| 1250 | $res = $this->dbh->query($this->query, $this->parameters); |
---|
| 1251 | } else { |
---|
| 1252 | $res = $this->dbh->query($this->query); |
---|
| 1253 | } |
---|
| 1254 | if (DB::isError($res)) { |
---|
| 1255 | return $res; |
---|
| 1256 | } |
---|
| 1257 | $i = 0; |
---|
| 1258 | while ($res->fetchInto($tmp, DB_FETCHMODE_ORDERED)) { |
---|
| 1259 | $i++; |
---|
| 1260 | } |
---|
| 1261 | return $i; |
---|
| 1262 | } else { |
---|
| 1263 | return $this->dbh->numRows($this->result); |
---|
| 1264 | } |
---|
| 1265 | } |
---|
| 1266 | |
---|
| 1267 | // }}} |
---|
| 1268 | // {{{ nextResult() |
---|
| 1269 | |
---|
| 1270 | /** |
---|
| 1271 | * Get the next result if a batch of queries was executed |
---|
| 1272 | * |
---|
| 1273 | * @return bool true if a new result is available or false if not |
---|
| 1274 | */ |
---|
| 1275 | function nextResult() |
---|
| 1276 | { |
---|
| 1277 | return $this->dbh->nextResult($this->result); |
---|
| 1278 | } |
---|
| 1279 | |
---|
| 1280 | // }}} |
---|
| 1281 | // {{{ free() |
---|
| 1282 | |
---|
| 1283 | /** |
---|
| 1284 | * Frees the resources allocated for this result set |
---|
| 1285 | * |
---|
| 1286 | * @return bool true on success. A DB_Error object on failure. |
---|
| 1287 | */ |
---|
| 1288 | function free() |
---|
| 1289 | { |
---|
| 1290 | $err = $this->dbh->freeResult($this->result); |
---|
| 1291 | if (DB::isError($err)) { |
---|
| 1292 | return $err; |
---|
| 1293 | } |
---|
| 1294 | $this->result = false; |
---|
| 1295 | $this->statement = false; |
---|
| 1296 | return true; |
---|
| 1297 | } |
---|
| 1298 | |
---|
| 1299 | // }}} |
---|
| 1300 | // {{{ tableInfo() |
---|
| 1301 | |
---|
| 1302 | /** |
---|
| 1303 | * @see DB_common::tableInfo() |
---|
| 1304 | * @deprecated Method deprecated some time before Release 1.2 |
---|
| 1305 | */ |
---|
| 1306 | function tableInfo($mode = null) |
---|
| 1307 | { |
---|
| 1308 | if (is_string($mode)) { |
---|
| 1309 | return $this->dbh->raiseError(DB_ERROR_NEED_MORE_DATA); |
---|
| 1310 | } |
---|
| 1311 | return $this->dbh->tableInfo($this, $mode); |
---|
| 1312 | } |
---|
| 1313 | |
---|
| 1314 | // }}} |
---|
| 1315 | // {{{ getQuery() |
---|
| 1316 | |
---|
| 1317 | /** |
---|
| 1318 | * Determine the query string that created this result |
---|
| 1319 | * |
---|
| 1320 | * @return string the query string |
---|
| 1321 | * |
---|
| 1322 | * @since Method available since Release 1.7.0 |
---|
| 1323 | */ |
---|
| 1324 | function getQuery() |
---|
| 1325 | { |
---|
| 1326 | return $this->query; |
---|
| 1327 | } |
---|
| 1328 | |
---|
| 1329 | // }}} |
---|
| 1330 | // {{{ getRowCounter() |
---|
| 1331 | |
---|
| 1332 | /** |
---|
| 1333 | * Tells which row number is currently being processed |
---|
| 1334 | * |
---|
| 1335 | * @return integer the current row being looked at. Starts at 1. |
---|
| 1336 | */ |
---|
| 1337 | function getRowCounter() |
---|
| 1338 | { |
---|
| 1339 | return $this->row_counter; |
---|
| 1340 | } |
---|
| 1341 | |
---|
| 1342 | // }}} |
---|
| 1343 | } |
---|
| 1344 | |
---|
| 1345 | // }}} |
---|
| 1346 | // {{{ class DB_row |
---|
| 1347 | |
---|
| 1348 | /** |
---|
| 1349 | * PEAR DB Row Object |
---|
| 1350 | * |
---|
| 1351 | * The object contains a row of data from a result set. Each column's data |
---|
| 1352 | * is placed in a property named for the column. |
---|
| 1353 | * |
---|
| 1354 | * @category Database |
---|
| 1355 | * @package DB |
---|
| 1356 | * @author Stig Bakken <ssb@php.net> |
---|
| 1357 | * @copyright 1997-2005 The PHP Group |
---|
| 1358 | * @license http://www.php.net/license/3_0.txt PHP License 3.0 |
---|
| 1359 | * @version Release: @package_version@ |
---|
| 1360 | * @link http://pear.php.net/package/DB |
---|
| 1361 | * @see DB_common::setFetchMode() |
---|
| 1362 | */ |
---|
| 1363 | class DB_row |
---|
| 1364 | { |
---|
| 1365 | // {{{ constructor |
---|
| 1366 | |
---|
| 1367 | /** |
---|
| 1368 | * The constructor places a row's data into properties of this object |
---|
| 1369 | * |
---|
| 1370 | * @param array the array containing the row's data |
---|
| 1371 | * |
---|
| 1372 | * @return void |
---|
| 1373 | */ |
---|
| 1374 | function DB_row(&$arr) |
---|
| 1375 | { |
---|
| 1376 | foreach ($arr as $key => $value) { |
---|
| 1377 | $this->$key = &$arr[$key]; |
---|
| 1378 | } |
---|
| 1379 | } |
---|
| 1380 | |
---|
| 1381 | // }}} |
---|
| 1382 | } |
---|
| 1383 | |
---|
| 1384 | // }}} |
---|
| 1385 | |
---|
| 1386 | /* |
---|
| 1387 | * Local variables: |
---|
| 1388 | * tab-width: 4 |
---|
| 1389 | * c-basic-offset: 4 |
---|
| 1390 | * End: |
---|
| 1391 | */ |
---|
| 1392 | |
---|
| 1393 | ?> |
---|