[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 PDO;
  12  use PDOStatement;
  13  
  14  /**
  15   *
  16   * An interface to the native PDO object.
  17   *
  18   * @package Aura.Sql
  19   *
  20   */
  21  interface PdoInterface
  22  {
  23      /**
  24       *
  25       * Begins a transaction and turns off autocommit mode.
  26       *
  27       * @return bool True on success, false on failure.
  28       *
  29       * @see http://php.net/manual/en/pdo.begintransaction.php
  30       *
  31       */
  32      public function beginTransaction(): bool;
  33  
  34      /**
  35       *
  36       * Commits the existing transaction and restores autocommit mode.
  37       *
  38       * @return bool True on success, false on failure.
  39       *
  40       * @see http://php.net/manual/en/pdo.commit.php
  41       *
  42       */
  43      public function commit(): bool;
  44  
  45      /**
  46       *
  47       * Introduced in 6.x due to PHP 8.4 change. This is a BC break for Aura.Sql.
  48       *
  49       * @param string $dsn The Data Source Name, or DSN, contains the information required to connect to the database.
  50       *
  51       * @param string | null $username  The user name for the DSN string. This parameter is optional for some PDO drivers.
  52       *
  53       * @param string | null $password The password for the DSN string. This parameter is optional for some PDO drivers.
  54       *
  55       * @param array | null $options  A key=>value array of driver-specific connection options.
  56       *
  57       * @return \PDO Returns an instance of a generic PDO instance.
  58       *
  59       * @see https://www.php.net/manual/en/pdo.connect.php
  60       */
  61      public static function connect(
  62          string $dsn,
  63          ?string $username = null,
  64          #[\SensitiveParameter] ?string $password = null,
  65          ?array $options = null
  66      ): static;
  67  
  68      /**
  69       *
  70       * Gets the most recent error code.
  71       *
  72       * @return string|null
  73       */
  74      public function errorCode(): ?string;
  75  
  76      /**
  77       *
  78       * Gets the most recent error info.
  79       *
  80       * @return array
  81       *
  82       */
  83      public function errorInfo(): array;
  84  
  85      /**
  86       *
  87       * Executes an SQL statement and returns the number of affected rows.
  88       *
  89       * @param string $statement The SQL statement to execute.
  90       *
  91       * @return int|false The number of rows affected.
  92       *
  93       * @see http://php.net/manual/en/pdo.exec.php
  94       *
  95       */
  96      public function exec(string $statement): int|false;
  97  
  98      /**
  99       *
 100       * Gets a PDO attribute value.
 101       *
 102       * @param int $attribute The PDO::ATTR_* constant.
 103       *
 104       * @return bool|int|string|array|null The value for the attribute.
 105       *
 106       */
 107      public function getAttribute(int $attribute): bool|int|string|array|null;
 108  
 109      /**
 110       *
 111       * Returns all currently available PDO drivers.
 112       *
 113       * @return array
 114       *
 115       */
 116      public static function getAvailableDrivers(): array;
 117  
 118      /**
 119       *
 120       * Is a transaction currently active?
 121       *
 122       * @return bool
 123       *
 124       * @see http://php.net/manual/en/pdo.intransaction.php
 125       *
 126       */
 127      public function inTransaction(): bool;
 128  
 129      /**
 130       *
 131       * Returns the last inserted autoincrement sequence value.
 132       *
 133       * @param string|null $name The name of the sequence to check; typically needed
 134       * only for PostgreSQL, where it takes the form of `<table>_<column>_seq`.
 135       *
 136       * @return string|false
 137       *
 138       * @see http://php.net/manual/en/pdo.lastinsertid.php
 139       *
 140       */
 141      public function lastInsertId(?string $name = null): string|false;
 142  
 143      /**
 144       *
 145       * Prepares an SQL statement for execution.
 146       *
 147       * @param string $query The SQL statement to prepare for execution.
 148       *
 149       * @param array $options Set these attributes on the returned
 150       * PDOStatement.
 151       *
 152       * @return \PDOStatement|false
 153       *
 154       * @see http://php.net/manual/en/pdo.prepare.php
 155       */
 156      public function prepare(string $query, array $options = []): PDOStatement|false;
 157  
 158      /**
 159       *
 160       * Queries the database and returns a PDOStatement.
 161       *
 162       * @param string $query The SQL statement to prepare and execute.
 163       *
 164       * @param int|null $fetchMode
 165       *
 166       * @param mixed ...$fetch_mode_args Optional fetch-related parameters.
 167       *
 168       * @return \PDOStatement|false
 169       *
 170       * @see http://php.net/manual/en/pdo.query.php
 171       *
 172       */
 173      public function query(string $query, ?int $fetchMode = null, ...$fetch_mode_args): PDOStatement|false;
 174  
 175      /**
 176       *
 177       * Quotes a value for use in an SQL statement.
 178       *
 179       * @param string|int|array|float|null $value The value to quote.
 180       *
 181       * @param int $type A data type hint for the database driver.
 182       *
 183       * @return string|false The quoted value.
 184       *
 185       * @see http://php.net/manual/en/pdo.quote.php
 186       *
 187       */
 188      public function quote(string|int|array|float|null $value, int $type = PDO::PARAM_STR): string|false;
 189  
 190      /**
 191       *
 192       * Rolls back the current transaction and restores autocommit mode.
 193       *
 194       * @return bool True on success, false on failure.
 195       *
 196       * @see http://php.net/manual/en/pdo.rollback.php
 197       *
 198       */
 199      public function rollBack(): bool;
 200  
 201      /**
 202       *
 203       * Sets a PDO attribute value.
 204       *
 205       * @param int $attribute The PDO::ATTR_* constant.
 206       *
 207       * @param mixed $value The value for the attribute.
 208       *
 209       * @return bool
 210       *
 211       */
 212      public function setAttribute(int $attribute, mixed $value): bool;
 213  }