<?php
/**
 * Part of the Joomla Framework Database Package
 *
 * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

namespace Joomla\Database\Pdo;

use Joomla\Database\FetchMode;
use Joomla\Database\FetchOrientation;
use Joomla\Database\ParameterType;
use Joomla\Database\StatementInterface;

/**
 * PDO Database Statement.
 *
 * @since  2.0.0
 */
class PdoStatement implements StatementInterface
{
	/**
	 * Mapping array for fetch modes.
	 *
	 * @var    array
	 * @since  2.0.0
	 */
	private const FETCH_MODE_MAP = [
		FetchMode::ASSOCIATIVE     => \PDO::FETCH_ASSOC,
		FetchMode::NUMERIC         => \PDO::FETCH_NUM,
		FetchMode::MIXED           => \PDO::FETCH_BOTH,
		FetchMode::STANDARD_OBJECT => \PDO::FETCH_OBJ,
		FetchMode::COLUMN          => \PDO::FETCH_COLUMN,
		FetchMode::CUSTOM_OBJECT   => \PDO::FETCH_CLASS,
	];

	/**
	 * Mapping array for parameter types.
	 *
	 * @var    array
	 * @since  2.0.0
	 */
	private const PARAMETER_TYPE_MAP = [
		ParameterType::BOOLEAN      => \PDO::PARAM_BOOL,
		ParameterType::INTEGER      => \PDO::PARAM_INT,
		ParameterType::LARGE_OBJECT => \PDO::PARAM_LOB,
		ParameterType::NULL         => \PDO::PARAM_NULL,
		ParameterType::STRING       => \PDO::PARAM_STR,
	];

	/**
	 * The decorated PDOStatement object.
	 *
	 * @var    \PDOStatement
	 * @since  2.0.0
	 */
	protected $pdoStatement;

	/**
	 * Statement constructor
	 *
	 * @param   \PDOStatement  $pdoStatement  The decorated PDOStatement object.
	 *
	 * @since   2.0.0
	 */
	public function __construct(\PDOStatement $pdoStatement)
	{
		$this->pdoStatement = $pdoStatement;
	}

	/**
	 * Binds a parameter to the specified variable name.
	 *
	 * @param   string|integer  $parameter      Parameter identifier. For a prepared statement using named placeholders, this will be a parameter
	 *                                          name of the form `:name`. For a prepared statement using question mark placeholders, this will be
	 *                                          the 1-indexed position of the parameter.
	 * @param   mixed           $variable       Name of the PHP variable to bind to the SQL statement parameter.
	 * @param   string          $dataType       Constant corresponding to a SQL datatype, this should be the processed type from the QueryInterface.
	 * @param   integer         $length         The length of the variable. Usually required for OUTPUT parameters.
	 * @param   array           $driverOptions  Optional driver options to be used.
	 *
	 * @return  boolean
	 *
	 * @since   2.0.0
	 */
	public function bindParam($parameter, &$variable, string $dataType = ParameterType::STRING, ?int $length = null, ?array $driverOptions = null)
	{
		$type            = $this->convertParameterType($dataType);
		$extraParameters = array_slice(func_get_args(), 3);

		if (count($extraParameters) !== 0)
		{
			$extraParameters[0] = $extraParameters[0] ?? 0;
		}

		$this->pdoStatement->bindParam($parameter, $variable, $type, ...$extraParameters);

		return true;
	}

	/**
	 * Closes the cursor, enabling the statement to be executed again.
	 *
	 * @return  void
	 *
	 * @since   2.0.0
	 */
	public function closeCursor(): void
	{
		$this->pdoStatement->closeCursor();
	}

	/**
	 * Fetches the SQLSTATE associated with the last operation on the statement handle.
	 *
	 * @return  string
	 *
	 * @since   2.0.0
	 */
	public function errorCode()
	{
		return $this->pdoStatement->errorCode();
	}

