[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: PreparedStatement.php,v 1.21 2005/03/29 16:56:09 gamr 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   * Interface for a pre-compiled SQL statement.
  24   * 
  25   * Many drivers do not take advantage of pre-compiling SQL statements; for these
  26   * cases the precompilation is emulated.  This emulation comes with slight penalty involved
  27   * in parsing the queries, but provides other benefits such as a cleaner object model and ability
  28   * to work with BLOB and CLOB values w/o needing special LOB-specific routines.
  29   * 
  30   * This class is abstract because there are driver-specific implementations in [clearly] how queries
  31   * are executed, and how parameters are bound.
  32   * 
  33   * This class is not as abstract as the JDBC version.  For exmple, if you are using a driver
  34   * that uses name-based query param substitution, then you'd better bind your variables to
  35   * names rather than index numbers.  e.g. in Oracle
  36   * <code>
  37   *            $stmt = $conn->prepareStatement("INSERT INTO users (name, passwd) VALUES (:name, :pass)");
  38   *            $stmt->setString(":name", $name);
  39   *            $stmt->executeUpdate();            
  40   * </code>
  41   * 
  42   * Developer note:  In many ways this interface is an extension of the Statement interface.  However, due 
  43   * to limitations in PHP5's interface extension model (specifically that you cannot change signatures on
  44   * methods defined in parent interface), we cannot extend the Statement interface.
  45   *
  46   * @author    Hans Lellelid <hans@xmpl.org>
  47   * @version   $Revision: 1.21 $
  48   * @package   creole
  49   */
  50  interface PreparedStatement {
  51       
  52      /**
  53       * Gets the db Connection that created this statement.
  54       * @return Connection
  55       */
  56      public function getConnection();    
  57  
  58      /**
  59       * Get the PHP native resource for the statement (if supported).
  60       * @return resource
  61       */
  62      public function getResource();
  63          
  64      /**
  65       * Free resources associated with this statement.
  66       * Some drivers will need to implement this method to free
  67       * database result resources. 
  68       * 
  69       * @return void
  70       */
  71      public function close();
  72      
  73      /**
  74       * Get result set.
  75       * This assumes that the last thing done was an executeQuery() or an execute()
  76       * with SELECT-type query.
  77       *
  78       * @return RestultSet Last ResultSet or <code>null</code> if not applicable.
  79       */
  80      public function getResultSet();
  81      
  82      /**
  83       * Gets next result set (if this behavior is supported by driver).
  84       * Some drivers (e.g. MSSQL) support returning multiple result sets -- e.g.
  85       * from stored procedures.
  86       *
  87       * This function also closes any current restult set.
  88       *
  89       * Default behavior is for this function to return false.  Driver-specific
  90       * implementations of this class can override this method if they actually
  91       * support multiple result sets.
  92       * 
  93       * @return boolean True if there is another result set, otherwise false.
  94       */
  95      public function getMoreResults();
  96      
  97      /**
  98       * Get update count.
  99       *
 100       * @return int Number of records affected, or <code>null</code> if not applicable.
 101       */
 102      public function getUpdateCount();
 103  
 104      /**
 105       * Sets the maximum number of rows to return from db.
 106       * This will affect the SQL if the RDBMS supports native LIMIT; if not,
 107       * it will be emulated.  Limit only applies to queries (not update sql).
 108       * @param int $v Maximum number of rows or 0 for all rows.
 109       * @return void
 110       */
 111      public function setLimit($v);
 112      
 113      /**
 114       * Returns the maximum number of rows to return or 0 for all.
 115       * @return int
 116       */
 117      public function getLimit();
 118      
 119      /**
 120       * Sets the start row.
 121       * This will affect the SQL if the RDBMS supports native OFFSET; if not,
 122       * it will be emulated. Offset only applies to queries (not update) and 
 123       * only is evaluated when LIMIT is set!
 124       * @param int $v
 125       * @return void
 126       */ 
 127      public function setOffset($v);
 128      
 129      /**
 130       * Returns the start row.
 131       * Offset only applies when Limit is set!
 132       * @return int
 133       */
 134      public function getOffset();
 135      
 136      /**
 137       * Executes the SQL query in this PreparedStatement object and returns the resultset generated by the query.
 138       * We support two signatures for this method:
 139       * - $stmt->executeQuery(ResultSet::FETCHMODE_NUM);
 140       * - $stmt->executeQuery(array($param1, $param2), ResultSet::FETCHMODE_NUM);
 141       * @param mixed $p1 Either (array) Parameters that will be set using PreparedStatement::set() before query is executed or (int) fetchmode.
 142       * @param int $fetchmode The mode to use when fetching the results (e.g. ResultSet::FETCHMODE_NUM, ResultSet::FETCHMODE_ASSOC).
 143       * @return ResultSet
 144       * @throws SQLException if a database access error occurs.
 145       */
 146      public function executeQuery();
 147      
 148      /**
 149       * Executes the SQL INSERT, UPDATE, or DELETE statement in this PreparedStatement object.
 150       * 
 151       * @param array $params Parameters that will be set using PreparedStatement::set() before query is executed.
 152       * @return int Number of affected rows (or 0 for drivers that return nothing).
 153       * @throws SQLException if a database access error occurs.
 154       */
 155      public function executeUpdate($params = null);
 156  
 157      /**
 158       * A generic set method.
 159       * 
 160       * You can use this if you don't want to concern yourself with the details.  It involves
 161       * slightly more overhead than the specific settesr, since it grabs the PHP type to determine
 162       * which method makes most sense.
 163       * 
 164       * @param int $paramIndex
 165       * @param mixed $value
 166       * @return void
 167       * @throws SQLException
 168       */
 169      public function set($paramIndex, $value);
 170      
 171      /**
 172       * Sets an array.
 173       * Unless a driver-specific method is used, this means simply serializing
 174       * the passed parameter and storing it as a string.
 175       * @param int $paramIndex
 176       * @param array $value
 177       * @return void
 178       */
 179      public function setArray($paramIndex, $value);
 180  
 181      /**
 182       * Sets a boolean value.
 183       * Default behavior is true = 1, false = 0.
 184       * @param int $paramIndex
 185       * @param boolean $value
 186       * @return void
 187       */
 188      public function setBoolean($paramIndex, $value);
 189      
 190  
 191      /**
 192       * @param int $paramIndex
 193       * @param mixed $blob Blob object or string containing data.
 194       * @return void
 195       */
 196      public function setBlob($paramIndex, $blob);
 197  
 198      /**
 199       * @param int $paramIndex
 200       * @param mixed $clob Clob object  or string containing data.
 201       * @return void
 202       */
 203      public function setClob($paramIndex, $clob);
 204  
 205      /**
 206       * @param int $paramIndex
 207       * @param string $value
 208       * @return void
 209       */
 210      public function setDate($paramIndex, $value);
 211          
 212      /**
 213       * @param int $paramIndex
 214       * @param float $value
 215       * @return void
 216       */
 217      public function setFloat($paramIndex, $value);
 218  
 219      /**
 220       * @param int $paramIndex
 221       * @param int $value
 222       * @return void
 223       */
 224      public function setInt($paramIndex, $value);
 225  
 226      /**
 227       * @param int $paramIndex
 228       * @return void
 229       */
 230      public function setNull($paramIndex);
 231  
 232      /**
 233       * @param int $paramIndex
 234       * @param string $value
 235       * @return void
 236       */
 237      public function setString($paramIndex, $value);
 238      
 239      /**
 240       * @param int $paramIndex
 241       * @param string $value
 242       * @return void
 243       */
 244      public function setTime($paramIndex, $value);
 245      
 246      /**
 247       * @param int $paramIndex
 248       * @param string $value
 249       * @return void
 250       */
 251      public function setTimestamp($paramIndex, $value);
 252              
 253  }