annotate core/lib/Drupal/Core/Database/StatementInterface.php @ 19:fa3358dc1485 tip

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