StatementWrapper.php

<?php

namespace Drupal\Core\Database;

// cSpell:ignore maxlen driverdata INOUT

/**
 * Implementation of StatementInterface encapsulating PDOStatement.
 */
class StatementWrapper implements \IteratorAggregate, StatementInterface {
    
    /**
     * The Drupal database connection object.
     *
     * @var \Drupal\Core\Database\Connection
     */
    protected $connection;
    
    /**
     * The client database Statement object.
     *
     * For a \PDO client connection, this will be a \PDOStatement object.
     *
     * @var object
     */
    protected $clientStatement;
    
    /**
     * Is rowCount() execution allowed.
     *
     * @var bool
     */
    protected $rowCountEnabled = FALSE;
    
    /**
     * Constructs a StatementWrapper object.
     *
     * @param \Drupal\Core\Database\Connection $connection
     *   Drupal database connection object.
     * @param object $client_connection
     *   Client database connection object, for example \PDO.
     * @param string $query
     *   The SQL query string.
     * @param array $options
     *   Array of query options.
     * @param bool $row_count_enabled
     *   (optional) Enables counting the rows matched. Defaults to FALSE.
     */
    public function __construct(Connection $connection, $client_connection, string $query, array $options, bool $row_count_enabled = FALSE) {
        $this->connection = $connection;
        $this->clientStatement = $client_connection->prepare($query, $options);
        $this->rowCountEnabled = $row_count_enabled;
        $this->setFetchMode(\PDO::FETCH_OBJ);
    }
    
    /**
     * Implements the magic __get() method.
     *
     * @todo Remove the method before Drupal 10.
     * @see https://www.drupal.org/i/3210310
     */
    public function __get($name) {
        if ($name === 'queryString') {
            @trigger_error("StatementWrapper::\$queryString should not be accessed in drupal:9.1.0 and will error in drupal:10.0.0. Access the client-level statement object via ::getClientStatement(). See https://www.drupal.org/node/3177488", E_USER_DEPRECATED);
            return $this->getClientStatement()->queryString;
        }
        if ($name === 'dbh') {
            @trigger_error(__CLASS__ . '::$dbh should not be accessed in drupal:9.3.0 and will error in drupal:10.0.0. Use $this->connection instead. See https://www.drupal.org/node/3186368', E_USER_DEPRECATED);
            return $this->connection;
        }
        if ($name === 'allowRowCount') {
            @trigger_error(__CLASS__ . '::$allowRowCount should not be accessed in drupal:9.3.0 and will error in drupal:10.0.0. Use $this->rowCountEnabled instead. See https://www.drupal.org/node/3186368', E_USER_DEPRECATED);
            return $this->rowCountEnabled;
        }
    }
    
    /**
     * Implements the magic __set() method.
     *
     * @todo Remove the method before Drupal 10.
     * @see https://www.drupal.org/i/3210310
     */
    public function __set($name, $value) {
        if ($name === 'allowRowCount') {
            @trigger_error(__CLASS__ . '::$allowRowCount should not be written in drupal:9.3.0 and will error in drupal:10.0.0. Enable row counting by passing the appropriate argument to the constructor instead. See https://www.drupal.org/node/3186368', E_USER_DEPRECATED);
            $this->rowCountEnabled = $value;
        }
    }
    
    /**
     * Implements the magic __call() method.
     *
     * @deprecated in drupal:9.1.0 and is removed from drupal:10.0.0. Access the
     *   client-level statement object via ::getClientStatement().
     *
     * @see https://www.drupal.org/node/3177488
     */
    public function __call($method, $arguments) {
        if (is_callable([
            $this->getClientStatement(),
            $method,
        ])) {
            @trigger_error("StatementWrapper::{$method} should not be called in drupal:9.1.0 and will error in drupal:10.0.0. Access the client-level statement object via ::getClientStatement(). See https://www.drupal.org/node/3177488", E_USER_DEPRECATED);
            return call_user_func_array([
                $this->getClientStatement(),
                $method,
            ], $arguments);
        }
        throw new \BadMethodCallException($method);
    }
    
