[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Database Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Database\Pdo;
  10  
  11  use Joomla\Database\FetchMode;
  12  use Joomla\Database\FetchOrientation;
  13  use Joomla\Database\ParameterType;
  14  use Joomla\Database\StatementInterface;
  15  
  16  /**
  17   * PDO Database Statement.
  18   *
  19   * @since  2.0.0
  20   */
  21  class PdoStatement implements StatementInterface
  22  {
  23      /**
  24       * Mapping array for fetch modes.
  25       *
  26       * @var    array
  27       * @since  2.0.0
  28       */
  29      private const FETCH_MODE_MAP = [
  30          FetchMode::ASSOCIATIVE     => \PDO::FETCH_ASSOC,
  31          FetchMode::NUMERIC         => \PDO::FETCH_NUM,
  32          FetchMode::MIXED           => \PDO::FETCH_BOTH,
  33          FetchMode::STANDARD_OBJECT => \PDO::FETCH_OBJ,
  34          FetchMode::COLUMN          => \PDO::FETCH_COLUMN,
  35          FetchMode::CUSTOM_OBJECT   => \PDO::FETCH_CLASS,
  36      ];
  37  
  38      /**
  39       * Mapping array for parameter types.
  40       *
  41       * @var    array
  42       * @since  2.0.0
  43       */
  44      private const PARAMETER_TYPE_MAP = [
  45          ParameterType::BOOLEAN      => \PDO::PARAM_BOOL,
  46          ParameterType::INTEGER      => \PDO::PARAM_INT,
  47          ParameterType::LARGE_OBJECT => \PDO::PARAM_LOB,
  48          ParameterType::NULL         => \PDO::PARAM_NULL,
  49          ParameterType::STRING       => \PDO::PARAM_STR,
  50      ];
  51  
  52      /**
  53       * The decorated PDOStatement object.
  54       *
  55       * @var    \PDOStatement
  56       * @since  2.0.0
  57       */
  58      protected $pdoStatement;
  59  
  60      /**
  61       * Statement constructor
  62       *
  63       * @param   \PDOStatement  $pdoStatement  The decorated PDOStatement object.
  64       *
  65       * @since   2.0.0
  66       */
  67  	public function __construct(\PDOStatement $pdoStatement)
  68      {
  69          $this->pdoStatement = $pdoStatement;
  70      }
  71  
  72      /**
  73       * Binds a parameter to the specified variable name.
  74       *
  75       * @param   string|integer  $parameter      Parameter identifier. For a prepared statement using named placeholders, this will be a parameter
  76       *                                          name of the form `:name`. For a prepared statement using question mark placeholders, this will be
  77       *                                          the 1-indexed position of the parameter.
  78       * @param   mixed           $variable       Name of the PHP variable to bind to the SQL statement parameter.
  79       * @param   string          $dataType       Constant corresponding to a SQL datatype, this should be the processed type from the QueryInterface.
  80       * @param   integer         $length         The length of the variable. Usually required for OUTPUT parameters.
  81       * @param   array           $driverOptions  Optional driver options to be used.
  82       *
  83       * @return  boolean
  84       *
  85       * @since   2.0.0
  86       */
  87  	public function bindParam($parameter, &$variable, string $dataType = ParameterType::STRING, ?int $length = null, ?array $driverOptions = null)
  88      {
  89          $type            = $this->convertParameterType($dataType);
  90          $extraParameters = array_slice(func_get_args(), 3);
  91  
  92          if (count($extraParameters) !== 0)
  93          {
  94              $extraParameters[0] = $extraParameters[0] ?? 0;
  95          }
  96  
  97          $this->pdoStatement->bindParam($parameter, $variable, $type, ...$extraParameters);
  98  
  99          return true;
 100      }
 101  
 102      /**
 103       * Closes the cursor, enabling the statement to be executed again.
 104       *
 105       * @return  void
 106       *
 107       * @since   2.0.0
 108       */
 109  	public function closeCursor(): void
 110      {
 111          $this->pdoStatement->closeCursor();
 112      }
 113  
 114      /**
 115       * Fetches the SQLSTATE associated with the last operation on the statement handle.
 116       *
 117       * @return  string
 118       *
 119       * @since   2.0.0
 120       */
 121  	public function errorCode()
 122      {
 123          return $this->pdoStatement->errorCode();
 124      }
 125  
 126      /**
 127       * Fetches extended error information associated with the last operation on the statement handle.
 128       *
 129       * @return  array
 130       *
 131       * @since   2.0.0
 132       */
 133  	public function errorInfo()
 134      {
 135          return $this->pdoStatement->errorInfo();
 136      }
 137  
 138      /**
 139       * Executes a prepared statement
 140       *
 141       * @param   array|null  $parameters  An array of values with as many elements as there are bound parameters in the SQL statement being executed.
 142       *
 143       * @return  boolean
 144       *
 145       * @since   2.0.0
 146       */
 147  	public function execute(?array $parameters = null)
 148      {
 149          return $this->pdoStatement->execute($parameters);
 150      }
 151  
 152      /**
 153       * Fetches the next row from a result set
 154       *
 155       * @param   integer|null  $fetchStyle         Controls how the next row will be returned to the caller. This value must be one of the
 156       *                                            FetchMode constants, defaulting to value of FetchMode::MIXED.
 157       * @param   integer       $cursorOrientation  For a StatementInterface object representing a scrollable cursor, this value determines which row
 158       *                                            will be returned to the caller. This value must be one of the FetchOrientation constants,
 159       *                                            defaulting to FetchOrientation::NEXT.
 160       * @param   integer       $cursorOffset       For a StatementInterface object representing a scrollable cursor for which the cursorOrientation
 161       *                                            parameter is set to FetchOrientation::ABS, this value specifies the absolute number of the row in
 162       *                                            the result set that shall be fetched. For a StatementInterface object representing a scrollable
 163       *                                            cursor for which the cursorOrientation parameter is set to FetchOrientation::REL, this value
 164       *                                            specifies the row to fetch relative to the cursor position before `fetch()` was called.
 165       *
 166       * @return  mixed  The return value of this function on success depends on the fetch type. In all cases, boolean false is returned on failure.
 167       *
 168       * @since   2.0.0
 169       */
 170  	public function fetch(?int $fetchStyle = null, int $cursorOrientation = FetchOrientation::NEXT, int $cursorOffset = 0)
 171      {
 172          if ($fetchStyle === null)
 173          {
 174              return $this->pdoStatement->fetch();
 175          }
 176  
 177          return $this->pdoStatement->fetch($this->convertFetchMode($fetchStyle), $cursorOrientation, $cursorOffset);
 178      }
 179  
 180      /**
 181       * Returns the number of rows affected by the last SQL statement.
 182       *
 183       * @return  integer
 184       *
 185       * @since   2.0.0
 186       */
 187  	public function rowCount(): int
 188      {
 189          return $this->pdoStatement->rowCount();
 190      }
 191  
 192      /**
 193       * Sets the fetch mode to use while iterating this statement.
 194       *
 195       * @param   integer  $fetchMode  The fetch mode, must be one of the FetchMode constants.
 196       * @param   mixed    ...$args    Optional mode-specific arguments.
 197       *
 198       * @return  void
 199       *
 200       * @since   2.0.0
 201       */
 202  	public function setFetchMode(int $fetchMode, ...$args): void
 203      {
 204          $this->pdoStatement->setFetchMode($this->convertFetchMode($fetchMode), ...$args);
 205      }
 206  
 207      /**
 208       * Converts the database API's fetch mode to a PDO fetch mode
 209       *
 210       * @param   integer  $mode  Fetch mode to convert
 211       *
 212       * @return  integer
 213       *
 214       * @since   2.0.0
 215       * @throws  \InvalidArgumentException if the fetch mode is unsupported
 216       */
 217  	private function convertFetchMode(int $mode): int
 218      {
 219          if (!isset(self::FETCH_MODE_MAP[$mode]))
 220          {
 221              throw new \InvalidArgumentException(sprintf('Unsupported fetch mode `%s`', $mode));
 222          }
 223  
 224          return self::FETCH_MODE_MAP[$mode];
 225      }
 226  
 227      /**
 228       * Converts the database API's parameter type to a PDO parameter type
 229       *
 230       * @param   string  $type  Parameter type to convert
 231       *
 232       * @return  integer
 233       *
 234       * @since   2.0.0
 235       * @throws  \InvalidArgumentException if the parameter type is unsupported
 236       */
 237  	private function convertParameterType(string $type): int
 238      {
 239          if (!isset(self::PARAMETER_TYPE_MAP[$type]))
 240          {
 241              throw new \InvalidArgumentException(sprintf('Unsupported parameter type `%s`', $type));
 242          }
 243  
 244          return self::PARAMETER_TYPE_MAP[$type];
 245      }
 246  }