www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Database/StatementInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Database;
   4
   5 /**
   6  * Represents a prepared statement.
   7  *
   8  * Child implementations should either extend PDOStatement:
   9  * @code
  10  * class Drupal\Core\Database\Driver\oracle\Statement extends PDOStatement implements Drupal\Core\Database\StatementInterface {}
  11  * @endcode
  12  * or define their own class. If defining their own class, they will also have
  13  * to implement either the Iterator or IteratorAggregate interface before
  14  * Drupal\Core\Database\StatementInterface:
  15  * @code
  16  * class Drupal\Core\Database\Driver\oracle\Statement implements Iterator, Drupal\Core\Database\StatementInterface {}
  17  * @endcode
  18  *
  19  * @ingroup database
  20  */
  21 interface StatementInterface extends \Traversable {
  22
  23   /**
  24    * Constructs a new PDOStatement object.
  25    *
  26    * The PDO manual does not document this constructor, but when overriding the
  27    * PDOStatement class with a custom without this constructor, PDO will throw
  28    * the internal exception/warning:
  29    *
  30    * "PDO::query(): SQLSTATE[HY000]: General error: user-supplied statement does
  31    *  not accept constructor arguments"
  32    *
  33    * PDO enforces that the access type of this constructor must be protected,
  34    * and lastly, it also enforces that a custom PDOStatement interface (like
  35    * this) omits the constructor (declaring it results in fatal errors
  36    * complaining about "the access type must not be public" if it is public, and
  37    * "the access type must be omitted" if it is protected; i.e., conflicting
  38    * statements). The access type has to be protected.
  39    */
  40   //protected function __construct(Connection $dbh);
  41
  42   /**
  43    * Executes a prepared statement
  44    *
  45    * @param $args
  46    *   An array of values with as many elements as there are bound parameters in
  47    *   the SQL statement being executed.
  48    * @param $options
  49    *   An array of options for this query.
  50    *
  51    * @return
  52    *   TRUE on success, or FALSE on failure.
  53    */
  54   public function execute($args = [], $options = []);
  55
  56   /**
  57    * Gets the query string of this statement.
  58    *
  59    * @return
  60    *   The query string, in its form with placeholders.
  61    */
  62   public function getQueryString();
  63
  64   /**
  65    * Returns the number of rows affected by the last SQL statement.
  66    *
  67    * @return
  68    *   The number of rows affected by the last DELETE, INSERT, or UPDATE
  69    *   statement executed or throws \Drupal\Core\Database\RowCountException
  70    *   if the last executed statement was SELECT.
  71    *
  72    * @throws \Drupal\Core\Database\RowCountException
  73    */
  74   public function rowCount();
  75
  76   /**
  77    * Sets the default fetch mode for this statement.
  78    *
  79    * See http://php.net/manual/pdo.constants.php for the definition of the
  80    * constants used.
  81    *
  82    * @param $mode
  83    *   One of the PDO::FETCH_* constants.
  84    * @param $a1
  85    *   An option depending of the fetch mode specified by $mode:
  86    *   - for PDO::FETCH_COLUMN, the index of the column to fetch
  87    *   - for PDO::FETCH_CLASS, the name of the class to create
  88    *   - for PDO::FETCH_INTO, the object to add the data to
  89    * @param $a2
  90    *   If $mode is PDO::FETCH_CLASS, the optional arguments to pass to the
  91    *   constructor.
  92    */
  93   public function setFetchMode($mode, $a1 = NULL, $a2 = []);
  94
  95   /**
  96    * Fetches the next row from a result set.
  97    *
  98    * See http://php.net/manual/pdo.constants.php for the definition of the
  99    * constants used.
 100    *
 101    * @param $mode
 102    *   One of the PDO::FETCH_* constants.
 103    *   Default to what was specified by setFetchMode().
 104    * @param $cursor_orientation
 105    *   Not implemented in all database drivers, don't use.
 106    * @param $cursor_offset
 107    *   Not implemented in all database drivers, don't use.
 108    *
 109    * @return
 110    *   A result, formatted according to $mode.
 111    */
 112   public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL);
 113
 114   /**
 115    * Returns a single field from the next record of a result set.
 116    *
 117    * @param $index
 118    *   The numeric index of the field to return. Defaults to the first field.
 119    *
 120    * @return
 121    *   A single field from the next record, or FALSE if there is no next record.
 122    */
 123   public function fetchField($index = 0);
 124
 125   /**
 126    * Fetches the next row and returns it as an object.
 127    *
 128    * The object will be of the class specified by StatementInterface::setFetchMode()
 129    * or stdClass if not specified.
 130    */
 131   public function fetchObject();
 132
 133   /**
 134    * Fetches the next row and returns it as an associative array.
 135    *
 136    * This method corresponds to PDOStatement::fetchObject(), but for associative
 137    * arrays. For some reason PDOStatement does not have a corresponding array
 138    * helper method, so one is added.
 139    *
 140    * @return
 141    *   An associative array, or FALSE if there is no next row.
 142    */
 143   public function fetchAssoc();
 144
 145   /**
 146    * Returns an array containing all of the result set rows.
 147    *
 148    * @param $mode
 149    *   One of the PDO::FETCH_* constants.
 150    * @param $column_index
 151    *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
 152    * @param $constructor_arguments
 153    *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
 154    *
 155    * @return
 156    *   An array of results.
 157    */
 158   public function fetchAll($mode = NULL, $column_index = NULL, $constructor_arguments = NULL);
 159
 160   /**
 161    * Returns an entire single column of a result set as an indexed array.
 162    *
 163    * Note that this method will run the result set to the end.
 164    *
 165    * @param $index
 166    *   The index of the column number to fetch.
 167    *
 168    * @return
 169    *   An indexed array, or an empty array if there is no result set.
 170    */
 171   public function fetchCol($index = 0);
 172
 173   /**
 174    * Returns the entire result set as a single associative array.
 175    *
 176    * This method is only useful for two-column result sets. It will return an
 177    * associative array where the key is one column from the result set and the
 178    * value is another field. In most cases, the default of the first two columns
 179    * is appropriate.
 180    *
 181    * Note that this method will run the result set to the end.
 182    *
 183    * @param $key_index
 184    *   The numeric index of the field to use as the array key.
 185    * @param $value_index
 186    *   The numeric index of the field to use as the array value.
 187    *
 188    * @return
 189    *   An associative array, or an empty array if there is no result set.
 190    */
 191   public function fetchAllKeyed($key_index = 0, $value_index = 1);
 192
 193   /**
 194    * Returns the result set as an associative array keyed by the given field.
 195    *
 196    * If the given key appears multiple times, later records will overwrite
 197    * earlier ones.
 198    *
 199    * @param $key
 200    *   The name of the field on which to index the array.
 201    * @param $fetch
 202    *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
 203    *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
 204    *   other value it will be an array of objects. By default, the fetch mode
 205    *   set for the query will be used.
 206    *
 207    * @return
 208    *   An associative array, or an empty array if there is no result set.
 209    */
 210   public function fetchAllAssoc($key, $fetch = NULL);
 211
 212 }