    /**
     * Returns the client-level database statement object.
     *
     * This method should normally be used only within database driver code.
     *
     * @return object
     *   The client-level database statement, for example \PDOStatement.
     */
    public function getClientStatement() {
        return $this->clientStatement;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getConnectionTarget() : string {
        return $this->connection
            ->getTarget();
    }
    
    /**
     * {@inheritdoc}
     */
    public function execute($args = [], $options = []) {
        if (isset($options['fetch'])) {
            if (is_string($options['fetch'])) {
                // \PDO::FETCH_PROPS_LATE tells __construct() to run before properties
                // are added to the object.
                $this->setFetchMode(\PDO::FETCH_CLASS | \PDO::FETCH_PROPS_LATE, $options['fetch']);
            }
            else {
                $this->setFetchMode($options['fetch']);
            }
        }
        $logger = $this->connection
            ->getLogger();
        if (!empty($logger)) {
            $query_start = microtime(TRUE);
        }
        $return = $this->clientStatement
            ->execute($args);
        if (!empty($logger)) {
            $query_end = microtime(TRUE);
            $logger->log($this, $args, $query_end - $query_start, $query_start);
        }
        return $return;
    }
    
    /**
     * {@inheritdoc}
     */
    public function getQueryString() {
        return $this->clientStatement->queryString;
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchCol($index = 0) {
        return $this->fetchAll(\PDO::FETCH_COLUMN, $index);
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchAllAssoc($key, $fetch = NULL) {
        $return = [];
        if (isset($fetch)) {
            if (is_string($fetch)) {
                $this->setFetchMode(\PDO::FETCH_CLASS, $fetch);
            }
            else {
                $this->setFetchMode($fetch);
            }
        }
        foreach ($this as $record) {
            $record_key = is_object($record) ? $record->{$key} : $record[$key];
            $return[$record_key] = $record;
        }
        return $return;
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchAllKeyed($key_index = 0, $value_index = 1) {
        $return = [];
        $this->setFetchMode(\PDO::FETCH_NUM);
        foreach ($this as $record) {
            $return[$record[$key_index]] = $record[$value_index];
        }
        return $return;
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchField($index = 0) {
        // Call \PDOStatement::fetchColumn to fetch the field.
        return $this->clientStatement
            ->fetchColumn($index);
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchAssoc() {
        // Call \PDOStatement::fetch to fetch the row.
        return $this->fetch(\PDO::FETCH_ASSOC);
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchObject(string $class_name = NULL, array $constructor_arguments = NULL) {
        if ($class_name) {
            return $this->clientStatement
                ->fetchObject($class_name, $constructor_arguments);
        }
        return $this->clientStatement
            ->fetchObject();
    }
    
    /**
     * {@inheritdoc}
     */
    public function rowCount() {
        // SELECT query should not use the method.
        if ($this->rowCountEnabled) {
            return $this->clientStatement
                ->rowCount();
        }
        else {
            throw new RowCountException();
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function setFetchMode($mode, $a1 = NULL, $a2 = []) {
        // Call \PDOStatement::setFetchMode to set fetch mode.
        // \PDOStatement is picky about the number of arguments in some cases so we
        // need to be pass the exact number of arguments we where given.
        switch (func_num_args()) {
            case 1:
                return $this->clientStatement
                    ->setFetchMode($mode);
            case 2:
                return $this->clientStatement
                    ->setFetchMode($mode, $a1);
            case 3:
            default:
                return $this->clientStatement
                    ->setFetchMode($mode, $a1, $a2);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetch($mode = NULL, $cursor_orientation = NULL, $cursor_offset = NULL) {
        // Call \PDOStatement::fetchAll to fetch all rows.
        // \PDOStatement is picky about the number of arguments in some cases so we
        // need to be pass the exact number of arguments we where given.
        switch (func_num_args()) {
            case 0:
                return $this->clientStatement
                    ->fetch();
            case 1:
                return $this->clientStatement
                    ->fetch($mode);
            case 2:
                return $this->clientStatement
                    ->fetch($mode, $cursor_orientation);
            case 3:
            default:
                return $this->clientStatement
                    ->fetch($mode, $cursor_orientation, $cursor_offset);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function fetchAll($mode = NULL, $column_index = NULL, $constructor_arguments = NULL) {
        // Call \PDOStatement::fetchAll to fetch all rows.
        // \PDOStatement is picky about the number of arguments in some cases so we
        // need to be pass the exact number of arguments we where given.
        switch (func_num_args()) {
            case 0:
                return $this->clientStatement
                    ->fetchAll();
            case 1:
                return $this->clientStatement
                    ->fetchAll($mode);
            case 2:
                return $this->clientStatement
                    ->fetchAll($mode, $column_index);
            case 3:
            default:
                return $this->clientStatement
                    ->fetchAll($mode, $column_index, $constructor_arguments);
        }
    }
    
    /**
     * {@inheritdoc}
     */
    public function getIterator() {
        return new \ArrayIterator($this->fetchAll());
    }
    
    /**
     * Bind a column to a PHP variable.
     *
     * @param mixed $column
     *   Number of the column (1-indexed) or name of the column in the result set.
     *   If using the column name, be aware that the name should match the case of
     *   the column, as returned by the driver.
     * @param mixed $param
     *   Name of the PHP variable to which the column will be bound.
     * @param int $type
     *   (Optional) data type of the parameter, specified by the PDO::PARAM_*
     *   constants.
     * @param int $maxlen
     *   (Optional) a hint for pre-allocation.
     * @param mixed $driverdata
     *   (Optional) optional parameter(s) for the driver.
     *
     * @return bool
     *   Returns TRUE on success or FALSE on failure.
     *
     * @deprecated in drupal:9.1.0 and is removed from drupal:10.0.0.
     *   StatementWrapper::bindColumn should not be called. Access the
     *   client-level statement object via ::getClientStatement().
     *
     * @see https://www.drupal.org/node/3177488
     */
    public function bindColumn($column, &$param, int $type = 0, int $maxlen = 0, $driverdata = NULL) : bool {
        @trigger_error("StatementWrapper::bindColumn should not be called in drupal:9.1.0 and will error in drupal:10.0.0. Access the client-level statement object via ::getClientStatement(). See https://www.drupal.org/node/3177488", E_USER_DEPRECATED);
        switch (func_num_args()) {
            case 2:
                return $this->clientStatement
                    ->bindColumn($column, $param);
            case 3:
                return $this->clientStatement
                    ->bindColumn($column, $param, $type);
            case 4:
                return $this->clientStatement
                    ->bindColumn($column, $param, $type, $maxlen);
            case 5:
                return $this->clientStatement
                    ->bindColumn($column, $param, $type, $maxlen, $driverdata);
        }
    }
    
    /**
     * Binds a parameter to the specified variable name.
     *
     * @param mixed $parameter
     *   Parameter identifier. For a prepared statement using named placeholders,
     *   this will be a parameter name of the form :name.
     * @param mixed $variable
     *   Name of the PHP variable to bind to the SQL statement parameter.
     * @param int $data_type
     *   (Optional) explicit data type for the parameter using the PDO::PARAM_*
     *   constants. To return an INOUT parameter from a stored procedure, use the
     *   bitwise OR operator to set the PDO::PARAM_INPUT_OUTPUT bits for the
     *   data_type parameter.
     * @param int $length
     *   (Optional) length of the data type. To indicate that a parameter is an
     *   OUT parameter from a stored procedure, you must explicitly set the
     *   length.
     * @param mixed $driver_options
     *   (Optional) Driver options.
     *
     * @return bool
     *   Returns TRUE on success or FALSE on failure.
     *
     * @deprecated in drupal:9.1.0 and is removed from drupal:10.0.0.
     *   StatementWrapper::bindParam should not be called. Access the
     *   client-level statement object via ::getClientStatement().
     *
     * @see https://www.drupal.org/node/3177488
     */
    public function bindParam($parameter, &$variable, int $data_type = \PDO::PARAM_STR, int $length = 0, $driver_options = NULL) : bool {
        @trigger_error("StatementWrapper::bindParam should not be called in drupal:9.1.0 and will error in drupal:10.0.0. Access the client-level statement object via ::getClientStatement(). See https://www.drupal.org/node/3177488", E_USER_DEPRECATED);
        switch (func_num_args()) {
            case 2:
                return $this->clientStatement
                    ->bindParam($parameter, $variable);
            case 3:
                return $this->clientStatement
                    ->bindParam($parameter, $variable, $data_type);
            case 4:
                return $this->clientStatement
                    ->bindParam($parameter, $variable, $data_type, $length);
            case 5:
                return $this->clientStatement
                    ->bindParam($parameter, $variable, $data_type, $length, $driver_options);
        }
    }

}