[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: ResultSet.php,v 1.28 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 is the interface for classes the wrap db results.
  24   * 
  25   * The get*() methods in this interface will format values before returning them. Note
  26   * that if they will return null if the database returned NULL.  If the requested column does
  27   * not exist than an exception (SQLException) will be thrown.
  28   * 
  29   * <code>
  30   * $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
  31   * $rs->next();
  32   * 
  33   * $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
  34   * // $max_stamp will be date string or null if no MAX(stamp) was found
  35   * 
  36   * $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
  37   * // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
  38   * // SQLException: Invalid resultset column: max(stamp)
  39   * </code>
  40   * 
  41   * This class implements SPL IteratorAggregate, so you may iterate over the database results
  42   * using foreach():
  43   * <code>
  44   * foreach($rs as $row) {
  45   *   print_r($row); // row is assoc array returned by getRow()
  46   * }
  47   * </code>
  48   * 
  49   * @author    Hans Lellelid <hans@xmpl.org>
  50   * @version   $Revision: 1.28 $
  51   * @package   creole
  52   */
  53  interface ResultSet extends IteratorAggregate {
  54          
  55      /**
  56       * Index result set by field name.
  57       */
  58      const FETCHMODE_ASSOC = 1;
  59  
  60      /**
  61       * Index result set numerically.
  62       */
  63      const FETCHMODE_NUM = 2;
  64      
  65      /**
  66       * Get the PHP native resource for the result.
  67       * Arguably this should not be part of the interface: i.e. every driver should implement
  68       * it if they have a result resource, but conceivably drivers could be created that do
  69       * not.  For now every single driver does have a "dblink" resource property, and other
  70       * classes (e.g. ResultSet) need this info in order to get correct native errors.  We'll
  71       * leave it in for now, as it helps with driver development, with the caveat that it 
  72       * could be removed from the interface at a later point.
  73       * @return resource Query result or NULL if not not applicable.
  74       */
  75      public function getResource();
  76          
  77      /**
  78       * Sets the fetchmode used to retrieve results.
  79       * Changing fetchmodes mid-result retrieval is supported (haven't encountered any drivers 
  80       * that don't support that yet).
  81       * @param int $mode ResultSet::FETCHMODE_NUM or  ResultSet::FETCHMODE_ASSOC (default).
  82       * @return void
  83       */
  84      public function setFetchmode($mode);
  85      
  86      /**
  87       * Gets the fetchmode used to retrieve results.
  88       * @return int ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
  89       */
  90      public function getFetchmode();       
  91      
  92      /**
  93       * Whether assoc result keys get converted to lowercase for compatibility.
  94       * 
  95       * This defaults to FALSE unless Creole::COMPAT_ASSOC_LOWER flag has been passed to connection.
  96       * This property is read-only since it must be set when connection is created.  The
  97       * reason for this behavior is some drivers (e.g. SQLite) do the case conversions internally
  98       * based on a PHP ini value; it would not be possible to change the behavior from the ResultSet
  99       * (since query has already been executed).
 100       * 
 101       * @return boolean
 102       */
 103      public function isLowerAssocCase();
 104          
 105      /**
 106       * Moves the internal cursor to the next position and fetches the row at that position.
 107       * 
 108       * @return boolean <tt>true</tt> if success, <tt>false</tt> if no next record.
 109       * @throws SQLException on any driver-level errors.
 110       */
 111      public function next();
 112  
 113      /**
 114       * Moves the internal cursor to the previous position and fetches the
 115       * row at that position.
 116       * 
 117       * @return boolean <tt>true</tt> if success, <tt>false</tt> if no previous record.
 118       * @throws SQLException - if unable to move to previous position
 119       *                      - if ResultSet doesn't support reverse scrolling
 120       */
 121      public function previous();
 122  
 123      /**
 124       * Moves the cursor a relative number of rows, either positive or negative and fetches
 125       * the row at that position.
 126       * 
 127       * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
 128       * the first/last row and issues a Warning. Calling relative(0) is valid, but does not change the cursor 
 129       * position. 
 130       * 
 131       * @param integer $offset
 132       * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
 133       * @throws SQLException - if unable to move to relative position
 134       *                      - if rel pos is negative & ResultSet doesn't support reverse scrolling
 135       */
 136      public function relative($offset);
 137  
 138  
 139      /**
 140       * Moves the cursor to an absolute cursor position and fetches the row at that position.
 141       * 
 142       * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
 143       * the first/last row and issues a Warning.
 144       * 
 145       * @param integer $pos cursor position, first position is 1.
 146       * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
 147       * @throws SQLException - if unable to move to absolute position
 148       *                      - if position is before current pos & ResultSet doesn't support reverse scrolling
 149       */
 150      public function absolute($pos);
 151  
 152      /**
 153       * Moves cursor position WITHOUT FETCHING ROW AT THAT POSITION.
 154       * 
 155       * Generally this method is for internal driver stuff (e.g. other methods like
 156       * absolute() or relative() might call this and then call next() to get the row).
 157       * This method is public to facilitate more advanced ResultSet scrolling tools
 158       * -- e.g. cleaner implimentation of ResultSetIterator.
 159       * 
 160       * Some drivers will emulate seek() and not allow reverse seek (Oracle).
 161       * 
 162       * Seek is 0-based, but seek() is only for moving to the space _before_ the record
 163       * that you want to read.  I.e. if you seek(0) and then call next() you will have the 
 164       * first row (i.e. same as calling first() or absolute(1)).
 165       * 
 166       * <strong>IMPORTANT:  You cannot rely on the return value of this method to know whether a given
 167       * record exists for reading.  In some cases seek() will correctly return <code>false</code> if
 168       * the position doesn't exist, but in other drivers the seek is not performed until the
 169       * record is fetched. You can check the return value of absolute() if you need to know
 170       * whether a specific rec position is valid.</strong>
 171       * 
 172       * @param int $rownum The cursor pos to seek to.
 173       * @return boolean true on success, false if unable to seek to specified record.
 174       * @throws SQLException if trying to seek backwards with a driver that doesn't
 175       *                      support reverse-scrolling
 176       */
 177      public function seek($rownum);    
 178      
 179      /**
 180       * Move cursor to beginning of recordset.
 181       * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
 182       * @throws SQLException - if unable to move to first position
 183       *                      - if not at first pos & ResultSet doesn't support reverse scrolling
 184       */
 185      public function first();
 186  
 187      /**
 188       * Move cursor to end of recordset.
 189       * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
 190       * @throws SQLException - if unable to move to last position
 191       *                      - if unable to get num rows
 192       */
 193      public function last();
 194      
 195      /**
 196       * Sets cursort to before first record. This does not actually seek(), but
 197       * simply sets cursor pos to 0.
 198       * This is useful for inserting a record before the first in the set, etc.
 199       * @return void
 200       */
 201      public function beforeFirst();
 202  
 203  
 204      /**
 205       * Sets cursort to after the last record. This does not actually seek(), but
 206       * simply sets the cursor pos  to last + 1.
 207       * This [will be] useful for inserting a record after the last in the set,
 208       * when/if Creole supports updateable ResultSets.
 209       * @return void
 210       */
 211      public function afterLast();
 212  
 213  
 214      /**
 215       * Checks whether cursor is after the last record.
 216       * @return boolean
 217       * @throws SQLException on any driver-level error.
 218       */
 219      public function isAfterLast();
 220  
 221      /**
 222       * Checks whether cursor is before the first record.
 223       * @return boolean
 224       * @throws SQLException on any driver-level error.
 225       */
 226      public function isBeforeFirst();
 227  
 228      /**
 229       * Returns the current cursor position.
 230       * Cursor positions start at 0, but as soon as first row is fetched
 231       * cursor position is 1. (so first row is 1)
 232       * @return int
 233       */
 234      public function getCursorPos();
 235  
 236      /**
 237       * Gets current fields (assoc array).
 238       * @return array
 239       */
 240      public function getRow();
 241  
 242      /**
 243       * Get the number of rows in a result set.
 244       * @return int the number of rows
 245       * @throws SQLException - if unable to get a rowcount.
 246       */
 247      public function getRecordCount();
 248              
 249      /**
 250       * Frees the resources allocated for this result set.
 251       * Also empties any internal field array so that any calls to
 252       * get() method on closed ResultSet will result in "Invalid column" SQLException.
 253       * @return void
 254       */
 255      public function close();
 256      
 257      /**
 258       * A generic get method returns unformatted (=string) value.
 259       * This returns the raw results from the database.  Usually this will be a string, but some drivers
 260       * also can return objects (lob descriptors, etc) in certain cases.
 261       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).
 262       * @return mixed Usually expect a string.
 263       * @throws SQLException - If the column specified is not a valid key in current field array.
 264       */
 265      public function get($column);
 266      
 267      /**
 268       * Reads a column as an array.
 269       * The value of the column is unserialized & returned as an array.  The generic case of this function is 
 270       * very PHP-specific.  Other drivers (e.g. Postgres) will format values into their native array format.
 271       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 272       * @return array value or null if database returned null.
 273       * @throws SQLException - If the column specified is not a valid key in current field array.
 274       */
 275      public function getArray($column);
 276  
 277      /**
 278       * Returns value translated to boolean.
 279       * Default is to map 0 => false, 1 => true, but some database drivers may override this behavior.
 280       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 281       * @return boolean value or null if database returned null.
 282       * @throws SQLException - If the column specified is not a valid key in current field array.
 283       */
 284      public function getBoolean($column);
 285              
 286      /**
 287       * Returns Blob with contents of column value.
 288       * 
 289       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 290       * @return Blob New Blob with data from column or null if database returned null.
 291       * @throws SQLException - If the column specified is not a valid key in current field array.
 292       */
 293      public function getBlob($column);
 294  
 295      /**
 296       * Returns Clob with contents of column value.
 297       * 
 298       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 299       * @return Clob New Clob object with data from column or null if database returned null.
 300       * @throws SQLException - If the column specified is not a valid key in current field array.
 301       */
 302      public function getClob($column);
 303  
 304      /**
 305       * Return a formatted date.
 306       * 
 307       * The default format for dates returned is preferred (in your locale, as specified using setlocale()) 
 308       * format w/o time (i.e. strftime("%x", $val)).  Override this by specifying a format second parameter.  You
 309       * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
 310       * 
 311       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 312       * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
 313       *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
 314       * @return mixed  Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null. 
 315       * @throws SQLException - If the column specified is not a valid key in current field array.
 316       */
 317      public function getDate($column, $format = '%x');   
 318  
 319      /**
 320       * Returns value cast as a float (in PHP this is same as double).
 321       * 
 322       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 323       * @return float value or null if database returned null
 324       * @throws SQLException - If the column specified is not a valid key in current field array.
 325       */
 326      public function getFloat($column);
 327  
 328      /**
 329       * Returns value cast as integer.
 330       * 
 331       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 332       * @return int value or null if database returned null
 333       * @see getInteger()
 334       * @throws SQLException - If the column specified is not a valid key in current field array.
 335       */
 336      public function getInt($column);      
 337  
 338      /**
 339       * Returns value cast as string.
 340       * 
 341       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 342       * @return string value or null if database returned null
 343       * @see get()
 344       * @throws SQLException - If the column specified is not a valid key in current field array.
 345       */
 346      public function getString($column);
 347      
 348      /**
 349       * Return a formatted time.
 350       * 
 351       * The default format for times returned is preferred (in your locale, as specified using setlocale()) 
 352       * format w/o date (i.e. strftime("%X", $val)).  Override this by specifying a format second parameter.  You
 353       * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
 354       * 
 355       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 356       * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
 357       *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
 358       * @return mixed  Formatted time, or integer unix timestamp (using today's date) if $format was null. 
 359       * @throws SQLException - If the column specified is not a valid key in current field array.
 360       */
 361      public function getTime($column, $format = '%X');
 362  
 363      /**
 364       * Return a formatted timestamp.
 365       * 
 366       * The default format for timestamp is ISO standard YYYY-MM-DD HH:MM:SS (i.e. date('Y-m-d H:i:s', $val).
 367       * Override this by specifying a format second parameter.  You can also specify a strftime()-style formatter.
 368       * 
 369       * Hint: if you want to get the unix timestamp use the "U" formatter string.
 370       * 
 371       * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
 372       * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
 373       *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
 374       * @return mixed Formatted timestamp, or integer unix timestamp (if $format was null)
 375       * @throws SQLException - If the column specified is not a valid key in current field array.
 376       */
 377      public function getTimestamp($column, $format = 'Y-m-d H:i:s');
 378      
 379  }
 380