extlib/DB/dbase.php

   1 <?php
   2
   3 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   4
   5 /**
   6  * The PEAR DB driver for PHP's dbase extension
   7  * for interacting with dBase databases
   8  *
   9  * PHP version 5
  10  *
  11  * LICENSE: This source file is subject to version 3.0 of the PHP license
  12  * that is available through the world-wide-web at the following URI:
  13  * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
  14  * the PHP License and are unable to obtain it through the web, please
  15  * send a note to license@php.net so we can mail you a copy immediately.
  16  *
  17  * @category   Database
  18  * @package    DB
  19  * @author     Tomas V.V. Cox <cox@idecnet.com>
  20  * @author     Daniel Convissor <danielc@php.net>
  21  * @copyright  1997-2007 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 DB_common class so it can be extended from
  29  */
  30 //require_once 'DB/common.php';
  31 require_once 'common.php';
  32
  33 /**
  34  * The methods PEAR DB uses to interact with PHP's dbase extension
  35  * for interacting with dBase databases
  36  *
  37  * These methods overload the ones declared in DB_common.
  38  *
  39  * @category   Database
  40  * @package    DB
  41  * @author     Tomas V.V. Cox <cox@idecnet.com>
  42  * @author     Daniel Convissor <danielc@php.net>
  43  * @copyright  1997-2007 The PHP Group
  44  * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  45  * @version    Release: 1.9.2
  46  * @link       http://pear.php.net/package/DB
  47  */
  48 class DB_dbase extends DB_common
  49 {
  50     // {{{ properties
  51
  52     /**
  53      * The DB driver type (mysql, oci8, odbc, etc.)
  54      * @var string
  55      */
  56     public $phptype = 'dbase';
  57
  58     /**
  59      * The database syntax variant to be used (db2, access, etc.), if any
  60      * @var string
  61      */
  62     public $dbsyntax = 'dbase';
  63
  64     /**
  65      * The capabilities of this DB implementation
  66      *
  67      * The 'new_link' element contains the PHP version that first provided
  68      * new_link support for this DBMS.  Contains false if it's unsupported.
  69      *
  70      * Meaning of the 'limit' element:
  71      *   + 'emulate' = emulate with fetch row by number
  72      *   + 'alter'   = alter the query
  73      *   + false     = skip rows
  74      *
  75      * @var array
  76      */
  77     public $features = array(
  78         'limit' => false,
  79         'new_link' => false,
  80         'numrows' => true,
  81         'pconnect' => false,
  82         'prepare' => false,
  83         'ssl' => false,
  84         'transactions' => false,
  85     );
  86
  87     /**
  88      * A mapping of native error codes to DB error codes
  89      * @var array
  90      */
  91     public $errorcode_map = array();
  92
  93     /**
  94      * The raw database connection created by PHP
  95      * @var resource
  96      */
  97     public $connection;
  98
  99     /**
 100      * The DSN information for connecting to a database
 101      * @var array
 102      */
 103     public $dsn = array();
 104
 105
 106     /**
 107      * A means of emulating result resources
 108      * @var array
 109      */
 110     public $res_row = array();
 111
 112     /**
 113      * The quantity of results so far
 114      *
 115      * For emulating result resources.
 116      *
 117      * @var integer
 118      */
 119     public $result = 0;
 120
 121     /**
 122      * Maps dbase data type id's to human readable strings
 123      *
 124      * The human readable values are based on the output of PHP's
 125      * dbase_get_header_info() function.
 126      *
 127      * @var array
 128      * @since Property available since Release 1.7.0
 129      */
 130     public $types = array(
 131         'C' => 'character',
 132         'D' => 'date',
 133         'L' => 'boolean',
 134         'M' => 'memo',
 135         'N' => 'number',
 136     );
 137
 138
 139     // }}}
 140     // {{{ constructor
 141
 142     /**
 143      * This constructor calls <kbd>parent::__construct()</kbd>
 144      *
 145      * @return void
 146      */
 147     public function __construct()
 148     {
 149         parent::__construct();
 150     }
 151
 152     // }}}
 153     // {{{ connect()
 154
 155     /**
 156      * Connect to the database and create it if it doesn't exist
 157      *
 158      * Don't call this method directly.  Use DB::connect() instead.
 159      *
 160      * PEAR DB's dbase driver supports the following extra DSN options:
 161      *   + mode    An integer specifying the read/write mode to use
 162      *              (0 = read only, 1 = write only, 2 = read/write).
 163      *              Available since PEAR DB 1.7.0.
 164      *   + fields  An array of arrays that PHP's dbase_create() function needs
 165      *              to create a new database.  This information is used if the
 166      *              dBase file specified in the "database" segment of the DSN
 167      *              does not exist.  For more info, see the PHP manual's
 168      *              {@link http://php.net/dbase_create dbase_create()} page.
 169      *              Available since PEAR DB 1.7.0.
 170      *
 171      * Example of how to connect and establish a new dBase file if necessary:
 172      * <code>
 173      * require_once 'DB.php';
 174      *
 175      * $dsn = array(
 176      *     'phptype'  => 'dbase',
 177      *     'database' => '/path/and/name/of/dbase/file',
 178      *     'mode'     => 2,
 179      *     'fields'   => array(
 180      *         array('a', 'N', 5, 0),
 181      *         array('b', 'C', 40),
 182      *         array('c', 'C', 255),
 183      *         array('d', 'C', 20),
 184      *     ),
 185      * );
 186      * $options = array(
 187      *     'debug'       => 2,
 188      *     'portability' => DB_PORTABILITY_ALL,
 189      * );
 190      *
 191      * $db = DB::connect($dsn, $options);
 192      * if ((new PEAR)->isError($db)) {
 193      *     die($db->getMessage());
 194      * }
 195      * </code>
 196      *
 197      * @param array $dsn the data source name
 198      * @param bool $persistent should the connection be persistent?
 199      *
 200      * @return int|object
 201      */
 202     public function connect($dsn, $persistent = false)
 203     {
 204         if (!PEAR::loadExtension('dbase')) {
 205             return $this->raiseError(DB_ERROR_EXTENSION_NOT_FOUND);
 206         }
 207
 208         $this->dsn = $dsn;
 209         if ($dsn['dbsyntax']) {
 210             $this->dbsyntax = $dsn['dbsyntax'];
 211         }
 212
 213         /*
 214          * Turn track_errors on for entire script since $php_errormsg
 215          * is the only way to find errors from the dbase extension.
 216          */
 217         @ini_set('track_errors', 1);
 218         $php_errormsg = '';
 219
 220         if (!file_exists($dsn['database'])) {
 221             $this->dsn['mode'] = 2;
 222             if (empty($dsn['fields']) || !is_array($dsn['fields'])) {
 223                 return $this->raiseError(
 224                     DB_ERROR_CONNECT_FAILED,
 225                     null,
 226                     null,
 227                     null,
 228                     'the dbase file does not exist and '
 229                     . 'it could not be created because '
 230                     . 'the "fields" element of the DSN '
 231                     . 'is not properly set'
 232                 );
 233             }
 234             $this->connection = @dbase_create(
 235                 $dsn['database'],
 236                 $dsn['fields']
 237             );
 238             if (!$this->connection) {
 239                 return $this->raiseError(
 240                     DB_ERROR_CONNECT_FAILED,
 241                     null,
 242                     null,
 243                     null,
 244                     'the dbase file does not exist and '
 245                     . 'the attempt to create it failed: '
 246                     . $php_errormsg
 247                 );
 248             }
 249         } else {
 250             if (!isset($this->dsn['mode'])) {
 251                 $this->dsn['mode'] = 0;
 252             }
 253             $this->connection = @dbase_open(
 254                 $dsn['database'],
 255                 $this->dsn['mode']
 256             );
 257             if (!$this->connection) {
 258                 return $this->raiseError(
 259                     DB_ERROR_CONNECT_FAILED,
 260                     null,
 261                     null,
 262                     null,
 263                     $php_errormsg
 264                 );
 265             }
 266         }
 267         return DB_OK;
 268     }
 269
 270     // }}}
 271     // {{{ disconnect()
 272
 273     /**
 274      * Disconnects from the database server
 275      *
 276      * @return bool  TRUE on success, FALSE on failure
 277      */
 278     public function disconnect()
 279     {
 280         $ret = @dbase_close($this->connection);
 281         $this->connection = null;
 282         return $ret;
 283     }
 284
 285     // }}}
 286     // {{{ &query()
 287
 288     public function &query($query = null)
 289     {
 290         // emulate result resources
 291         $this->res_row[(int)$this->result] = 0;
 292         $tmp = new DB_result($this, $this->result++);
 293         return $tmp;
 294     }
 295
 296     // }}}
 297     // {{{ fetchInto()
 298
 299     /**
 300      * Places a row from the result set into the given array
 301      *
 302      * Formating of the array and the data therein are configurable.
 303      * See DB_result::fetchInto() for more information.
 304      *
 305      * This method is not meant to be called directly.  Use
 306      * DB_result::fetchInto() instead.  It can't be declared "protected"
 307      * because DB_result is a separate object.
 308      *
 309      * @param resource $result the query result resource
 310      * @param array $arr the referenced array to put the data in
 311      * @param int $fetchmode how the resulting array should be indexed
 312      * @param int $rownum the row number to fetch (0 = first row)
 313      *
 314      * @return mixed  DB_OK on success, NULL when the end of a result set is
 315      *                 reached or on failure
 316      *
 317      * @see DB_result::fetchInto()
 318      */
 319     public function fetchInto($result, &$arr, $fetchmode, $rownum = null)
 320     {
 321         if ($rownum === null) {
 322             $rownum = $this->res_row[(int)$result]++;
 323         }
 324         if ($fetchmode & DB_FETCHMODE_ASSOC) {
 325             $arr = @dbase_get_record_with_names($this->connection, $rownum);
 326             if ($this->options['portability'] & DB_PORTABILITY_LOWERCASE && $arr) {
 327                 $arr = array_change_key_case($arr, CASE_LOWER);
 328             }
 329         } else {
 330             $arr = @dbase_get_record($this->connection, $rownum);
 331         }
 332         if (!$arr) {
 333             return null;
 334         }
 335         if ($this->options['portability'] & DB_PORTABILITY_RTRIM) {
 336             $this->_rtrimArrayValues($arr);
 337         }
 338         if ($this->options['portability'] & DB_PORTABILITY_NULL_TO_EMPTY) {
 339             $this->_convertNullArrayValuesToEmpty($arr);
 340         }
 341         return DB_OK;
 342     }
 343
 344     // }}}
 345     // {{{ freeResult()
 346
 347     /**
 348      * Deletes the result set and frees the memory occupied by the result set.
 349      *
 350      * This method is a no-op for dbase, as there aren't result resources in
 351      * the same sense as most other database backends.
 352      *
 353      * @param resource $result PHP's query result resource
 354      *
 355      * @return bool  TRUE on success, FALSE if $result is invalid
 356      *
 357      * @see DB_result::free()
 358      */
 359     public function freeResult($result)
 360     {
 361         return true;
 362     }
 363
 364     // }}}
 365     // {{{ numCols()
 366
 367     /**
 368      * Gets the number of columns in a result set
 369      *
 370      * This method is not meant to be called directly.  Use
 371      * DB_result::numCols() instead.  It can't be declared "protected"
 372      * because DB_result is a separate object.
 373      *
 374      * @param $foo
 375      * @return int  the number of columns.  A DB_Error object on failure.
 376      *
 377      * @see DB_result::numCols()
 378      */
 379     public function numCols($foo)
 380     {
 381         return @dbase_numfields($this->connection);
 382     }
 383
 384     // }}}
 385     // {{{ numRows()
 386
 387     /**
 388      * Gets the number of rows in a result set
 389      *
 390      * This method is not meant to be called directly.  Use
 391      * DB_result::numRows() instead.  It can't be declared "protected"
 392      * because DB_result is a separate object.
 393      *
 394      * @param $foo
 395      * @return int  the number of rows.  A DB_Error object on failure.
 396      *
 397      * @see DB_result::numRows()
 398      */
 399     public function numRows($foo)
 400     {
 401         return @dbase_numrecords($this->connection);
 402     }
 403
 404     // }}}
 405     // {{{ quoteBoolean()
 406
 407     /**
 408      * Formats a boolean value for use within a query in a locale-independent
 409      * manner.
 410      *
 411      * @param boolean the boolean value to be quoted.
 412      * @return string the quoted string.
 413      * @see DB_common::quoteSmart()
 414      * @since Method available since release 1.7.8.
 415      */
 416     public function quoteBoolean($boolean)
 417     {
 418         return $boolean ? 'T' : 'F';
 419     }
 420
 421     // }}}
 422     // {{{ tableInfo()
 423
 424     /**
 425      * Returns information about the current database
 426      *
 427      * @param mixed $result THIS IS UNUSED IN DBASE.  The current database
 428      *                       is examined regardless of what is provided here.
 429      * @param int $mode a valid tableInfo mode
 430      *
 431      * @return array|object
 432      *                 A DB_Error object on failure.
 433      *
 434      * @see DB_common::tableInfo()
 435      * @since Method available since Release 1.7.0
 436      */
 437     public function tableInfo($result = null, $mode = null)
 438     {
 439         if (function_exists('dbase_get_header_info')) {
 440             $id = @dbase_get_header_info($this->connection);
 441             if (!$id && $php_errormsg) {
 442                 return $this->raiseError(
 443                     DB_ERROR,
 444                     null,
 445                     null,
 446                     null,
 447                     $php_errormsg
 448                 );
 449             }
 450         } else {
 451             /*
 452              * This segment for PHP 4 is loosely based on code by
 453              * Hadi Rusiah <deegos@yahoo.com> in the comments on
 454              * the dBase reference page in the PHP manual.
 455              */
 456             $db = @fopen($this->dsn['database'], 'r');
 457             if (!$db) {
 458                 return $this->raiseError(
 459                     DB_ERROR_CONNECT_FAILED,
 460                     null,
 461                     null,
 462                     null,
 463                     $php_errormsg
 464                 );
 465             }
 466
 467             $id = array();
 468             $i = 0;
 469
 470             $line = fread($db, 32);
 471             while (!feof($db)) {
 472                 $line = fread($db, 32);
 473                 if (substr($line, 0, 1) == chr(13)) {
 474                     break;
 475                 } else {
 476                     $pos = strpos(substr($line, 0, 10), chr(0));
 477                     $pos = ($pos == 0 ? 10 : $pos);
 478                     $id[$i] = array(
 479                         'name' => substr($line, 0, $pos),
 480                         'type' => $this->types[substr($line, 11, 1)],
 481                         'length' => ord(substr($line, 16, 1)),
 482                         'precision' => ord(substr($line, 17, 1)),
 483                     );
 484                 }
 485                 $i++;
 486             }
 487
 488             fclose($db);
 489         }
 490
 491         if ($this->options['portability'] & DB_PORTABILITY_LOWERCASE) {
 492             $case_func = 'strtolower';
 493         } else {
 494             $case_func = 'strval';
 495         }
 496
 497         $res = array();
 498         $count = count($id);
 499
 500         if ($mode) {
 501             $res['num_fields'] = $count;
 502         }
 503
 504         for ($i = 0; $i < $count; $i++) {
 505             $res[$i] = array(
 506                 'table' => $this->dsn['database'],
 507                 'name' => $case_func($id[$i]['name']),
 508                 'type' => $id[$i]['type'],
 509                 'len' => $id[$i]['length'],
 510                 'flags' => ''
 511             );
 512             if ($mode & DB_TABLEINFO_ORDER) {
 513                 $res['order'][$res[$i]['name']] = $i;
 514             }
 515             if ($mode & DB_TABLEINFO_ORDERTABLE) {
 516                 $res['ordertable'][$res[$i]['table']][$res[$i]['name']] = $i;
 517             }
 518         }
 519
 520         return $res;
 521     }
 522
 523     // }}}
 524 }
 525
 526 /*
 527  * Local variables:
 528  * tab-width: 4
 529  * c-basic-offset: 4
 530  * End:
 531  */