	/**
	 * Fetches extended error information associated with the last operation on the statement handle.
	 *
	 * @return  array
	 *
	 * @since   2.0.0
	 */
	public function errorInfo()
	{
		return $this->pdoStatement->errorInfo();
	}

	/**
	 * Executes a prepared statement
	 *
	 * @param   array|null  $parameters  An array of values with as many elements as there are bound parameters in the SQL statement being executed.
	 *
	 * @return  boolean
	 *
	 * @since   2.0.0
	 */
	public function execute(?array $parameters = null)
	{
		return $this->pdoStatement->execute($parameters);
	}

	/**
	 * Fetches the next row from a result set
	 *
	 * @param   integer|null  $fetchStyle         Controls how the next row will be returned to the caller. This value must be one of the
	 *                                            FetchMode constants, defaulting to value of FetchMode::MIXED.
	 * @param   integer       $cursorOrientation  For a StatementInterface object representing a scrollable cursor, this value determines which row
	 *                                            will be returned to the caller. This value must be one of the FetchOrientation constants,
	 *                                            defaulting to FetchOrientation::NEXT.
	 * @param   integer       $cursorOffset       For a StatementInterface object representing a scrollable cursor for which the cursorOrientation
	 *                                            parameter is set to FetchOrientation::ABS, this value specifies the absolute number of the row in
	 *                                            the result set that shall be fetched. For a StatementInterface object representing a scrollable
	 *                                            cursor for which the cursorOrientation parameter is set to FetchOrientation::REL, this value
	 *                                            specifies the row to fetch relative to the cursor position before `fetch()` was called.
	 *
	 * @return  mixed  The return value of this function on success depends on the fetch type. In all cases, boolean false is returned on failure.
	 *
	 * @since   2.0.0
	 */
	public function fetch(?int $fetchStyle = null, int $cursorOrientation = FetchOrientation::NEXT, int $cursorOffset = 0)
	{
		if ($fetchStyle === null)
		{
			return $this->pdoStatement->fetch();
		}

		return $this->pdoStatement->fetch($this->convertFetchMode($fetchStyle), $cursorOrientation, $cursorOffset);
	}

	/**
	 * Returns the number of rows affected by the last SQL statement.
	 *
	 * @return  integer
	 *
	 * @since   2.0.0
	 */
	public function rowCount(): int
	{
		return $this->pdoStatement->rowCount();
	}

	/**
	 * Sets the fetch mode to use while iterating this statement.
	 *
	 * @param   integer  $fetchMode  The fetch mode, must be one of the FetchMode constants.
	 * @param   mixed    ...$args    Optional mode-specific arguments.
	 *
	 * @return  void
	 *
	 * @since   2.0.0
	 */
	public function setFetchMode(int $fetchMode, ...$args): void
	{
		$this->pdoStatement->setFetchMode($this->convertFetchMode($fetchMode), ...$args);
	}

	/**
	 * Converts the database API's fetch mode to a PDO fetch mode
	 *
	 * @param   integer  $mode  Fetch mode to convert
	 *
	 * @return  integer
	 *
	 * @since   2.0.0
	 * @throws  \InvalidArgumentException if the fetch mode is unsupported
	 */
	private function convertFetchMode(int $mode): int
	{
		if (!isset(self::FETCH_MODE_MAP[$mode]))
		{
			throw new \InvalidArgumentException(sprintf('Unsupported fetch mode `%s`', $mode));
		}

		return self::FETCH_MODE_MAP[$mode];
	}

	/**
	 * Converts the database API's parameter type to a PDO parameter type
	 *
	 * @param   string  $type  Parameter type to convert
	 *
	 * @return  integer
	 *
	 * @since   2.0.0
	 * @throws  \InvalidArgumentException if the parameter type is unsupported
	 */
	private function convertParameterType(string $type): int
	{
		if (!isset(self::PARAMETER_TYPE_MAP[$type]))
		{
			throw new \InvalidArgumentException(sprintf('Unsupported parameter type `%s`', $type));
		}

		return self::PARAMETER_TYPE_MAP[$type];
	}
}