vendor/doctrine/dbal/src/Statement.php line 249

  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Doctrine\DBAL\Platforms\AbstractPlatform;
  6. use Doctrine\DBAL\Types\Type;
  7. use Doctrine\Deprecations\Deprecation;
  9. use function func_num_args;
  10. use function is_string;
  12. /**
  13.  * A database abstraction-level statement that implements support for logging, DBAL mapping types, etc.
  14.  */
  15. class Statement
  16. {
  17.     /**
  18.      * The SQL statement.
  19.      *
  20.      * @var string
  21.      */
  22.     protected $sql;
  24.     /**
  25.      * The bound parameters.
  26.      *
  27.      * @var mixed[]
  28.      */
  29.     protected $params = [];
  31.     /**
  32.      * The parameter types.
  33.      *
  34.      * @var int[]|string[]
  35.      */
  36.     protected $types = [];
  38.     /**
  39.      * The underlying driver statement.
  40.      *
  41.      * @var Driver\Statement
  42.      */
  43.     protected $stmt;
  45.     /**
  46.      * The underlying database platform.
  47.      *
  48.      * @var AbstractPlatform
  49.      */
  50.     protected $platform;
  52.     /**
  53.      * The connection this statement is bound to and executed on.
  54.      *
  55.      * @var Connection
  56.      */
  57.     protected $conn;
  59.     /**
  60.      * Creates a new <tt>Statement</tt> for the given SQL and <tt>Connection</tt>.
  61.      *
  62.      * @internal The statement can be only instantiated by {@see Connection}.
  63.      *
  64.      * @param Connection       $conn      The connection for handling statement errors.
  65.      * @param Driver\Statement $statement The underlying driver-level statement.
  66.      * @param string           $sql       The SQL of the statement.
  67.      *
  68.      * @throws Exception
  69.      */
  70.     public function __construct(Connection $conn, Driver\Statement $statement, string $sql)
  71.     {
  72.         $this->conn     = $conn;
  73.         $this->stmt     = $statement;
  74.         $this->sql      = $sql;
  75.         $this->platform = $conn->getDatabasePlatform();
  76.     }
  78.     /**
  79.      * Binds a parameter value to the statement.
  80.      *
  81.      * The value can optionally be bound with a DBAL mapping type.
  82.      * If bound with a DBAL mapping type, the binding type is derived from the mapping
  83.      * type and the value undergoes the conversion routines of the mapping type before
  84.      * being bound.
  85.      *
  86.      * @param string|int $param The name or position of the parameter.
  87.      * @param mixed      $value The value of the parameter.
  88.      * @param mixed      $type  Either a PDO binding type or a DBAL mapping type name or instance.
  89.      *
  90.      * @return bool TRUE on success, FALSE on failure.
  91.      *
  92.      * @throws Exception
  93.      */
  94.     public function bindValue($param, $value, $type = ParameterType::STRING)
  95.     {
  96.         $this->params[$param] = $value;
  97.         $this->types[$param]  = $type;
  99.         $bindingType = ParameterType::STRING;
  101.         if ($type !== null) {
  102.             if (is_string($type)) {
  103.                 $type = Type::getType($type);
  104.             }
  106.             $bindingType = $type;
  108.             if ($type instanceof Type) {
  109.                 $value       = $type->convertToDatabaseValue($value, $this->platform);
  110.                 $bindingType = $type->getBindingType();
  111.             }
  112.         }
  114.         try {
  115.             return $this->stmt->bindValue($param, $value, $bindingType);
  116.         } catch (Driver\Exception $e) {
  117.             throw $this->conn->convertException($e);
  118.         }
  119.     }
  121.     /**
  122.      * Binds a parameter to a value by reference.
  123.      *
  124.      * Binding a parameter by reference does not support DBAL mapping types.
  125.      *
  126.      * @deprecated Use {@see bindValue()} instead.
  127.      *
  128.      * @param string|int $param    The name or position of the parameter.
  129.      * @param mixed      $variable The reference to the variable to bind.
  130.      * @param int        $type     The binding type.
  131.      * @param int|null   $length   Must be specified when using an OUT bind
  132.      *                             so that PHP allocates enough memory to hold the returned value.
  133.      *
  134.      * @return bool TRUE on success, FALSE on failure.
  135.      *
  136.      * @throws Exception
  137.      */
  138.     public function bindParam($param, &$variable, $type = ParameterType::STRING, $length = null)
  139.     {
  140.         Deprecation::trigger(
  141.             'doctrine/dbal',
  142.             'https://github.com/doctrine/dbal/pull/5563',
  143.             '%s is deprecated. Use bindValue() instead.',
  144.             __METHOD__,
  145.         );
  147.         $this->params[$param] = $variable;
  148.         $this->types[$param]  = $type;
  150.         try {
  151.             if (func_num_args() > 3) {
  152.                 return $this->stmt->bindParam($param, $variable, $type, $length);
  153.             }
  155.             return $this->stmt->bindParam($param, $variable, $type);
  156.         } catch (Driver\Exception $e) {
  157.             throw $this->conn->convertException($e);
  158.         }
  159.     }
  161.     /**
  162.      * Executes the statement with the currently bound parameters.
  163.      *
  164.      * @deprecated Statement::execute() is deprecated, use Statement::executeQuery() or executeStatement() instead
  165.      *
  166.      * @param mixed[]|null $params
  167.      *
  168.      * @throws Exception
  169.      */
  170.     public function execute($params = null): Result
  171.     {
  172.         Deprecation::triggerIfCalledFromOutside(
  173.             'doctrine/dbal',
  174.             'https://github.com/doctrine/dbal/pull/4580',
  175.             '%s() is deprecated, use Statement::executeQuery() or Statement::executeStatement() instead',
  176.             __METHOD__,
  177.         );
  179.         if ($params !== null) {
  180.             $this->params = $params;
  181.         }
  183.         $logger = $this->conn->getConfiguration()->getSQLLogger();
  184.         if ($logger !== null) {
  185.             $logger->startQuery($this->sql, $this->params, $this->types);
  186.         }
  188.         try {
  189.             return new Result(
  190.                 $this->stmt->execute($params),
  191.                 $this->conn,
  192.             );
  193.         } catch (Driver\Exception $ex) {
  194.             throw $this->conn->convertExceptionDuringQuery($ex, $this->sql, $this->params, $this->types);
  195.         } finally {
  196.             if ($logger !== null) {
  197.                 $logger->stopQuery();
  198.             }
  199.         }
  200.     }
  202.     /**
  203.      * Executes the statement with the currently bound parameters and return result.
  204.      *
  205.      * @param mixed[] $params
  206.      *
  207.      * @throws Exception
  208.      */
  209.     public function executeQuery(array $params = []): Result
  210.     {
  211.         if (func_num_args() > 0) {
  212.             Deprecation::trigger(
  213.                 'doctrine/dbal',
  214.                 'https://github.com/doctrine/dbal/pull/5556',
  215.                 'Passing $params to Statement::executeQuery() is deprecated. Bind parameters using'
  216.                     . ' Statement::bindParam() or Statement::bindValue() instead.',
  217.             );
  218.         }
  220.         if ($params === []) {
  221.             $params = null; // Workaround as long execute() exists and used internally.
  222.         }
  224.         return $this->execute($params);
  225.     }
  227.     /**
  228.      * Executes the statement with the currently bound parameters and return affected rows.
  229.      *
  230.      * @param mixed[] $params
  231.      *
  232.      * @throws Exception
  233.      */
  234.     public function executeStatement(array $params = []): int
  235.     {
  236.         if (func_num_args() > 0) {
  237.             Deprecation::trigger(
  238.                 'doctrine/dbal',
  239.                 'https://github.com/doctrine/dbal/pull/5556',
  240.                 'Passing $params to Statement::executeStatement() is deprecated. Bind parameters using'
  241.                     . ' Statement::bindParam() or Statement::bindValue() instead.',
  242.             );
  243.         }
  245.         if ($params === []) {
  246.             $params = null; // Workaround as long execute() exists and used internally.
  247.         }
  249.         return $this->execute($params)->rowCount();
  250.     }
  252.     /**
  253.      * Gets the wrapped driver statement.
  254.      *
  255.      * @return Driver\Statement
  256.      */
  257.     public function getWrappedStatement()
  258.     {
  259.         return $this->stmt;
  260.     }
  261. }