source: branches/comu/data/module/DB.php @ 2

Revision 2, 38.3 KB checked in by root, 17 years ago (diff)

new import

Line 
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: DB.php 4774 2006-10-12 06:59:22Z naka $
24 * @link       http://pear.php.net/package/DB
25 */
26
27/**
28 * Obtain the PEAR class so it can be extended from
29 */
30
31if(!defined('DB_PHP_DIR')) {
32    $DB_PHP_DIR = realpath(dirname( __FILE__));
33    define("DB_PHP_DIR", $DB_PHP_DIR); 
34}
35
36require_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 */
52define('DB_OK', 1);
53
54/**
55 * Unkown error
56 */
57define('DB_ERROR', -1);
58
59/**
60 * Syntax error
61 */
62define('DB_ERROR_SYNTAX', -2);
63
64/**
65 * Tried to insert a duplicate value into a primary or unique index
66 */
67define('DB_ERROR_CONSTRAINT', -3);
68
69/**
70 * An identifier in the query refers to a non-existant object
71 */
72define('DB_ERROR_NOT_FOUND', -4);
73
74/**
75 * Tried to create a duplicate object
76 */
77define('DB_ERROR_ALREADY_EXISTS', -5);
78
79/**
80 * The current driver does not support the action you attempted
81 */
82define('DB_ERROR_UNSUPPORTED', -6);
83
84/**
85 * The number of parameters does not match the number of placeholders
86 */
87define('DB_ERROR_MISMATCH', -7);
88
89/**
90 * A literal submitted did not match the data type expected
91 */
92define('DB_ERROR_INVALID', -8);
93
94/**
95 * The current DBMS does not support the action you attempted
96 */
97define('DB_ERROR_NOT_CAPABLE', -9);
98
99/**
100 * A literal submitted was too long so the end of it was removed
101 */
102define('DB_ERROR_TRUNCATED', -10);
103
104/**
105 * A literal number submitted did not match the data type expected
106 */
107define('DB_ERROR_INVALID_NUMBER', -11);
108
109/**
110 * A literal date submitted did not match the data type expected
111 */
112define('DB_ERROR_INVALID_DATE', -12);
113
114/**
115 * Attempt to divide something by zero
116 */
117define('DB_ERROR_DIVZERO', -13);
118
119/**
120 * A database needs to be selected
121 */
122define('DB_ERROR_NODBSELECTED', -14);
123
124/**
125 * Could not create the object requested
126 */
127define('DB_ERROR_CANNOT_CREATE', -15);
128
129/**
130 * Could not drop the database requested because it does not exist
131 */
132define('DB_ERROR_CANNOT_DROP', -17);
133
134/**
135 * An identifier in the query refers to a non-existant table
136 */
137define('DB_ERROR_NOSUCHTABLE', -18);
138
139/**
140 * An identifier in the query refers to a non-existant column
141 */
142define('DB_ERROR_NOSUCHFIELD', -19);
143
144/**
145 * The data submitted to the method was inappropriate
146 */
147define('DB_ERROR_NEED_MORE_DATA', -20);
148
149/**
150 * The attempt to lock the table failed
151 */
152define('DB_ERROR_NOT_LOCKED', -21);
153
154/**
155 * The number of columns doesn't match the number of values
156 */
157define('DB_ERROR_VALUE_COUNT_ON_ROW', -22);
158
159/**
160 * The DSN submitted has problems
161 */
162define('DB_ERROR_INVALID_DSN', -23);
163
164/**
165 * Could not connect to the database
166 */
167define('DB_ERROR_CONNECT_FAILED', -24);
168
169/**
170 * The PHP extension needed for this DBMS could not be found
171 */
172define('DB_ERROR_EXTENSION_NOT_FOUND',-25);
173
174/**
175 * The present user has inadequate permissions to perform the task requestd
176 */
177define('DB_ERROR_ACCESS_VIOLATION', -26);
178
179/**
180 * The database requested does not exist
181 */
182define('DB_ERROR_NOSUCHDB', -27);
183
184/**
185 * Tried to insert a null value into a column that doesn't allow nulls
186 */
187define('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 */
205define('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 */
213define('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 */
220define('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 */
235define('DB_BINMODE_PASSTHRU', 1);
236
237/**
238 * Lets you return data as usual
239 */
240define('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 */
247define('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 */
264define('DB_FETCHMODE_DEFAULT', 0);
265
266/**
267 * Column data indexed by numbers, ordered from 0 and up
268 */
269define('DB_FETCHMODE_ORDERED', 1);
270
271/**
272 * Column data indexed by column names
273 */
274define('DB_FETCHMODE_ASSOC', 2);
275
276/**
277 * Column data as object properties
278 */
279define('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 */
288define('DB_FETCHMODE_FLIPPED', 4);
289/**#@-*/
290
291/**#@+
292 * Old fetch modes.  Left here for compatibility.
293 */
294define('DB_GETMODE_ORDERED', DB_FETCHMODE_ORDERED);
295define('DB_GETMODE_ASSOC',   DB_FETCHMODE_ASSOC);
296define('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 */
315define('DB_TABLEINFO_ORDER', 1);
316define('DB_TABLEINFO_ORDERTABLE', 2);
317define('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 */
325define('DB_AUTOQUERY_INSERT', 1);
326define('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 */
349define('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 */
355define('DB_PORTABILITY_LOWERCASE', 1);
356
357/**
358 * Right trim the data output by get*() and fetch*()
359 */
360define('DB_PORTABILITY_RTRIM', 2);
361
362/**
363 * Force reporting the number of rows deleted
364 */
365define('DB_PORTABILITY_DELETE_COUNT', 4);
366
367/**
368 * Enable hack that makes numRows() work in Oracle
369 */
370define('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 */
383define('DB_PORTABILITY_ERRORS', 16);
384
385/**
386 * Convert null values to empty strings in data output by
387 * get*() and fetch*()
388 */
389define('DB_PORTABILITY_NULL_TO_EMPTY', 32);
390
391/**
392 * Turn on all portability features
393 */
394define('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 */
437class 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&param2=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 */
873class 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 */
920class 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 */
1363class 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?>
Note: See TracBrowser for help on using the repository browser.