[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   * This file is part of Aura for PHP.
   5   *
   6   * @license https://opensource.org/licenses/MIT MIT
   7   *
   8   */
   9  namespace Aura\Sql;
  10  
  11  use Aura\Sql\Parser\ParserInterface;
  12  use Aura\Sql\Profiler\ProfilerInterface;
  13  use PDO;
  14  
  15  /**
  16   *
  17   * An interface to the Aura.Sql extended PDO object.
  18   *
  19   * @package Aura.Sql
  20   *
  21   */
  22  interface ExtendedPdoInterface extends PdoInterface
  23  {
  24      /**
  25       *
  26       * Connects to the database.
  27       *
  28       */
  29      public function connect();
  30  
  31      /**
  32       *
  33       * Disconnects from the database.
  34       *
  35       */
  36      public function disconnect();
  37  
  38      /**
  39       *
  40       * Performs a statement and returns the number of affected rows.
  41       *
  42       * @param string $statement The SQL statement to prepare and execute.
  43       *
  44       * @param array $values Values to bind to the query.
  45       *
  46       * @return int
  47       *
  48       */
  49      public function fetchAffected($statement, array $values = []);
  50  
  51      /**
  52       *
  53       * Fetches a sequential array of rows from the database; the rows
  54       * are represented as associative arrays.
  55       *
  56       * @param string $statement The SQL statement to prepare and execute.
  57       *
  58       * @param array $values Values to bind to the query.
  59       *
  60       * @return array
  61       *
  62       */
  63      public function fetchAll($statement, array $values = []);
  64  
  65      /**
  66       *
  67       * Fetches an associative array of rows from the database; the rows
  68       * are represented as associative arrays. The array of rows is keyed
  69       * on the first column of each row.
  70       *
  71       * N.b.: if multiple rows have the same first column value, the last
  72       * row with that value will override earlier rows.
  73       *
  74       * @param string $statement The SQL statement to prepare and execute.
  75       *
  76       * @param array $values Values to bind to the query.
  77       *
  78       * @return array
  79       *
  80       */
  81      public function fetchAssoc($statement, array $values = []);
  82  
  83      /**
  84       *
  85       * Fetches the first column of rows as a sequential array.
  86       *
  87       * @param string $statement The SQL statement to prepare and execute.
  88       *
  89       * @param array $values Values to bind to the query.
  90       *
  91       * @return array
  92       *
  93       */
  94      public function fetchCol($statement, array $values = []);
  95  
  96      /**
  97       *
  98       * Fetches multiple from the database as an associative array.
  99       * The first column will be the index
 100       *
 101       * @param string $statement The SQL statement to prepare and execute.
 102       *
 103       * @param array $values Values to bind to the query.
 104       *
 105       * @param int $style a fetch style defaults to PDO::FETCH_COLUMN for single
 106       * values, use PDO::FETCH_NAMED when fetching a multiple columns
 107       *
 108       * @return array
 109       *
 110       */
 111      public function fetchGroup(
 112          $statement,
 113          array $values = [],
 114          $style = PDO::FETCH_COLUMN
 115      );
 116  
 117      /**
 118       *
 119       * Fetches one row from the database as an object, mapping column values
 120       * to object properties.
 121       *
 122       * Warning: PDO "injects property-values BEFORE invoking the constructor -
 123       * in other words, if your class initializes property-values to defaults
 124       * in the constructor, you will be overwriting the values injected by
 125       * fetchObject() !"
 126       * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
 127       *
 128       * @param string $statement The SQL statement to prepare and execute.
 129       *
 130       * @param array $values Values to bind to the query.
 131       *
 132       * @param string $class The name of the class to create.
 133       *
 134       * @param array $args Arguments to pass to the object constructor.
 135       *
 136       * @return object
 137       *
 138       */
 139      public function fetchObject(
 140          $statement,
 141          array $values = [],
 142          $class = 'stdClass',
 143          array $args = []
 144      );
 145  
 146      /**
 147       *
 148       * Fetches a sequential array of rows from the database; the rows
 149       * are represented as objects, where the column values are mapped to
 150       * object properties.
 151       *
 152       * Warning: PDO "injects property-values BEFORE invoking the constructor -
 153       * in other words, if your class initializes property-values to defaults
 154       * in the constructor, you will be overwriting the values injected by
 155       * fetchObject() !"
 156       * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
 157       *
 158       * @param string $statement The SQL statement to prepare and execute.
 159       *
 160       * @param array $values Values to bind to the query.
 161       *
 162       * @param string $class The name of the class to create from each
 163       * row.
 164       *
 165       * @param array $args Arguments to pass to each object constructor.
 166       *
 167       * @return array
 168       *
 169       */
 170      public function fetchObjects(
 171          $statement,
 172          array $values = [],
 173          $class = 'stdClass',
 174          array $args = []
 175      );
 176  
 177      /**
 178       *
 179       * Fetches one row from the database as an associative array.
 180       *
 181       * @param string $statement The SQL statement to prepare and execute.
 182       *
 183       * @param array $values Values to bind to the query.
 184       *
 185       * @return array
 186       *
 187       */
 188      public function fetchOne($statement, array $values = []);
 189  
 190      /**
 191       *
 192       * Fetches an associative array of rows as key-value pairs (first
 193       * column is the key, second column is the value).
 194       *
 195       * @param string $statement The SQL statement to prepare and execute.
 196       *
 197       * @param array $values Values to bind to the query.
 198       *
 199       * @return array
 200       *
 201       */
 202      public function fetchPairs($statement, array $values = []);
 203  
 204      /**
 205       *
 206       * Fetches the very first value (i.e., first column of the first row).
 207       *
 208       * @param string $statement The SQL statement to prepare and execute.
 209       *
 210       * @param array $values Values to bind to the query.
 211       *
 212       * @return mixed
 213       *
 214       */
 215      public function fetchValue($statement, array $values = []);
 216  
 217      /**
 218       *
 219       * Returns the Parser instance.
 220       *
 221       * @return ParserInterface
 222       *
 223       */
 224      public function getParser();
 225  
 226      /**
 227       *
 228       * Return the inner PDO (if any)
 229       *
 230       * @return \PDO
 231       *
 232       */
 233      public function getPdo();
 234  
 235      /**
 236       *
 237       * Returns the Profiler instance.
 238       *
 239       * @return ProfilerInterface
 240       *
 241       */
 242      public function getProfiler();
 243  
 244      /**
 245       *
 246       * Quotes a multi-part (dotted) identifier name.
 247       *
 248       * @param string $name The multi-part identifier name.
 249       *
 250       * @return string The multi-part identifier name, quoted.
 251       *
 252       */
 253      public function quoteName($name);
 254  
 255      /**
 256       *
 257       * Quotes a single identifier name.
 258       *
 259       * @param string $name The identifier name.
 260       *
 261       * @return string The quoted identifier name.
 262       *
 263       */
 264      public function quoteSingleName($name);
 265  
 266      /**
 267       *
 268       * Is the PDO connection active?
 269       *
 270       * @return bool
 271       *
 272       */
 273      public function isConnected();
 274  
 275      /**
 276       *
 277       * Sets the Parser instance.
 278       *
 279       * @param ParserInterface $parser The Parser instance.
 280       *
 281       */
 282      public function setParser(ParserInterface $parser);
 283  
 284      /**
 285       *
 286       * Sets the Profiler instance.
 287       *
 288       * @param ProfilerInterface $profiler The Profiler instance.
 289       *
 290       */
 291      public function setProfiler(ProfilerInterface $profiler);
 292  
 293      /**
 294       *
 295       * Yields rows from the database
 296       *
 297       * @param string $statement The SQL statement to prepare and execute.
 298       *
 299       * @param array $values Values to bind to the query.
 300       *
 301       * @return \Generator
 302       *
 303       */
 304      public function yieldAll($statement, array $values = []);
 305  
 306      /**
 307       *
 308       * Yields rows from the database keyed on the first column of each row.
 309       *
 310       * @param string $statement The SQL statement to prepare and execute.
 311       *
 312       * @param array $values Values to bind to the query.
 313       *
 314       * @return \Generator
 315       *
 316       */
 317      public function yieldAssoc($statement, array $values = []);
 318  
 319      /**
 320       *
 321       * Yields the first column of all rows
 322       *
 323       * @param string $statement The SQL statement to prepare and execute.
 324       *
 325       * @param array $values Values to bind to the query.
 326       *
 327       * @return \Generator
 328       *
 329       */
 330      public function yieldCol($statement, array $values = []);
 331  
 332      /**
 333       *
 334       * Yields objects where the column values are mapped to object properties.
 335       *
 336       * Warning: PDO "injects property-values BEFORE invoking the constructor -
 337       * in other words, if your class initializes property-values to defaults
 338       * in the constructor, you will be overwriting the values injected by
 339       * fetchObject() !"
 340       * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
 341       *
 342       * @param string $statement The SQL statement to prepare and execute.
 343       *
 344       * @param array $values Values to bind to the query.
 345       *
 346       * @param string $class The name of the class to create from each
 347       * row.
 348       *
 349       * @param array $args Arguments to pass to each object constructor.
 350       *
 351       * @return \Generator
 352       *
 353       */
 354      public function yieldObjects(
 355          $statement,
 356          array $values = [],
 357          $class = 'stdClass',
 358          array $args = []
 359      );
 360  
 361      /**
 362       *
 363       * Yields key-value pairs (first column is the key, second column is the
 364       * value).
 365       *
 366       * @param string $statement The SQL statement to prepare and execute.
 367       *
 368       * @param array $values Values to bind to the query.
 369       *
 370       * @return \Generator
 371       *
 372       */
 373      public function yieldPairs($statement, array $values = []);
 374  
 375      /**
 376       *
 377       * Performs a query after preparing the statement with bound values, then
 378       * returns the result as a PDOStatement.
 379       *
 380       * @param string $statement The SQL statement to prepare and execute.
 381       *
 382       * @param array $values Values to bind to the query.
 383       *
 384       * @return \PDOStatement
 385       *
 386       */
 387      public function perform($statement, array $values = []);
 388  
 389      /**
 390       *
 391       * Prepares an SQL statement with bound values.
 392       *
 393       * This method only binds values that have placeholders in the
 394       * statement, thereby avoiding errors from PDO regarding too many bound
 395       * values. It also binds all sequential (question-mark) placeholders.
 396       *
 397       * If a placeholder value is an array, the array is converted to a string
 398       * of comma-separated quoted values; e.g., for an `IN (...)` condition.
 399       * The quoted string is replaced directly into the statement instead of
 400       * using `PDOStatement::bindValue()` proper.
 401       *
 402       * @param string $statement The SQL statement to prepare for execution.
 403       *
 404       * @param array $values The values to bind to the statement, if any.
 405       *
 406       * @return \PDOStatement
 407       *
 408       * @see http://php.net/manual/en/pdo.prepare.php
 409       *
 410       */
 411      public function prepareWithValues($statement, array $values = []);
 412  }