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