Source for file Statement.php

Documentation is available at Statement.php

  1. <?php
  2. /*
  3.  *  $Id: Statement.php 1532 2007-05-31 17:45:07Z zYne $
  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.phpdoctrine.com>.
  20.  */
  21. Doctrine::autoload('Doctrine_Adapter_Statement_Interface');
  22. /**
  23.  * Doctrine_Connection_Statement
  24.  *
  25.  * @author      Konsta Vesterinen <kvesteri@cc.hut.fi>
  26.  * @license     http://www.opensource.org/licenses/lgpl-license.php LGPL
  27.  * @package     Doctrine
  28.  * @category    Object Relational Mapping
  29.  * @link        www.phpdoctrine.com
  30.  * @since       1.0
  31.  * @version     $Revision: 1532 $
  32.  */
  33. class Doctrine_Connection_Statement implements Doctrine_Adapter_Statement_Interface
  34. {
  35.     /**
  36.      * @var Doctrine_Connection $conn       Doctrine_Connection object, every connection
  37.      *                                       statement holds an instance of Doctrine_Connection
  38.      */
  39.     protected $_conn;
  40.     /**
  41.      * @var mixed $_stmt                    PDOStatement object, boolean false or Doctrine_Adapter_Statement object
  42.      */
  43.     protected $_stmt;
  44.     /**
  45.      * constructor
  46.      *
  47.      * @param Doctrine_Connection $conn     Doctrine_Connection object, every connection
  48.      *                                       statement holds an instance of Doctrine_Connection
  49.      * @param mixed $stmt 
  50.      */
  51.     public function __construct(Doctrine_Connection $conn, $stmt)
  52.     {
  53.         $this->_conn = $conn;
  54.         $this->_stmt = $stmt;
  55.  
  56.         if ($stmt === false) {
  57.             throw new Doctrine_Exception('Unknown statement object given.');
  58.         }
  59.     }
  60.     /**
  61.      * getConnection
  62.      * returns the connection object this statement uses
  63.      *
  64.      * @return Doctrine_Connection 
  65.      */
  66.     public function getConnection()
  67.     {
  68.         return $this->_conn;
  69.     }
  70.     public function getStatement()
  71.     {
  72.         return $this->_stmt;
  73.     }
  74.     public function getQuery()
  75.     {
  76.         return $this->_stmt->queryString;
  77.     }
  78.     /**
  79.      * bindColumn
  80.      * Bind a column to a PHP variable
  81.      *
  82.      * @param mixed $column         Number of the column (1-indexed) or name of the column in the result set.
  83.      *                               If using the column name, be aware that the name should match
  84.      *                               the case of the column, as returned by the driver.
  85.      *
  86.      * @param string $param         Name of the PHP variable to which the column will be bound.
  87.      * @param integer $type         Data type of the parameter, specified by the Doctrine::PARAM_* constants.
  88.      * @return boolean              Returns TRUE on success or FALSE on failure
  89.      */
  90.     public function bindColumn($column, $param, $type = null)
  91.     {
  92.         if($type === null) {
  93.             return $this->_stmt->bindColumn($column, $param);
  94.         } else {
  95.             return $this->_stmt->bindColumn($column, $param, $type);
  96.         }
  97.     }
  98.     /**
  99.      * bindValue
  100.      * Binds a value to a corresponding named or question mark
  101.      * placeholder in the SQL statement that was use to prepare the statement.
  102.      *
  103.      * @param mixed $param          Parameter identifier. For a prepared statement using named placeholders,
  104.      *                               this will be a parameter name of the form :name. For a prepared statement
  105.      *                               using question mark placeholders, this will be the 1-indexed position of the parameter
  106.      *
  107.      * @param mixed $value          The value to bind to the parameter.
  108.      * @param integer $type         Explicit data type for the parameter using the Doctrine::PARAM_* constants.
  109.      *
  110.      * @return boolean              Returns TRUE on success or FALSE on failure.
  111.      */
  112.     public function bindValue($param, $value, $type = null)
  113.     {
  114.         if($type === null) {
  115.             return $this->_stmt->bindValue($param, $value);
  116.         } else {
  117.             return $this->_stmt->bindValue($param, $value, $type);
  118.         }
  119.     }
  120.     /**
  121.      * bindParam
  122.      * Binds a PHP variable to a corresponding named or question mark placeholder in the
  123.      * SQL statement that was use to prepare the statement. Unlike Doctrine_Adapter_Statement_Interface->bindValue(),
  124.      * the variable is bound as a reference and will only be evaluated at the time
  125.      * that Doctrine_Adapter_Statement_Interface->execute() is called.
  126.      *
  127.      * Most parameters are input parameters, that is, parameters that are
  128.      * used in a read-only fashion to build up the query. Some drivers support the invocation
  129.      * of stored procedures that return data as output parameters, and some also as input/output
  130.      * parameters that both send in data and are updated to receive it.
  131.      *
  132.      * @param mixed $param          Parameter identifier. For a prepared statement using named placeholders,
  133.      *                               this will be a parameter name of the form :name. For a prepared statement
  134.      *                               using question mark placeholders, this will be the 1-indexed position of the parameter
  135.      *
  136.      * @param mixed $variable       Name of the PHP variable to bind to the SQL statement parameter.
  137.      *
  138.      * @param integer $type         Explicit data type for the parameter using the Doctrine::PARAM_* constants. To return
  139.      *                               an INOUT parameter from a stored procedure, use the bitwise OR operator to set the
  140.      *                               Doctrine::PARAM_INPUT_OUTPUT bits for the data_type parameter.
  141.      *
  142.      * @param integer $length       Length of the data type. To indicate that a parameter is an OUT parameter
  143.      *                               from a stored procedure, you must explicitly set the length.
  144.      * @param mixed $driverOptions 
  145.      * @return boolean              Returns TRUE on success or FALSE on failure.
  146.      */
  147.     public function bindParam($column, $variable, $type = null, $length = null, $driverOptions = array())
  148.     {
  149.         if($type === null) {
  150.             return $this->_stmt->bindParam($column, $variable);
  151.         } else {
  152.             return $this->_stmt->bindParam($column, $variable, $type, $length, $driverOptions);
  153.         }
  154.     }
  155.     /**
  156.      * closeCursor
  157.      * Closes the cursor, enabling the statement to be executed again.
  158.      *
  159.      * @return boolean              Returns TRUE on success or FALSE on failure.
  160.      */
  161.     public function closeCursor()
  162.     {
  163.         return $this->_stmt->closeCursor();
  164.     }
  165.     /**
  166.      * columnCount
  167.      * Returns the number of columns in the result set
  168.      *
  169.      * @return integer              Returns the number of columns in the result set represented
  170.      *                               by the Doctrine_Adapter_Statement_Interface object. If there is no result set,
  171.      *                               this method should return 0.
  172.      */
  173.     public function columnCount()
  174.     {
  175.         return $this->_stmt->columnCount();
  176.     }
  177.     /**
  178.      * errorCode
  179.      * Fetch the SQLSTATE associated with the last operation on the statement handle
  180.      *
  181.      * @see Doctrine_Adapter_Interface::errorCode()
  182.      * @return string       error code string
  183.      */
  184.     public function errorCode()
  185.     {
  186.         return $this->_stmt->errorCode();
  187.     }
  188.     /**
  189.      * errorInfo
  190.      * Fetch extended error information associated with the last operation on the statement handle
  191.      *
  192.      * @see Doctrine_Adapter_Interface::errorInfo()
  193.      * @return array        error info array
  194.      */
  195.     public function errorInfo()
  196.     {
  197.         return $this->_stmt->errorInfo();
  198.     }
  199.     /**
  200.      * execute
  201.      * Executes a prepared statement
  202.      *
  203.      * If the prepared statement included parameter markers, you must either:
  204.      * call PDOStatement->bindParam() to bind PHP variables to the parameter markers:
  205.      * bound variables pass their value as input and receive the output value,
  206.      * if any, of their associated parameter markers or pass an array of input-only
  207.      * parameter values
  208.      *
  209.      *
  210.      * @param array $params             An array of values with as many elements as there are
  211.      *                                   bound parameters in the SQL statement being executed.
  212.      * @return boolean                  Returns TRUE on success or FALSE on failure.
  213.      */
  214.     public function execute($params = null)
  215.     {
  216.         try {
  217.             $event = new Doctrine_Event($this, Doctrine_Event::STMT_EXECUTE, $this->getQuery(), $params);
  218.             $this->_conn->getListener()->preStmtExecute($event);
  219.  
  220.             $result = true;
  221.             if ( ! $event->skipOperation) {
  222.                 $result = $this->_stmt->execute($params);
  223.                 $this->_conn->incrementQueryCount();
  224.             }
  225.  
  226.             $this->_conn->getListener()->postStmtExecute($event);
  227.  
  228.             return $result;
  229.         } catch (PDOException $e) {
  230.         } catch (Doctrine_Adapter_Exception $e) {
  231.         }
  232.  
  233.         $this->_conn->rethrowException($e, $this);
  234.  
  235.         return false;
  236.     }
  237.     /**
  238.      * fetch
  239.      *
  240.      * @see Doctrine::FETCH_* constants
  241.      * @param integer $fetchStyle           Controls how the next row will be returned to the caller.
  242.      *                                       This value must be one of the Doctrine::FETCH_* constants,
  243.      *                                       defaulting to Doctrine::FETCH_BOTH
  244.      *
  245.      * @param integer $cursorOrientation    For a PDOStatement object representing a scrollable cursor,
  246.      *                                       this value determines which row will be returned to the caller.
  247.      *                                       This value must be one of the Doctrine::FETCH_ORI_* constants, defaulting to
  248.      *                                       Doctrine::FETCH_ORI_NEXT. To request a scrollable cursor for your
  249.      *                                       Doctrine_Adapter_Statement_Interface object,
  250.      *                                       you must set the Doctrine::ATTR_CURSOR attribute to Doctrine::CURSOR_SCROLL when you
  251.      *                                       prepare the SQL statement with Doctrine_Adapter_Interface->prepare().
  252.      *
  253.      * @param integer $cursorOffset         For a Doctrine_Adapter_Statement_Interface object representing a scrollable cursor for which the
  254.      *                                       $cursorOrientation parameter is set to Doctrine::FETCH_ORI_ABS, this value specifies
  255.      *                                       the absolute number of the row in the result set that shall be fetched.
  256.      *
  257.      *                                       For a Doctrine_Adapter_Statement_Interface object representing a scrollable cursor for
  258.      *                                       which the $cursorOrientation parameter is set to Doctrine::FETCH_ORI_REL, this value
  259.      *                                       specifies the row to fetch relative to the cursor position before
  260.      *                                       Doctrine_Adapter_Statement_Interface->fetch() was called.
  261.      *
  262.      * @return mixed 
  263.      */
  264.     public function fetch($fetchMode = Doctrine::FETCH_BOTH,
  265.                           $cursorOrientation = Doctrine::FETCH_ORI_NEXT,
  266.                           $cursorOffset = null)
  267.     {
  268.         $event = new Doctrine_Event($this, Doctrine_Event::STMT_FETCH, $this->getQuery());
  269.  
  270.         $event->fetchMode = $fetchMode;
  271.         $event->cursorOrientation = $cursorOrientation;
  272.         $event->cursorOffset = $cursorOffset;
  273.  
  274.         $data = $this->_conn->getListener()->preFetch($event);
  275.  
  276.         if ( ! $event->skipOperation) {
  277.             $data = $this->_stmt->fetch($fetchMode, $cursorOrientation, $cursorOffset);
  278.         }
  279.  
  280.         $this->_conn->getListener()->postFetch($event);
  281.  
  282.         return $data;
  283.     }
  284.     /**
  285.      * fetchAll
  286.      * Returns an array containing all of the result set rows
  287.      *
  288.      * @param integer $fetchMode            Controls how the next row will be returned to the caller.
  289.      *                                       This value must be one of the Doctrine::FETCH_* constants,
  290.      *                                       defaulting to Doctrine::FETCH_BOTH
  291.      *
  292.      * @param integer $columnIndex          Returns the indicated 0-indexed column when the value of $fetchStyle is
  293.      *                                       Doctrine::FETCH_COLUMN. Defaults to 0.
  294.      *
  295.      * @return array 
  296.      */
  297.     public function fetchAll($fetchMode = Doctrine::FETCH_BOTH,
  298.                              $columnIndex = null)
  299.     {
  300.         $event = new Doctrine_Event($this, Doctrine_Event::STMT_FETCHALL, $this->getQuery());
  301.         $event->fetchMode = $fetchMode;
  302.         $event->columnIndex = $columnIndex;
  303.  
  304.         $this->_conn->getListener()->preFetchAll($event);
  305.  
  306.         if ( ! $event->skipOperation) {
  307.             if ($columnIndex !== null) {
  308.                 $data = $this->_stmt->fetchAll($fetchMode, $columnIndex);
  309.             } else {
  310.                 $data = $this->_stmt->fetchAll($fetchMode);
  311.             }
  312.  
  313.             $event->data = $data;
  314.         }
  315.  
  316.         $this->_conn->getListener()->postFetchAll($event);
  317.  
  318.         return $data;
  319.     }
  320.     /**
  321.      * fetchColumn
  322.      * Returns a single column from the next row of a
  323.      * result set or FALSE if there are no more rows.
  324.      *
  325.      * @param integer $columnIndex          0-indexed number of the column you wish to retrieve from the row. If no
  326.      *                                       value is supplied, Doctrine_Adapter_Statement_Interface->fetchColumn()
  327.      *                                       fetches the first column.
  328.      *
  329.      * @return string                       returns a single column in the next row of a result set.
  330.      */
  331.     public function fetchColumn($columnIndex = 0)
  332.     {
  333.         return $this->_stmt->fetchColumn($columnIndex);
  334.     }
  335.     /**
  336.      * fetchObject
  337.      * Fetches the next row and returns it as an object.
  338.      *
  339.      * Fetches the next row and returns it as an object. This function is an alternative to
  340.      * Doctrine_Adapter_Statement_Interface->fetch() with Doctrine::FETCH_CLASS or Doctrine::FETCH_OBJ style.
  341.      *
  342.      * @param string $className             Name of the created class, defaults to stdClass.
  343.      * @param array $args                   Elements of this array are passed to the constructor.
  344.      *
  345.      * @return mixed                        an instance of the required class with property names that correspond
  346.      *                                       to the column names or FALSE in case of an error.
  347.      */
  348.     public function fetchObject($className = 'stdClass', $args = array())
  349.     {
  350.         return $this->_stmt->fetchObject($className, $args);
  351.     }
  352.     /**
  353.      * getAttribute
  354.      * Retrieve a statement attribute
  355.      *
  356.      * @param integer $attribute 
  357.      * @see Doctrine::ATTR_* constants
  358.      * @return mixed                        the attribute value
  359.      */
  360.     public function getAttribute($attribute)
  361.     {
  362.         return $this->_stmt->getAttribute($attribute);
  363.     }
  364.     /**
  365.      * getColumnMeta
  366.      * Returns metadata for a column in a result set
  367.      *
  368.      * @param integer $column               The 0-indexed column in the result set.
  369.      *
  370.      * @return array                        Associative meta data array with the following structure:
  371.      *
  372.      *           native_type                 The PHP native type used to represent the column value.
  373.      *           driver:decl_                type The SQL type used to represent the column value in the database. If the column in the result set is the result of a function, this value is not returned by PDOStatement->getColumnMeta().
  374.      *           flags                       Any flags set for this column.
  375.      *           name                        The name of this column as returned by the database.
  376.      *           len                         The length of this column. Normally -1 for types other than floating point decimals.
  377.      *           precision                   The numeric precision of this column. Normally 0 for types other than floating point decimals.
  378.      *           pdo_type                    The type of this column as represented by the PDO::PARAM_* constants.
  379.      */
  380.     public function getColumnMeta($column)
  381.     {
  382.         return $this->_stmt->getColumnMeta($column);
  383.     }
  384.     /**
  385.      * nextRowset
  386.      * Advances to the next rowset in a multi-rowset statement handle
  387.      *
  388.      * Some database servers support stored procedures that return more than one rowset
  389.      * (also known as a result set). The nextRowset() method enables you to access the second
  390.      * and subsequent rowsets associated with a PDOStatement object. Each rowset can have a
  391.      * different set of columns from the preceding rowset.
  392.      *
  393.      * @return boolean                      Returns TRUE on success or FALSE on failure.
  394.      */
  395.     public function nextRowset()
  396.     {
  397.         return $this->_stmt->nextRowset();
  398.     }
  399.     /**
  400.      * rowCount
  401.      * rowCount() returns the number of rows affected by the last DELETE, INSERT, or UPDATE statement
  402.      * executed by the corresponding object.
  403.      *
  404.      * If the last SQL statement executed by the associated Statement object was a SELECT statement,
  405.      * some databases may return the number of rows returned by that statement. However,
  406.      * this behaviour is not guaranteed for all databases and should not be
  407.      * relied on for portable applications.
  408.      *
  409.      * @return integer                      Returns the number of rows.
  410.      */
  411.     public function rowCount()
  412.     {
  413.         return $this->_stmt->rowCount();
  414.     }
  415.     /**
  416.      * setAttribute
  417.      * Set a statement attribute
  418.      *
  419.      * @param integer $attribute 
  420.      * @param mixed $value                  the value of given attribute
  421.      * @return boolean                      Returns TRUE on success or FALSE on failure.
  422.      */
  423.     public function setAttribute($attribute, $value)
  424.     {
  425.         return $this->_stmt->setAttribute($attribute, $value);
  426.     }
  427.     /**
  428.      * setFetchMode
  429.      * Set the default fetch mode for this statement
  430.      *
  431.      * @param integer $mode                 The fetch mode must be one of the Doctrine::FETCH_* constants.
  432.      * @return boolean                      Returns 1 on success or FALSE on failure.
  433.      */
  434.     public function setFetchMode($mode, $arg1 = null, $arg2 = null)
  435.     {
  436.         return $this->_stmt->setFetchMode($mode, $arg1, $arg2);
  437.     }
  438. }