[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: ResultSetCommon.php,v 1.9 2006/01/17 19:44:38 hlellelid Exp $
   4   *
   5   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   6   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   7   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   8   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   9   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  10   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  11   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  12   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  13   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  14   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  15   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  16   *
  17   * This software consists of voluntary contributions made by many individuals
  18   * and is licensed under the LGPL. For more information please see
  19   * <http://creole.phpdb.org>.
  20   */
  21  
  22  /**
  23   * This class implements many shared or common methods needed by resultset drivers.
  24   * 
  25   * This class may (optionally) be extended by driver classes simply to make it easier
  26   * to create driver classes.  This is also useful in the early stages of Creole development
  27   * as it means that API changes affect fewer files. As Creole matures/stabalizes having
  28   * a common class may become less useful, as drivers may have their own ways of doing things
  29   * (and we'll have a solid unit test framework to make sure drivers conform to the API
  30   * described by the interfaces).
  31   * 
  32   * The get*() methods in this class will format values before returning them. Note
  33   * that if they will return <code>null</code> if the database returned <code>NULL</code>
  34   * which makes these functions easier to use than simply typecasting the values from the
  35   * db. If the requested column does not exist than an exception (SQLException) will be thrown.
  36   * 
  37   * <code>
  38   * $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
  39   * $rs->next();
  40   * 
  41   * $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
  42   * // $max_stamp will be date string or null if no MAX(stamp) was found
  43   * 
  44   * $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
  45   * // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
  46   * // SQLException: Invalid resultset column: max(stamp)
  47   * </code>
  48   * 
  49   * @author    Hans Lellelid <hans@xmpl.org>
  50   * @version   $Revision: 1.9 $
  51   * @package   creole.common
  52   */
  53  abstract class ResultSetCommon {          
  54      
  55      /**
  56       * The fetchmode for this recordset.
  57       * @var int
  58       */
  59      protected $fetchmode;
  60      
  61      /**
  62       * DB connection.
  63       * @var Connection
  64       */
  65      protected $conn;
  66      
  67      /**
  68       * Resource identifier used for native result set handling.
  69       * @var resource
  70       */
  71      protected $result;
  72  
  73      /**
  74       * The current cursor position (row number). First row is 1. Before first row is 0.
  75       * @var int
  76       */
  77      protected $cursorPos = 0;
  78      
  79      /**
  80       * The current unprocessed record/row from the db.
  81       * @var array
  82       */
  83      protected $fields;
  84      
  85      /**
  86       * Whether to convert assoc col case.
  87       * @var boolean
  88       */
  89      protected $lowerAssocCase = false;
  90      
  91      /**
  92       * Whether to apply rtrim() to strings.
  93       * @var boolean
  94       */
  95      protected $rtrimString = false;
  96      
  97      /**
  98       * Constructor.
  99       */
 100      public function __construct(Connection $conn, $result, $fetchmode = null)
 101      {
 102          $this->conn = $conn;
 103          $this->result = $result;             
 104          if ($fetchmode !== null) {
 105              $this->fetchmode = $fetchmode;
 106          } else {
 107              $this->fetchmode = ResultSet::FETCHMODE_ASSOC; // default
 108          }
 109          $this->lowerAssocCase = (($conn->getFlags() & Creole::COMPAT_ASSOC_LOWER) === Creole::COMPAT_ASSOC_LOWER);
 110          $this->rtrimString = (($conn->getFlags() & Creole::COMPAT_RTRIM_STRING) === Creole::COMPAT_RTRIM_STRING);
 111      }
 112      
 113      /**
 114       * Destructor
 115       *
 116       * Free db result resource.
 117       */
 118      public function __destruct()
 119      {
 120            $this->close();
 121      }
 122      
 123      /**
 124       * @see ResultSet::getIterator()
 125       */
 126      public function getIterator()
 127      {
 128          require_once 'creole/ResultSetIterator.php';
 129          return new ResultSetIterator($this);
 130      }
 131      
 132      /**
 133       * @see ResultSet::getResource()
 134       */
 135      public function getResource()
 136      {
 137          return $this->result;
 138      }
 139      
 140      /**
 141       * @see ResultSet::isLowereAssocCase()
 142       */
 143      public function isLowerAssocCase()
 144      {
 145          return $this->lowerAssocCase;
 146      }        
 147      
 148      /**
 149       * @see ResultSet::setFetchmode()
 150       */
 151      public function setFetchmode($mode)
 152      {
 153          $this->fetchmode = $mode;
 154      }
 155      
 156      /**
 157       * @see ResultSet::getFetchmode()
 158       */
 159      public function getFetchmode()
 160      {
 161          return $this->fetchmode;
 162      }                
 163  
 164      /**
 165       * @see ResultSet::previous()
 166       */
 167      public function previous()
 168      {
 169          // Go back 2 spaces so that we can then advance 1 space.
 170          $ok = $this->seek($this->cursorPos - 2);
 171          if ($ok === false) {
 172              $this->beforeFirst();
 173              return false;
 174          }        
 175          return $this->next();      
 176      }
 177  
 178      /**
 179       * @see ResultSet::isBeforeFirst()
 180       */
 181      public function relative($offset)
 182      {
 183          // which absolute row number are we seeking
 184          $pos = $this->cursorPos + ($offset - 1);
 185          $ok = $this->seek($pos);
 186                  
 187          if ($ok === false) {
 188              if ($pos < 0) {
 189                  $this->beforeFirst();
 190              } else {
 191                  $this->afterLast();
 192              }
 193          } else {
 194              $ok = $this->next();
 195          }
 196          
 197          return $ok;
 198      }
 199  
 200      /**
 201       * @see ResultSet::absolute()
 202       */
 203      public function absolute($pos)
 204      {
 205          $ok = $this->seek( $pos - 1 ); // compensate for next() factor        
 206          if ($ok === false) {
 207              if ($pos - 1 < 0) {
 208                  $this->beforeFirst();
 209              } else {
 210                  $this->afterLast();
 211              }
 212          } else {
 213              $ok = $this->next();
 214          }        
 215          return $ok;
 216      }
 217      
 218      /**
 219       * @see ResultSet::first()
 220       */
 221      public function first()
 222      {
 223          if($this->cursorPos !== 0) { $this->seek(0); }
 224          return $this->next();
 225      }
 226  
 227      /**
 228       * @see ResultSet::last()
 229       */
 230      public function last()
 231      {
 232          if($this->cursorPos !==  ($last = $this->getRecordCount() - 1)) {
 233              $this->seek( $last );
 234          }
 235          return $this->next();
 236      }
 237      
 238      /**
 239       * @see ResultSet::beforeFirst()
 240       */
 241      public function beforeFirst()
 242      {
 243          $this->cursorPos = 0;
 244      }
 245  
 246      /**
 247       * @see ResultSet::afterLast()
 248       */
 249      public function afterLast()
 250      {
 251          $this->cursorPos = $this->getRecordCount() + 1;
 252      }
 253  
 254      /**
 255       * @see ResultSet::isAfterLast()
 256       */
 257      public function isAfterLast()
 258      {
 259          return ($this->cursorPos === $this->getRecordCount() + 1);
 260      }
 261  
 262      /**
 263       * @see ResultSet::isBeforeFirst()
 264       */
 265      public function isBeforeFirst()
 266      {
 267          return ($this->cursorPos === 0);
 268      }    
 269  
 270      /**
 271       * @see ResultSet::getCursorPos()
 272       */
 273      public function getCursorPos()
 274      {
 275          return $this->cursorPos;
 276      }
 277      
 278      /**
 279       * @see ResultSet::getRow()
 280       */
 281      public function getRow()
 282      {
 283          return $this->fields;
 284      }
 285      
 286      /**
 287       * @see ResultSet::get()
 288       */
 289      public function get($column)
 290      {
 291          $idx = (is_int($column) ? $column - 1 : $column);
 292          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 293          return $this->fields[$idx];
 294      }
 295      
 296      /**
 297       * @see ResultSet::getArray()
 298       */
 299      public function getArray($column) 
 300      {
 301          $idx = (is_int($column) ? $column - 1 : $column);
 302          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 303          if ($this->fields[$idx] === null) { return null; }
 304          return (array) unserialize($this->fields[$idx]);
 305      } 
 306  
 307      /**
 308       * @see ResultSet::getBoolean()
 309       */
 310      public function getBoolean($column) 
 311      {
 312          $idx = (is_int($column) ? $column - 1 : $column);
 313          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 314          if ($this->fields[$idx] === null) { return null; }
 315          return (boolean) $this->fields[$idx];
 316      }
 317              
 318      /**
 319       * @see ResultSet::getBlob()
 320       */
 321      public function getBlob($column) 
 322      {
 323          $idx = (is_int($column) ? $column - 1 : $column);
 324          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 325          if ($this->fields[$idx] === null) { return null; }
 326          require_once 'creole/util/Blob.php';
 327          $b = new Blob();
 328          $b->setContents($this->fields[$idx]);
 329          return $b;
 330      }    
 331  
 332      /**
 333       * @see ResultSet::getClob()
 334       */
 335      public function getClob($column) 
 336      {
 337          $idx = (is_int($column) ? $column - 1 : $column);
 338          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 339          if ($this->fields[$idx] === null) { return null; }
 340          require_once 'creole/util/Clob.php';
 341          $c = new Clob();
 342          $c->setContents($this->fields[$idx]);
 343          return $c;
 344      } 
 345  
 346      /**
 347       * @see ResultSet::getDate()
 348       */
 349      public function getDate($column, $format = '%x') 
 350      {
 351          $idx = (is_int($column) ? $column - 1 : $column);
 352          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 353          if ($this->fields[$idx] === null) { return null; }
 354          $ts = strtotime($this->fields[$idx]);        
 355          if ($ts === -1 || $ts === false) { // in PHP 5.1 return value changes to FALSE
 356              throw new SQLException("Unable to convert value at column " . $column . " to timestamp: " . $this->fields[$idx]);
 357          }
 358          if ($format === null) {
 359              return $ts;
 360          }
 361          if (strpos($format, '%') !== false) {
 362              return strftime($format, $ts);
 363          } else {
 364              return date($format, $ts);
 365          }
 366      }    
 367  
 368      /**
 369       * @see ResultSet::getFloat()
 370       */
 371      public function getFloat($column) 
 372      {
 373          $idx = (is_int($column) ? $column - 1 : $column);
 374          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 375          if ($this->fields[$idx] === null) { return null; }
 376          return (float) $this->fields[$idx];
 377      }
 378  
 379      /**
 380       * @see ResultSet::getInt()
 381       */
 382      public function getInt($column) 
 383      {
 384          $idx = (is_int($column) ? $column - 1 : $column);
 385          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 386          if ($this->fields[$idx] === null) { return null; }
 387          return (int) $this->fields[$idx];
 388      }
 389         
 390      /**
 391       * @see ResultSet::getString()
 392       */
 393      public function getString($column) 
 394      {
 395          $idx = (is_int($column) ? $column - 1 : $column);
 396          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 397          if ($this->fields[$idx] === null) { return null; }
 398          return ($this->rtrimString ? rtrim($this->fields[$idx]) : (string) $this->fields[$idx]);
 399      }
 400      
 401      /**
 402       * @see ResultSet::getTime()
 403       */
 404      public function getTime($column, $format = '%X') 
 405      {
 406          $idx = (is_int($column) ? $column - 1 : $column);
 407          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 408          if ($this->fields[$idx] === null) { return null; }
 409          
 410          $ts = strtotime($this->fields[$idx]);
 411          
 412          if ($ts === -1 || $ts === false) { // in PHP 5.1 return value changes to FALSE
 413              throw new SQLException("Unable to convert value at column " . (is_int($column) ? $column + 1 : $column) . " to timestamp: " . $this->fields[$idx]);
 414          }
 415          if ($format === null) {
 416              return $ts;
 417          }        
 418          if (strpos($format, '%') !== false) {
 419              return strftime($format, $ts);
 420          } else {
 421              return date($format, $ts);
 422          }        
 423      }
 424  
 425      /**
 426       * @see ResultSet::getTimestamp()
 427       */
 428      public function getTimestamp($column, $format = 'Y-m-d H:i:s') 
 429      {
 430          $idx = (is_int($column) ? $column - 1 : $column);
 431          if (!array_key_exists($idx, $this->fields)) { throw new SQLException("Invalid resultset column: " . $column); }
 432          if ($this->fields[$idx] === null) { return null; }
 433          
 434          $ts = strtotime($this->fields[$idx]);
 435          if ($ts === -1 || $ts === false) { // in PHP 5.1 return value changes to FALSE
 436              throw new SQLException("Unable to convert value at column " . $column . " to timestamp: " . $this->fields[$idx]);
 437          }
 438          if ($format === null) {
 439              return $ts;
 440          }
 441          if (strpos($format, '%') !== false) {
 442              return strftime($format, $ts);
 443          } else {
 444              return date($format, $ts);
 445          }        
 446      }  
 447  }