1 <?php

     2 /*

     3  *  $Id$

     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, see

    19  * <http://www.doctrine-project.org>.

    20  */

    21 

    22 namespace Doctrine\DBAL\Driver;

    23 

    24 use \PDO;

    25 

    26 /**

    27  * Statement interface.

    28  * Drivers must implement this interface.

    29  * 

    30  * This resembles (a subset of) the PDOStatement interface.

    31  * 

    32  * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>

    33  * @author      Roman Borschel <roman@code-factory.org>

    34  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL

    35  * @link        www.doctrine-project.org

    36  * @since       2.0

    37  * @version     $Revision$

    38  */

    39 interface Statement

    40 {

    41     /**

    42      * Binds a value to a corresponding named or positional

    43      * placeholder in the SQL statement that was used to prepare the statement.

    44      *

    45      * @param mixed $param          Parameter identifier. For a prepared statement using named placeholders,

    46      *                              this will be a parameter name of the form :name. For a prepared statement

    47      *                              using question mark placeholders, this will be the 1-indexed position of the parameter

    48      *

    49      * @param mixed $value          The value to bind to the parameter.

    50      * @param integer $type         Explicit data type for the parameter using the PDO::PARAM_* constants.

    51      *

    52      * @return boolean              Returns TRUE on success or FALSE on failure.

    53      */

    54     function bindValue($param, $value, $type = null);

    55 

    56     /**

    57      * Binds a PHP variable to a corresponding named or question mark placeholder in the 

    58      * SQL statement that was use to prepare the statement. Unlike PDOStatement->bindValue(),

    59      * the variable is bound as a reference and will only be evaluated at the time 

    60      * that PDOStatement->execute() is called.

    61      *

    62      * Most parameters are input parameters, that is, parameters that are 

    63      * used in a read-only fashion to build up the query. Some drivers support the invocation 

    64      * of stored procedures that return data as output parameters, and some also as input/output

    65      * parameters that both send in data and are updated to receive it.

    66      *

    67      * @param mixed $param          Parameter identifier. For a prepared statement using named placeholders,

    68      *                              this will be a parameter name of the form :name. For a prepared statement

    69      *                              using question mark placeholders, this will be the 1-indexed position of the parameter

    70      *

    71      * @param mixed $variable       Name of the PHP variable to bind to the SQL statement parameter.

    72      *

    73      * @param integer $type         Explicit data type for the parameter using the PDO::PARAM_* constants. To return

    74      *                              an INOUT parameter from a stored procedure, use the bitwise OR operator to set the

    75      *                              PDO::PARAM_INPUT_OUTPUT bits for the data_type parameter.

    76      * @return boolean              Returns TRUE on success or FALSE on failure.

    77      */

    78     function bindParam($column, &$variable, $type = null);

    79 

    80     /**

    81      * Closes the cursor, enabling the statement to be executed again.

    82      *

    83      * @return boolean              Returns TRUE on success or FALSE on failure.

    84      */

    85     function closeCursor();

    86 

    87     /** 

    88      * columnCount

    89      * Returns the number of columns in the result set 

    90      *

    91      * @return integer              Returns the number of columns in the result set represented

    92      *                              by the PDOStatement object. If there is no result set,

    93      *                              this method should return 0.

    94      */

    95     function columnCount();

    96 

    97     /**

    98      * errorCode

    99      * Fetch the SQLSTATE associated with the last operation on the statement handle 

   100      *

   101      * @see Doctrine_Adapter_Interface::errorCode()

   102      * @return string       error code string

   103      */

   104     function errorCode();

   105 

   106     /**

   107      * errorInfo

   108      * Fetch extended error information associated with the last operation on the statement handle

   109      *

   110      * @see Doctrine_Adapter_Interface::errorInfo()

   111      * @return array        error info array

   112      */

   113     function errorInfo();

   114 

   115     /**

   116      * Executes a prepared statement

   117      *

   118      * If the prepared statement included parameter markers, you must either:

   119      * call PDOStatement->bindParam() to bind PHP variables to the parameter markers:

   120      * bound variables pass their value as input and receive the output value,

   121      * if any, of their associated parameter markers or pass an array of input-only

   122      * parameter values

   123      *

   124      *

   125      * @param array $params             An array of values with as many elements as there are

   126      *                                  bound parameters in the SQL statement being executed.

   127      * @return boolean                  Returns TRUE on success or FALSE on failure.

   128      */

   129     function execute($params = null);

   130 

   131     /**

   132      * fetch

   133      *

   134      * @see Query::HYDRATE_* constants

   135      * @param integer $fetchStyle           Controls how the next row will be returned to the caller.

   136      *                                      This value must be one of the Query::HYDRATE_* constants,

   137      *                                      defaulting to Query::HYDRATE_BOTH

   138      *

   139      * @param integer $cursorOrientation    For a PDOStatement object representing a scrollable cursor, 

   140      *                                      this value determines which row will be returned to the caller. 

   141      *                                      This value must be one of the Query::HYDRATE_ORI_* constants, defaulting to

   142      *                                      Query::HYDRATE_ORI_NEXT. To request a scrollable cursor for your 

   143      *                                      PDOStatement object,

   144      *                                      you must set the PDO::ATTR_CURSOR attribute to Doctrine::CURSOR_SCROLL when you

   145      *                                      prepare the SQL statement with Doctrine_Adapter_Interface->prepare().

   146      *

   147      * @param integer $cursorOffset         For a PDOStatement object representing a scrollable cursor for which the

   148      *                                      $cursorOrientation parameter is set to Query::HYDRATE_ORI_ABS, this value specifies

   149      *                                      the absolute number of the row in the result set that shall be fetched.

   150      *                                      

   151      *                                      For a PDOStatement object representing a scrollable cursor for 

   152      *                                      which the $cursorOrientation parameter is set to Query::HYDRATE_ORI_REL, this value 

   153      *                                      specifies the row to fetch relative to the cursor position before 

   154      *                                      PDOStatement->fetch() was called.

   155      *

   156      * @return mixed

   157      */

   158     function fetch($fetchStyle = PDO::FETCH_BOTH);

   159 

   160     /**

   161      * Returns an array containing all of the result set rows

   162      *

   163      * @param integer $fetchStyle           Controls how the next row will be returned to the caller.

   164      *                                      This value must be one of the Query::HYDRATE_* constants,

   165      *                                      defaulting to Query::HYDRATE_BOTH

   166      *

   167      * @param integer $columnIndex          Returns the indicated 0-indexed column when the value of $fetchStyle is

   168      *                                      Query::HYDRATE_COLUMN. Defaults to 0.

   169      *

   170      * @return array

   171      */

   172     function fetchAll($fetchStyle = PDO::FETCH_BOTH);

   173 

   174     /**

   175      * fetchColumn

   176      * Returns a single column from the next row of a

   177      * result set or FALSE if there are no more rows.

   178      *

   179      * @param integer $columnIndex          0-indexed number of the column you wish to retrieve from the row. If no 

   180      *                                      value is supplied, PDOStatement->fetchColumn() 

   181      *                                      fetches the first column.

   182      *

   183      * @return string                       returns a single column in the next row of a result set.

   184      */

   185     function fetchColumn($columnIndex = 0);

   186 

   187     /**

   188      * rowCount

   189      * rowCount() returns the number of rows affected by the last DELETE, INSERT, or UPDATE statement 

   190      * executed by the corresponding object.

   191      *

   192      * If the last SQL statement executed by the associated Statement object was a SELECT statement, 

   193      * some databases may return the number of rows returned by that statement. However, 

   194      * this behaviour is not guaranteed for all databases and should not be 

   195      * relied on for portable applications.

   196      *

   197      * @return integer                      Returns the number of rows.

   198      */

   199     function rowCount();

   200 }