vendor/doctrine/dbal/lib/Doctrine/DBAL/Connection.php line 1038

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayStatement;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Cache\ResultCacheStatement;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\PDO\Statement as PDODriverStatement;
  13. use Doctrine\DBAL\Driver\PingableConnection;
  14. use Doctrine\DBAL\Driver\ResultStatement;
  15. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  16. use Doctrine\DBAL\Exception\ConnectionLost;
  17. use Doctrine\DBAL\Exception\InvalidArgumentException;
  18. use Doctrine\DBAL\Exception\NoKeyValue;
  19. use Doctrine\DBAL\Platforms\AbstractPlatform;
  20. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  21. use Doctrine\DBAL\Query\QueryBuilder;
  22. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  23. use Doctrine\DBAL\Types\Type;
  24. use Doctrine\Deprecations\Deprecation;
  25. use PDO;
  26. use Throwable;
  27. use Traversable;
  29. use function array_key_exists;
  30. use function array_shift;
  31. use function assert;
  32. use function func_get_args;
  33. use function implode;
  34. use function is_int;
  35. use function is_string;
  36. use function key;
  38. /**
  39. * A wrapper around a Doctrine\DBAL\Driver\Connection that adds features like
  40. * events, transaction isolation levels, configuration, emulated transaction nesting,
  41. * lazy connecting and more.
  42. *
  43. * @psalm-import-type Params from DriverManager
  44. * @psalm-consistent-constructor
  45. */
  46. class Connection implements DriverConnection
  47. {
  48. /**
  49. * Constant for transaction isolation level READ UNCOMMITTED.
  50. *
  51. * @deprecated Use TransactionIsolationLevel::READ_UNCOMMITTED.
  52. */
  53. public const TRANSACTION_READ_UNCOMMITTED = TransactionIsolationLevel::READ_UNCOMMITTED;
  55. /**
  56. * Constant for transaction isolation level READ COMMITTED.
  57. *
  58. * @deprecated Use TransactionIsolationLevel::READ_COMMITTED.
  59. */
  60. public const TRANSACTION_READ_COMMITTED = TransactionIsolationLevel::READ_COMMITTED;
  62. /**
  63. * Constant for transaction isolation level REPEATABLE READ.
  64. *
  65. * @deprecated Use TransactionIsolationLevel::REPEATABLE_READ.
  66. */
  67. public const TRANSACTION_REPEATABLE_READ = TransactionIsolationLevel::REPEATABLE_READ;
  69. /**
  70. * Constant for transaction isolation level SERIALIZABLE.
  71. *
  72. * @deprecated Use TransactionIsolationLevel::SERIALIZABLE.
  73. */
  74. public const TRANSACTION_SERIALIZABLE = TransactionIsolationLevel::SERIALIZABLE;
  76. /**
  77. * Represents an array of ints to be expanded by Doctrine SQL parsing.
  78. */
  79. public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  81. /**
  82. * Represents an array of strings to be expanded by Doctrine SQL parsing.
  83. */
  84. public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  86. /**
  87. * Offset by which PARAM_* constants are detected as arrays of the param type.
  88. */
  89. public const ARRAY_PARAM_OFFSET = 100;
  91. /**
  92. * The wrapped driver connection.
  93. *
  94. * @var \Doctrine\DBAL\Driver\Connection|null
  95. */
  96. protected $_conn;
  98. /** @var Configuration */
  99. protected $_config;
  101. /** @var EventManager */
  102. protected $_eventManager;
  104. /** @var ExpressionBuilder */
  105. protected $_expr;
  107. /**
  108. * The current auto-commit mode of this connection.
  109. *
  110. * @var bool
  111. */
  112. private $autoCommit = true;
  114. /**
  115. * The transaction nesting level.
  116. *
  117. * @var int
  118. */
  119. private $transactionNestingLevel = 0;
  121. /**
  122. * The currently active transaction isolation level or NULL before it has been determined.
  123. *
  124. * @var int|null
  125. */
  126. private $transactionIsolationLevel;
  128. /**
  129. * If nested transactions should use savepoints.
  130. *
  131. * @var bool
  132. */
  133. private $nestTransactionsWithSavepoints = false;
  135. /**
  136. * The parameters used during creation of the Connection instance.
  137. *
  138. * @var array<string,mixed>
  139. * @phpstan-var array<string,mixed>
  140. * @psalm-var Params
  141. */
  142. private $params;
  144. /**
  145. * The database platform object used by the connection or NULL before it's initialized.
  146. *
  147. * @var AbstractPlatform|null
  148. */
  149. private $platform;
  151. /**
  152. * The schema manager.
  153. *
  154. * @var AbstractSchemaManager|null
  155. */
  156. protected $_schemaManager;
  158. /**
  159. * The used DBAL driver.
  160. *
  161. * @var Driver
  162. */
  163. protected $_driver;
  165. /**
  166. * Flag that indicates whether the current transaction is marked for rollback only.
  167. *
  168. * @var bool
  169. */
  170. private $isRollbackOnly = false;
  172. /** @var int */
  173. protected $defaultFetchMode = FetchMode::ASSOCIATIVE;
  175. /**
  176. * Initializes a new instance of the Connection class.
  177. *
  178. * @internal The connection can be only instantiated by the driver manager.
  179. *
  180. * @param array<string,mixed> $params The connection parameters.
  181. * @param Driver $driver The driver to use.
  182. * @param Configuration|null $config The configuration, optional.
  183. * @param EventManager|null $eventManager The event manager, optional.
  184. * @psalm-param Params $params
  185. * @phpstan-param array<string,mixed> $params
  186. *
  187. * @throws Exception
  188. */
  189. public function __construct(
  190. array $params,
  191. Driver $driver,
  192. ?Configuration $config = null,
  193. ?EventManager $eventManager = null
  194. ) {
  195. $this->_driver = $driver;
  196. $this->params = $params;
  198. if (isset($params['pdo'])) {
  199. Deprecation::trigger(
  200. 'doctrine/dbal',
  201. 'https://github.com/doctrine/dbal/pull/3554',
  202. 'Passing a user provided PDO instance directly to Doctrine is deprecated.'
  203. );
  205. if (! $params['pdo'] instanceof PDO) {
  206. throw Exception::invalidPdoInstance();
  207. }
  209. $this->_conn = $params['pdo'];
  210. $this->_conn->setAttribute(PDO::ATTR_STATEMENT_CLASS, [PDODriverStatement::class, []]);
  211. unset($this->params['pdo']);
  212. }
  214. if (isset($params['platform'])) {
  215. if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  216. throw Exception::invalidPlatformType($params['platform']);
  217. }
  219. $this->platform = $params['platform'];
  220. }
  222. // Create default config and event manager if none given
  223. if (! $config) {
  224. $config = new Configuration();
  225. }
  227. if (! $eventManager) {
  228. $eventManager = new EventManager();
  229. }
  231. $this->_config = $config;
  232. $this->_eventManager = $eventManager;
  234. $this->_expr = new Query\Expression\ExpressionBuilder($this);
  236. $this->autoCommit = $config->getAutoCommit();
  237. }
  239. /**
  240. * Gets the parameters used during instantiation.
  241. *
  242. * @internal
  243. *
  244. * @return array<string,mixed>
  245. * @psalm-return Params
  246. * @phpstan-return array<string,mixed>
  247. */
  248. public function getParams()
  249. {
  250. return $this->params;
  251. }
  253. /**
  254. * Gets the name of the database this Connection is connected to.
  255. *
  256. * @return string
  257. */
  258. public function getDatabase()
  259. {
  260. return $this->_driver->getDatabase($this);
  261. }
  263. /**
  264. * Gets the hostname of the currently connected database.
  265. *
  266. * @deprecated
  267. *
  268. * @return string|null
  269. */
  270. public function getHost()
  271. {
  272. Deprecation::trigger(
  273. 'doctrine/dbal',
  274. 'https://github.com/doctrine/dbal/issues/3580',
  275. 'Connection::getHost() is deprecated, get the database server host from application config ' .
  276. 'or as a last resort from internal Connection::getParams() API.'
  277. );
  279. return $this->params['host'] ?? null;
  280. }
  282. /**
  283. * Gets the port of the currently connected database.
  284. *
  285. * @deprecated
  286. *
  287. * @return mixed
  288. */
  289. public function getPort()
  290. {
  291. Deprecation::trigger(
  292. 'doctrine/dbal',
  293. 'https://github.com/doctrine/dbal/issues/3580',
  294. 'Connection::getPort() is deprecated, get the database server port from application config ' .
  295. 'or as a last resort from internal Connection::getParams() API.'
  296. );
  298. return $this->params['port'] ?? null;
  299. }
  301. /**
  302. * Gets the username used by this connection.
  303. *
  304. * @deprecated
  305. *
  306. * @return string|null
  307. */
  308. public function getUsername()
  309. {
  310. Deprecation::trigger(
  311. 'doctrine/dbal',
  312. 'https://github.com/doctrine/dbal/issues/3580',
  313. 'Connection::getUsername() is deprecated, get the username from application config ' .
  314. 'or as a last resort from internal Connection::getParams() API.'
  315. );
  317. return $this->params['user'] ?? null;
  318. }
  320. /**
  321. * Gets the password used by this connection.
  322. *
  323. * @deprecated
  324. *
  325. * @return string|null
  326. */
  327. public function getPassword()
  328. {
  329. Deprecation::trigger(
  330. 'doctrine/dbal',
  331. 'https://github.com/doctrine/dbal/issues/3580',
  332. 'Connection::getPassword() is deprecated, get the password from application config ' .
  333. 'or as a last resort from internal Connection::getParams() API.'
  334. );
  336. return $this->params['password'] ?? null;
  337. }
  339. /**
  340. * Gets the DBAL driver instance.
  341. *
  342. * @return Driver
  343. */
  344. public function getDriver()
  345. {
  346. return $this->_driver;
  347. }
  349. /**
  350. * Gets the Configuration used by the Connection.
  351. *
  352. * @return Configuration
  353. */
  354. public function getConfiguration()
  355. {
  356. return $this->_config;
  357. }
  359. /**
  360. * Gets the EventManager used by the Connection.
  361. *
  362. * @return EventManager
  363. */
  364. public function getEventManager()
  365. {
  366. return $this->_eventManager;
  367. }
  369. /**
  370. * Gets the DatabasePlatform for the connection.
  371. *
  372. * @return AbstractPlatform
  373. *
  374. * @throws Exception
  375. */
  376. public function getDatabasePlatform()
  377. {
  378. if ($this->platform === null) {
  379. $this->platform = $this->detectDatabasePlatform();
  380. $this->platform->setEventManager($this->_eventManager);
  381. }
  383. return $this->platform;
  384. }
  386. /**
  387. * Gets the ExpressionBuilder for the connection.
  388. *
  389. * @return ExpressionBuilder
  390. */
  391. public function getExpressionBuilder()
  392. {
  393. return $this->_expr;
  394. }
  396. /**
  397. * Establishes the connection with the database.
  398. *
  399. * @return bool TRUE if the connection was successfully established, FALSE if
  400. * the connection is already open.
  401. */
  402. public function connect()
  403. {
  404. if ($this->_conn !== null) {
  405. return false;
  406. }
  408. $driverOptions = $this->params['driverOptions'] ?? [];
  409. $user = $this->params['user'] ?? null;
  410. $password = $this->params['password'] ?? null;
  412. $this->_conn = $this->_driver->connect($this->params, $user, $password, $driverOptions);
  414. $this->transactionNestingLevel = 0;
  416. if ($this->autoCommit === false) {
  417. $this->beginTransaction();
  418. }
  420. if ($this->_eventManager->hasListeners(Events::postConnect)) {
  421. $eventArgs = new Event\ConnectionEventArgs($this);
  422. $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  423. }
  425. return true;
  426. }
  428. /**
  429. * Detects and sets the database platform.
  430. *
  431. * Evaluates custom platform class and version in order to set the correct platform.
  432. *
  433. * @throws Exception If an invalid platform was specified for this connection.
  434. */
  435. private function detectDatabasePlatform(): AbstractPlatform
  436. {
  437. $version = $this->getDatabasePlatformVersion();
  439. if ($version !== null) {
  440. assert($this->_driver instanceof VersionAwarePlatformDriver);
  442. return $this->_driver->createDatabasePlatformForVersion($version);
  443. }
  445. return $this->_driver->getDatabasePlatform();
  446. }
  448. /**
  449. * Returns the version of the related platform if applicable.
  450. *
  451. * Returns null if either the driver is not capable to create version
  452. * specific platform instances, no explicit server version was specified
  453. * or the underlying driver connection cannot determine the platform
  454. * version without having to query it (performance reasons).
  455. *
  456. * @return string|null
  457. *
  458. * @throws Throwable
  459. */
  460. private function getDatabasePlatformVersion()
  461. {
  462. // Driver does not support version specific platforms.
  463. if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  464. return null;
  465. }
  467. // Explicit platform version requested (supersedes auto-detection).
  468. if (isset($this->params['serverVersion'])) {
  469. return $this->params['serverVersion'];
  470. }
  472. // If not connected, we need to connect now to determine the platform version.
  473. if ($this->_conn === null) {
  474. try {
  475. $this->connect();
  476. } catch (Throwable $originalException) {
  477. if (empty($this->params['dbname'])) {
  478. throw $originalException;
  479. }
  481. // The database to connect to might not yet exist.
  482. // Retry detection without database name connection parameter.
  483. $params = $this->params;
  485. unset($this->params['dbname']);
  487. try {
  488. $this->connect();
  489. } catch (Throwable $fallbackException) {
  490. // Either the platform does not support database-less connections
  491. // or something else went wrong.
  492. throw $originalException;
  493. } finally {
  494. $this->params = $params;
  495. }
  497. $serverVersion = $this->getServerVersion();
  499. // Close "temporary" connection to allow connecting to the real database again.
  500. $this->close();
  502. return $serverVersion;
  503. }
  504. }
  506. return $this->getServerVersion();
  507. }
  509. /**
  510. * Returns the database server version if the underlying driver supports it.
  511. *
  512. * @return string|null
  513. */
  514. private function getServerVersion()
  515. {
  516. $connection = $this->getWrappedConnection();
  518. // Automatic platform version detection.
  519. if ($connection instanceof ServerInfoAwareConnection && ! $connection->requiresQueryForServerVersion()) {
  520. return $connection->getServerVersion();
  521. }
  523. // Unable to detect platform version.
  524. return null;
  525. }
  527. /**
  528. * Returns the current auto-commit mode for this connection.
  529. *
  530. * @see setAutoCommit
  531. *
  532. * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  533. */
  534. public function isAutoCommit()
  535. {
  536. return $this->autoCommit === true;
  537. }
  539. /**
  540. * Sets auto-commit mode for this connection.
  541. *
  542. * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  543. * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  544. * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  545. *
  546. * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  547. * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  548. *
  549. * @see isAutoCommit
  550. *
  551. * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  552. *
  553. * @return void
  554. */
  555. public function setAutoCommit($autoCommit)
  556. {
  557. $autoCommit = (bool) $autoCommit;
  559. // Mode not changed, no-op.
  560. if ($autoCommit === $this->autoCommit) {
  561. return;
  562. }
  564. $this->autoCommit = $autoCommit;
  566. // Commit all currently active transactions if any when switching auto-commit mode.
  567. if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  568. return;
  569. }
  571. $this->commitAll();
  572. }
  574. /**
  575. * Sets the fetch mode.
  576. *
  577. * @deprecated Use one of the fetch- or iterate-related methods.
  578. *
  579. * @param int $fetchMode
  580. *
  581. * @return void
  582. */
  583. public function setFetchMode($fetchMode)
  584. {
  585. Deprecation::trigger(
  586. 'doctrine/dbal',
  587. 'https://github.com/doctrine/dbal/pull/4019',
  588. 'Default Fetch Mode configuration is deprecated, use explicit Connection::fetch*() APIs instead.'
  589. );
  591. $this->defaultFetchMode = $fetchMode;
  592. }
  594. /**
  595. * Prepares and executes an SQL query and returns the first row of the result
  596. * as an associative array.
  597. *
  598. * @deprecated Use fetchAssociative()
  599. *
  600. * @param string $sql SQL query
  601. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  602. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  603. *
  604. * @return array<string, mixed>|false False is returned if no rows are found.
  605. *
  606. * @throws Exception
  607. */
  608. public function fetchAssoc($sql, array $params = [], array $types = [])
  609. {
  610. Deprecation::trigger(
  611. 'doctrine/dbal',
  612. 'https://github.com/doctrine/dbal/pull/4019',
  613. 'Connection::fetchAssoc() is deprecated, use Connection::fetchAssociative() API instead.'
  614. );
  616. return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::ASSOCIATIVE);
  617. }
  619. /**
  620. * Prepares and executes an SQL query and returns the first row of the result
  621. * as a numerically indexed array.
  622. *
  623. * @deprecated Use fetchNumeric()
  624. *
  625. * @param string $sql SQL query
  626. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  627. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  628. *
  629. * @return array<int, mixed>|false False is returned if no rows are found.
  630. */
  631. public function fetchArray($sql, array $params = [], array $types = [])
  632. {
  633. Deprecation::trigger(
  634. 'doctrine/dbal',
  635. 'https://github.com/doctrine/dbal/pull/4019',
  636. 'Connection::fetchArray() is deprecated, use Connection::fetchNumeric() API instead.'
  637. );
  639. return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::NUMERIC);
  640. }
  642. /**
  643. * Prepares and executes an SQL query and returns the value of a single column
  644. * of the first row of the result.
  645. *
  646. * @deprecated Use fetchOne() instead.
  647. *
  648. * @param string $sql SQL query
  649. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  650. * @param int $column 0-indexed column number
  651. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  652. *
  653. * @return mixed|false False is returned if no rows are found.
  654. *
  655. * @throws Exception
  656. */
  657. public function fetchColumn($sql, array $params = [], $column = 0, array $types = [])
  658. {
  659. Deprecation::trigger(
  660. 'doctrine/dbal',
  661. 'https://github.com/doctrine/dbal/pull/4019',
  662. 'Connection::fetchColumn() is deprecated, use Connection::fetchOne() API instead.'
  663. );
  665. return $this->executeQuery($sql, $params, $types)->fetchColumn($column);
  666. }
  668. /**
  669. * Prepares and executes an SQL query and returns the first row of the result
  670. * as an associative array.
  671. *
  672. * @param string $query SQL query
  673. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  674. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  675. *
  676. * @return array<string, mixed>|false False is returned if no rows are found.
  677. *
  678. * @throws Exception
  679. */
  680. public function fetchAssociative(string $query, array $params = [], array $types = [])
  681. {
  682. try {
  683. $stmt = $this->ensureForwardCompatibilityStatement(
  684. $this->executeQuery($query, $params, $types)
  685. );
  687. return $stmt->fetchAssociative();
  688. } catch (Throwable $e) {
  689. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  690. }
  691. }
  693. /**
  694. * Prepares and executes an SQL query and returns the first row of the result
  695. * as a numerically indexed array.
  696. *
  697. * @param string $query SQL query
  698. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  699. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  700. *
  701. * @return array<int, mixed>|false False is returned if no rows are found.
  702. *
  703. * @throws Exception
  704. */
  705. public function fetchNumeric(string $query, array $params = [], array $types = [])
  706. {
  707. try {
  708. $stmt = $this->ensureForwardCompatibilityStatement(
  709. $this->executeQuery($query, $params, $types)
  710. );
  712. return $stmt->fetchNumeric();
  713. } catch (Throwable $e) {
  714. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  715. }
  716. }
  718. /**
  719. * Prepares and executes an SQL query and returns the value of a single column
  720. * of the first row of the result.
  721. *
  722. * @param string $query SQL query
  723. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  724. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  725. *
  726. * @return mixed|false False is returned if no rows are found.
  727. *
  728. * @throws Exception
  729. */
  730. public function fetchOne(string $query, array $params = [], array $types = [])
  731. {
  732. try {
  733. $stmt = $this->ensureForwardCompatibilityStatement(
  734. $this->executeQuery($query, $params, $types)
  735. );
  737. return $stmt->fetchOne();
  738. } catch (Throwable $e) {
  739. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  740. }
  741. }
  743. /**
  744. * Whether an actual connection to the database is established.
  745. *
  746. * @return bool
  747. */
  748. public function isConnected()
  749. {
  750. return $this->_conn !== null;
  751. }
  753. /**
  754. * Checks whether a transaction is currently active.
  755. *
  756. * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  757. */
  758. public function isTransactionActive()
  759. {
  760. return $this->transactionNestingLevel > 0;
  761. }
  763. /**
  764. * Adds condition based on the criteria to the query components
  765. *
  766. * @param array<string,mixed> $criteria Map of key columns to their values
  767. * @param string[] $columns Column names
  768. * @param mixed[] $values Column values
  769. * @param string[] $conditions Key conditions
  770. *
  771. * @throws Exception
  772. */
  773. private function addCriteriaCondition(
  774. array $criteria,
  775. array &$columns,
  776. array &$values,
  777. array &$conditions
  778. ): void {
  779. $platform = $this->getDatabasePlatform();
  781. foreach ($criteria as $columnName => $value) {
  782. if ($value === null) {
  783. $conditions[] = $platform->getIsNullExpression($columnName);
  784. continue;
  785. }
  787. $columns[] = $columnName;
  788. $values[] = $value;
  789. $conditions[] = $columnName . ' = ?';
  790. }
  791. }
  793. /**
  794. * Executes an SQL DELETE statement on a table.
  795. *
  796. * Table expression and columns are not escaped and are not safe for user-input.
  797. *
  798. * @param string $table Table name
  799. * @param array<string, mixed> $criteria Deletion criteria
  800. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  801. *
  802. * @return int|string The number of affected rows.
  803. *
  804. * @throws Exception
  805. */
  806. public function delete($table, array $criteria, array $types = [])
  807. {
  808. if (empty($criteria)) {
  809. throw InvalidArgumentException::fromEmptyCriteria();
  810. }
  812. $columns = $values = $conditions = [];
  814. $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  816. return $this->executeStatement(
  817. 'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  818. $values,
  819. is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  820. );
  821. }
  823. /**
  824. * Closes the connection.
  825. *
  826. * @return void
  827. */
  828. public function close()
  829. {
  830. $this->_conn = null;
  831. }
  833. /**
  834. * Sets the transaction isolation level.
  835. *
  836. * @param int $level The level to set.
  837. *
  838. * @return int|string
  839. */
  840. public function setTransactionIsolation($level)
  841. {
  842. $this->transactionIsolationLevel = $level;
  844. return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  845. }
  847. /**
  848. * Gets the currently active transaction isolation level.
  849. *
  850. * @return int The current transaction isolation level.
  851. */
  852. public function getTransactionIsolation()
  853. {
  854. if ($this->transactionIsolationLevel === null) {
  855. $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  856. }
  858. return $this->transactionIsolationLevel;
  859. }
  861. /**
  862. * Executes an SQL UPDATE statement on a table.
  863. *
  864. * Table expression and columns are not escaped and are not safe for user-input.
  865. *
  866. * @param string $table Table name
  867. * @param array<string, mixed> $data Column-value pairs
  868. * @param array<string, mixed> $criteria Update criteria
  869. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  870. *
  871. * @return int|string The number of affected rows.
  872. *
  873. * @throws Exception
  874. */
  875. public function update($table, array $data, array $criteria, array $types = [])
  876. {
  877. $columns = $values = $conditions = $set = [];
  879. foreach ($data as $columnName => $value) {
  880. $columns[] = $columnName;
  881. $values[] = $value;
  882. $set[] = $columnName . ' = ?';
  883. }
  885. $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  887. if (is_string(key($types))) {
  888. $types = $this->extractTypeValues($columns, $types);
  889. }
  891. $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  892. . ' WHERE ' . implode(' AND ', $conditions);
  894. return $this->executeStatement($sql, $values, $types);
  895. }
  897. /**
  898. * Inserts a table row with specified data.
  899. *
  900. * Table expression and columns are not escaped and are not safe for user-input.
  901. *
  902. * @param string $table Table name
  903. * @param array<string, mixed> $data Column-value pairs
  904. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  905. *
  906. * @return int|string The number of affected rows.
  907. *
  908. * @throws Exception
  909. */
  910. public function insert($table, array $data, array $types = [])
  911. {
  912. if (empty($data)) {
  913. return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  914. }
  916. $columns = [];
  917. $values = [];
  918. $set = [];
  920. foreach ($data as $columnName => $value) {
  921. $columns[] = $columnName;
  922. $values[] = $value;
  923. $set[] = '?';
  924. }
  926. return $this->executeStatement(
  927. 'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  928. ' VALUES (' . implode(', ', $set) . ')',
  929. $values,
  930. is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  931. );
  932. }
  934. /**
  935. * Extract ordered type list from an ordered column list and type map.
  936. *
  937. * @param array<int, string> $columnList
  938. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  939. *
  940. * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  941. */
  942. private function extractTypeValues(array $columnList, array $types)
  943. {
  944. $typeValues = [];
  946. foreach ($columnList as $columnIndex => $columnName) {
  947. $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  948. }
  950. return $typeValues;
  951. }
  953. /**
  954. * Quotes a string so it can be safely used as a table or column name, even if
  955. * it is a reserved name.
  956. *
  957. * Delimiting style depends on the underlying database platform that is being used.
  958. *
  959. * NOTE: Just because you CAN use quoted identifiers does not mean
  960. * you SHOULD use them. In general, they end up causing way more
  961. * problems than they solve.
  962. *
  963. * @param string $str The name to be quoted.
  964. *
  965. * @return string The quoted name.
  966. */
  967. public function quoteIdentifier($str)
  968. {
  969. return $this->getDatabasePlatform()->quoteIdentifier($str);
  970. }
  972. /**
  973. * {@inheritDoc}
  974. *
  975. * @param mixed $value
  976. * @param int|string|Type|null $type
  977. */
  978. public function quote($value, $type = ParameterType::STRING)
  979. {
  980. $connection = $this->getWrappedConnection();
  982. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  984. return $connection->quote($value, $bindingType);
  985. }
  987. /**
  988. * Prepares and executes an SQL query and returns the result as an associative array.
  989. *
  990. * @deprecated Use fetchAllAssociative()
  991. *
  992. * @param string $sql The SQL query.
  993. * @param mixed[] $params The query parameters.
  994. * @param int[]|string[] $types The query parameter types.
  995. *
  996. * @return mixed[]
  997. */
  998. public function fetchAll($sql, array $params = [], $types = [])
  999. {
  1000. return $this->executeQuery($sql, $params, $types)->fetchAll();
  1001. }
  1003. /**
  1004. * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  1005. *
  1006. * @param string $query SQL query
  1007. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1008. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1009. *
  1010. * @return array<int,array<int,mixed>>
  1011. *
  1012. * @throws Exception
  1013. */
  1014. public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  1015. {
  1016. try {
  1017. $stmt = $this->ensureForwardCompatibilityStatement(
  1018. $this->executeQuery($query, $params, $types)
  1019. );
  1021. return $stmt->fetchAllNumeric();
  1022. } catch (Throwable $e) {
  1023. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1024. }
  1025. }
  1027. /**
  1028. * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  1029. *
  1030. * @param string $query SQL query
  1031. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1032. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1033. *
  1034. * @return array<int,array<string,mixed>>
  1035. *
  1036. * @throws Exception
  1037. */
  1038. public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  1039. {
  1040. try {
  1041. $stmt = $this->ensureForwardCompatibilityStatement(
  1042. $this->executeQuery($query, $params, $types)
  1043. );
  1045. return $stmt->fetchAllAssociative();
  1046. } catch (Throwable $e) {
  1047. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1048. }
  1049. }
  1051. /**
  1052. * Prepares and executes an SQL query and returns the result as an associative array with the keys
  1053. * mapped to the first column and the values mapped to the second column.
  1054. *
  1055. * @param string $query SQL query
  1056. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1057. * @param array<int, int|string>|array<string, int|string> $types Parameter types
  1058. *
  1059. * @return array<mixed,mixed>
  1060. *
  1061. * @throws Exception
  1062. */
  1063. public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  1064. {
  1065. $stmt = $this->executeQuery($query, $params, $types);
  1067. $this->ensureHasKeyValue($stmt);
  1069. $data = [];
  1071. foreach ($stmt->fetchAll(FetchMode::NUMERIC) as [$key, $value]) {
  1072. $data[$key] = $value;
  1073. }
  1075. return $data;
  1076. }
  1078. /**
  1079. * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  1080. * to the first column and the values being an associative array representing the rest of the columns
  1081. * and their values.
  1082. *
  1083. * @param string $query SQL query
  1084. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1085. * @param array<int, int|string>|array<string, int|string> $types Parameter types
  1086. *
  1087. * @return array<mixed,array<string,mixed>>
  1088. *
  1089. * @throws Exception
  1090. */
  1091. public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  1092. {
  1093. $stmt = $this->executeQuery($query, $params, $types);
  1095. $data = [];
  1097. foreach ($stmt->fetchAll(FetchMode::ASSOCIATIVE) as $row) {
  1098. $data[array_shift($row)] = $row;
  1099. }
  1101. return $data;
  1102. }
  1104. /**
  1105. * Prepares and executes an SQL query and returns the result as an array of the first column values.
  1106. *
  1107. * @param string $query SQL query
  1108. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1109. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1110. *
  1111. * @return array<int,mixed>
  1112. *
  1113. * @throws Exception
  1114. */
  1115. public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  1116. {
  1117. try {
  1118. $stmt = $this->ensureForwardCompatibilityStatement(
  1119. $this->executeQuery($query, $params, $types)
  1120. );
  1122. return $stmt->fetchFirstColumn();
  1123. } catch (Throwable $e) {
  1124. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1125. }
  1126. }
  1128. /**
  1129. * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  1130. *
  1131. * @param string $query SQL query
  1132. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1133. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1134. *
  1135. * @return Traversable<int,array<int,mixed>>
  1136. *
  1137. * @throws Exception
  1138. */
  1139. public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  1140. {
  1141. try {
  1142. $stmt = $this->ensureForwardCompatibilityStatement(
  1143. $this->executeQuery($query, $params, $types)
  1144. );
  1146. yield from $stmt->iterateNumeric();
  1147. } catch (Throwable $e) {
  1148. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1149. }
  1150. }
  1152. /**
  1153. * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  1154. * as associative arrays.
  1155. *
  1156. * @param string $query SQL query
  1157. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1158. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1159. *
  1160. * @return Traversable<int,array<string,mixed>>
  1161. *
  1162. * @throws Exception
  1163. */
  1164. public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  1165. {
  1166. try {
  1167. $stmt = $this->ensureForwardCompatibilityStatement(
  1168. $this->executeQuery($query, $params, $types)
  1169. );
  1171. yield from $stmt->iterateAssociative();
  1172. } catch (Throwable $e) {
  1173. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1174. }
  1175. }
  1177. /**
  1178. * Prepares and executes an SQL query and returns the result as an iterator with the keys
  1179. * mapped to the first column and the values mapped to the second column.
  1180. *
  1181. * @param string $query SQL query
  1182. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1183. * @param array<int, int|string>|array<string, int|string> $types Parameter types
  1184. *
  1185. * @return Traversable<mixed,mixed>
  1186. *
  1187. * @throws Exception
  1188. */
  1189. public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  1190. {
  1191. $stmt = $this->executeQuery($query, $params, $types);
  1193. $this->ensureHasKeyValue($stmt);
  1195. while (($row = $stmt->fetch(FetchMode::NUMERIC)) !== false) {
  1196. yield $row[0] => $row[1];
  1197. }
  1198. }
  1200. /**
  1201. * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  1202. * to the first column and the values being an associative array representing the rest of the columns
  1203. * and their values.
  1204. *
  1205. * @param string $query SQL query
  1206. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1207. * @param array<int, int|string>|array<string, int|string> $types Parameter types
  1208. *
  1209. * @return Traversable<mixed,array<string,mixed>>
  1210. *
  1211. * @throws Exception
  1212. */
  1213. public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  1214. {
  1215. $stmt = $this->executeQuery($query, $params, $types);
  1217. while (($row = $stmt->fetch(FetchMode::ASSOCIATIVE)) !== false) {
  1218. yield array_shift($row) => $row;
  1219. }
  1220. }
  1222. /**
  1223. * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  1224. *
  1225. * @param string $query SQL query
  1226. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1227. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1228. *
  1229. * @return Traversable<int,mixed>
  1230. *
  1231. * @throws Exception
  1232. */
  1233. public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1234. {
  1235. try {
  1236. $stmt = $this->ensureForwardCompatibilityStatement(
  1237. $this->executeQuery($query, $params, $types)
  1238. );
  1240. yield from $stmt->iterateColumn();
  1241. } catch (Throwable $e) {
  1242. $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1243. }
  1244. }
  1246. /**
  1247. * Prepares an SQL statement.
  1248. *
  1249. * @param string $sql The SQL statement to prepare.
  1250. *
  1251. * @return Statement The prepared statement.
  1252. *
  1253. * @throws Exception
  1254. */
  1255. public function prepare($sql)
  1256. {
  1257. try {
  1258. $stmt = new Statement($sql, $this);
  1259. } catch (Throwable $e) {
  1260. $this->handleExceptionDuringQuery($e, $sql);
  1261. }
  1263. $stmt->setFetchMode($this->defaultFetchMode);
  1265. return $stmt;
  1266. }
  1268. /**
  1269. * Executes an, optionally parametrized, SQL query.
  1270. *
  1271. * If the query is parametrized, a prepared statement is used.
  1272. * If an SQLLogger is configured, the execution is logged.
  1273. *
  1274. * @param string $sql SQL query
  1275. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1276. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1277. *
  1278. * @return ForwardCompatibility\DriverStatement|ForwardCompatibility\DriverResultStatement
  1279. *
  1280. * The executed statement or the cached result statement if a query cache profile is used
  1281. *
  1282. * @throws Exception
  1283. */
  1284. public function executeQuery($sql, array $params = [], $types = [], ?QueryCacheProfile $qcp = null)
  1285. {
  1286. if ($qcp !== null) {
  1287. return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1288. }
  1290. $connection = $this->getWrappedConnection();
  1292. $logger = $this->_config->getSQLLogger();
  1293. if ($logger) {
  1294. $logger->startQuery($sql, $params, $types);
  1295. }
  1297. try {
  1298. if ($params) {
  1299. [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1301. $stmt = $connection->prepare($sql);
  1302. if ($types) {
  1303. $this->_bindTypedValues($stmt, $params, $types);
  1304. $stmt->execute();
  1305. } else {
  1306. $stmt->execute($params);
  1307. }
  1308. } else {
  1309. $stmt = $connection->query($sql);
  1310. }
  1311. } catch (Throwable $e) {
  1312. $this->handleExceptionDuringQuery(
  1313. $e,
  1314. $sql,
  1315. $params,
  1316. $types
  1317. );
  1318. }
  1320. $stmt->setFetchMode($this->defaultFetchMode);
  1322. if ($logger) {
  1323. $logger->stopQuery();
  1324. }
  1326. return $this->ensureForwardCompatibilityStatement($stmt);
  1327. }
  1329. /**
  1330. * Executes a caching query.
  1331. *
  1332. * @param string $sql SQL query
  1333. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  1334. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1335. *
  1336. * @return ForwardCompatibility\DriverResultStatement
  1337. *
  1338. * @throws CacheException
  1339. */
  1340. public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp)
  1341. {
  1342. $resultCache = $qcp->getResultCacheDriver() ?? $this->_config->getResultCacheImpl();
  1344. if ($resultCache === null) {
  1345. throw CacheException::noResultDriverConfigured();
  1346. }
  1348. $connectionParams = $this->params;
  1349. unset($connectionParams['platform']);
  1351. [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1353. // fetch the row pointers entry
  1354. $data = $resultCache->fetch($cacheKey);
  1356. if ($data !== false) {
  1357. // is the real key part of this row pointers map or is the cache only pointing to other cache keys?
  1358. if (isset($data[$realKey])) {
  1359. $stmt = new ArrayStatement($data[$realKey]);
  1360. } elseif (array_key_exists($realKey, $data)) {
  1361. $stmt = new ArrayStatement([]);
  1362. }
  1363. }
  1365. if (! isset($stmt)) {
  1366. $stmt = new ResultCacheStatement(
  1367. $this->executeQuery($sql, $params, $types),
  1368. $resultCache,
  1369. $cacheKey,
  1370. $realKey,
  1371. $qcp->getLifetime()
  1372. );
  1373. }
  1375. $stmt->setFetchMode($this->defaultFetchMode);
  1377. return $this->ensureForwardCompatibilityStatement($stmt);
  1378. }
  1380. /**
  1381. * @return ForwardCompatibility\Result
  1382. */
  1383. private function ensureForwardCompatibilityStatement(ResultStatement $stmt)
  1384. {
  1385. return ForwardCompatibility\Result::ensure($stmt);
  1386. }
  1388. /**
  1389. * Executes an, optionally parametrized, SQL query and returns the result,
  1390. * applying a given projection/transformation function on each row of the result.
  1391. *
  1392. * @deprecated
  1393. *
  1394. * @param string $sql The SQL query to execute.
  1395. * @param mixed[] $params The parameters, if any.
  1396. * @param Closure $function The transformation function that is applied on each row.
  1397. * The function receives a single parameter, an array, that
  1398. * represents a row of the result set.
  1399. *
  1400. * @return mixed[] The projected result of the query.
  1401. */
  1402. public function project($sql, array $params, Closure $function)
  1403. {
  1404. Deprecation::trigger(
  1405. 'doctrine/dbal',
  1406. 'https://github.com/doctrine/dbal/pull/3823',
  1407. 'Connection::project() is deprecated without replacement, implement data projections in your own code.'
  1408. );
  1410. $result = [];
  1411. $stmt = $this->executeQuery($sql, $params);
  1413. while ($row = $stmt->fetch()) {
  1414. $result[] = $function($row);
  1415. }
  1417. $stmt->closeCursor();
  1419. return $result;
  1420. }
  1422. /**
  1423. * Executes an SQL statement, returning a result set as a Statement object.
  1424. *
  1425. * @deprecated Use {@link executeQuery()} instead.
  1426. *
  1427. * @return \Doctrine\DBAL\Driver\Statement
  1428. *
  1429. * @throws Exception
  1430. */
  1431. public function query()
  1432. {
  1433. Deprecation::trigger(
  1434. 'doctrine/dbal',
  1435. 'https://github.com/doctrine/dbal/pull/4163',
  1436. 'Connection::query() is deprecated, use Connection::executeQuery() instead.'
  1437. );
  1439. $connection = $this->getWrappedConnection();
  1441. $args = func_get_args();
  1443. $logger = $this->_config->getSQLLogger();
  1444. if ($logger) {
  1445. $logger->startQuery($args[0]);
  1446. }
  1448. try {
  1449. $statement = $connection->query(...$args);
  1450. } catch (Throwable $e) {
  1451. $this->handleExceptionDuringQuery($e, $args[0]);
  1452. }
  1454. $statement->setFetchMode($this->defaultFetchMode);
  1456. if ($logger) {
  1457. $logger->stopQuery();
  1458. }
  1460. return $statement;
  1461. }
  1463. /**
  1464. * Executes an SQL INSERT/UPDATE/DELETE query with the given parameters
  1465. * and returns the number of affected rows.
  1466. *
  1467. * This method supports PDO binding types as well as DBAL mapping types.
  1468. *
  1469. * @deprecated Use {@link executeStatement()} instead.
  1470. *
  1471. * @param string $sql SQL statement
  1472. * @param array<int, mixed>|array<string, mixed> $params Statement parameters
  1473. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1474. *
  1475. * @return int|string The number of affected rows.
  1476. *
  1477. * @throws Exception
  1478. */
  1479. public function executeUpdate($sql, array $params = [], array $types = [])
  1480. {
  1481. Deprecation::trigger(
  1482. 'doctrine/dbal',
  1483. 'https://github.com/doctrine/dbal/pull/4163',
  1484. 'Connection::executeUpdate() is deprecated, use Connection::executeStatement() instead.'
  1485. );
  1487. return $this->executeStatement($sql, $params, $types);
  1488. }
  1490. /**
  1491. * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1492. *
  1493. * Could be used for:
  1494. * - DML statements: INSERT, UPDATE, DELETE, etc.
  1495. * - DDL statements: CREATE, DROP, ALTER, etc.
  1496. * - DCL statements: GRANT, REVOKE, etc.
  1497. * - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1498. * - Other statements that don't yield a row set.
  1499. *
  1500. * This method supports PDO binding types as well as DBAL mapping types.
  1501. *
  1502. * @param string $sql SQL statement
  1503. * @param array<int, mixed>|array<string, mixed> $params Statement parameters
  1504. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1505. *
  1506. * @return int|string The number of affected rows.
  1507. *
  1508. * @throws Exception
  1509. */
  1510. public function executeStatement($sql, array $params = [], array $types = [])
  1511. {
  1512. $connection = $this->getWrappedConnection();
  1514. $logger = $this->_config->getSQLLogger();
  1515. if ($logger) {
  1516. $logger->startQuery($sql, $params, $types);
  1517. }
  1519. try {
  1520. if ($params) {
  1521. [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1523. $stmt = $connection->prepare($sql);
  1525. if ($types) {
  1526. $this->_bindTypedValues($stmt, $params, $types);
  1527. $stmt->execute();
  1528. } else {
  1529. $stmt->execute($params);
  1530. }
  1532. $result = $stmt->rowCount();
  1533. } else {
  1534. $result = $connection->exec($sql);
  1535. }
  1536. } catch (Throwable $e) {
  1537. $this->handleExceptionDuringQuery(
  1538. $e,
  1539. $sql,
  1540. $params,
  1541. $types
  1542. );
  1543. }
  1545. if ($logger) {
  1546. $logger->stopQuery();
  1547. }
  1549. return $result;
  1550. }
  1552. /**
  1553. * Executes an SQL statement and return the number of affected rows.
  1554. *
  1555. * @deprecated Use {@link executeStatement()} instead.
  1556. *
  1557. * @param string $sql
  1558. *
  1559. * @return int|string The number of affected rows.
  1560. *
  1561. * @throws Exception
  1562. */
  1563. public function exec($sql)
  1564. {
  1565. Deprecation::trigger(
  1566. 'doctrine/dbal',
  1567. 'https://github.com/doctrine/dbal/pull/4163',
  1568. 'Connection::exec() is deprecated, use Connection::executeStatement() instead.'
  1569. );
  1571. $connection = $this->getWrappedConnection();
  1573. $logger = $this->_config->getSQLLogger();
  1574. if ($logger) {
  1575. $logger->startQuery($sql);
  1576. }
  1578. try {
  1579. $result = $connection->exec($sql);
  1580. } catch (Throwable $e) {
  1581. $this->handleExceptionDuringQuery($e, $sql);
  1582. }
  1584. if ($logger) {
  1585. $logger->stopQuery();
  1586. }
  1588. return $result;
  1589. }
  1591. /**
  1592. * Returns the current transaction nesting level.
  1593. *
  1594. * @return int The nesting level. A value of 0 means there's no active transaction.
  1595. */
  1596. public function getTransactionNestingLevel()
  1597. {
  1598. return $this->transactionNestingLevel;
  1599. }
  1601. /**
  1602. * Fetches the SQLSTATE associated with the last database operation.
  1603. *
  1604. * @deprecated The error information is available via exceptions.
  1605. *
  1606. * @return string|null The last error code.
  1607. */
  1608. public function errorCode()
  1609. {
  1610. Deprecation::trigger(
  1611. 'doctrine/dbal',
  1612. 'https://github.com/doctrine/dbal/pull/3507',
  1613. 'Connection::errorCode() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1614. );
  1616. return $this->getWrappedConnection()->errorCode();
  1617. }
  1619. /**
  1620. * {@inheritDoc}
  1621. *
  1622. * @deprecated The error information is available via exceptions.
  1623. */
  1624. public function errorInfo()
  1625. {
  1626. Deprecation::trigger(
  1627. 'doctrine/dbal',
  1628. 'https://github.com/doctrine/dbal/pull/3507',
  1629. 'Connection::errorInfo() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1630. );
  1632. return $this->getWrappedConnection()->errorInfo();
  1633. }
  1635. /**
  1636. * Returns the ID of the last inserted row, or the last value from a sequence object,
  1637. * depending on the underlying driver.
  1638. *
  1639. * Note: This method may not return a meaningful or consistent result across different drivers,
  1640. * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1641. * columns or sequences.
  1642. *
  1643. * @param string|null $name Name of the sequence object from which the ID should be returned.
  1644. *
  1645. * @return string|int|false A string representation of the last inserted ID.
  1646. */
  1647. public function lastInsertId($name = null)
  1648. {
  1649. return $this->getWrappedConnection()->lastInsertId($name);
  1650. }
  1652. /**
  1653. * Executes a function in a transaction.
  1654. *
  1655. * The function gets passed this Connection instance as an (optional) parameter.
  1656. *
  1657. * If an exception occurs during execution of the function or transaction commit,
  1658. * the transaction is rolled back and the exception re-thrown.
  1659. *
  1660. * @param Closure $func The function to execute transactionally.
  1661. *
  1662. * @return mixed The value returned by $func
  1663. *
  1664. * @throws Throwable
  1665. */
  1666. public function transactional(Closure $func)
  1667. {
  1668. $this->beginTransaction();
  1669. try {
  1670. $res = $func($this);
  1671. $this->commit();
  1673. return $res;
  1674. } catch (Throwable $e) {
  1675. $this->rollBack();
  1677. throw $e;
  1678. }
  1679. }
  1681. /**
  1682. * Sets if nested transactions should use savepoints.
  1683. *
  1684. * @param bool $nestTransactionsWithSavepoints
  1685. *
  1686. * @return void
  1687. *
  1688. * @throws ConnectionException
  1689. */
  1690. public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1691. {
  1692. if ($this->transactionNestingLevel > 0) {
  1693. throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1694. }
  1696. if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1697. throw ConnectionException::savepointsNotSupported();
  1698. }
  1700. $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1701. }
  1703. /**
  1704. * Gets if nested transactions should use savepoints.
  1705. *
  1706. * @return bool
  1707. */
  1708. public function getNestTransactionsWithSavepoints()
  1709. {
  1710. return $this->nestTransactionsWithSavepoints;
  1711. }
  1713. /**
  1714. * Returns the savepoint name to use for nested transactions are false if they are not supported
  1715. * "savepointFormat" parameter is not set
  1716. *
  1717. * @return mixed A string with the savepoint name or false.
  1718. */
  1719. protected function _getNestedTransactionSavePointName()
  1720. {
  1721. return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1722. }
  1724. /**
  1725. * {@inheritDoc}
  1726. */
  1727. public function beginTransaction()
  1728. {
  1729. $connection = $this->getWrappedConnection();
  1731. ++$this->transactionNestingLevel;
  1733. $logger = $this->_config->getSQLLogger();
  1735. if ($this->transactionNestingLevel === 1) {
  1736. if ($logger) {
  1737. $logger->startQuery('"START TRANSACTION"');
  1738. }
  1740. $connection->beginTransaction();
  1742. if ($logger) {
  1743. $logger->stopQuery();
  1744. }
  1745. } elseif ($this->nestTransactionsWithSavepoints) {
  1746. if ($logger) {
  1747. $logger->startQuery('"SAVEPOINT"');
  1748. }
  1750. $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1751. if ($logger) {
  1752. $logger->stopQuery();
  1753. }
  1754. }
  1756. return true;
  1757. }
  1759. /**
  1760. * {@inheritDoc}
  1761. *
  1762. * @throws ConnectionException If the commit failed due to no active transaction or
  1763. * because the transaction was marked for rollback only.
  1764. */
  1765. public function commit()
  1766. {
  1767. if ($this->transactionNestingLevel === 0) {
  1768. throw ConnectionException::noActiveTransaction();
  1769. }
  1771. if ($this->isRollbackOnly) {
  1772. throw ConnectionException::commitFailedRollbackOnly();
  1773. }
  1775. $result = true;
  1777. $connection = $this->getWrappedConnection();
  1779. $logger = $this->_config->getSQLLogger();
  1781. if ($this->transactionNestingLevel === 1) {
  1782. if ($logger) {
  1783. $logger->startQuery('"COMMIT"');
  1784. }
  1786. $result = $connection->commit();
  1788. if ($logger) {
  1789. $logger->stopQuery();
  1790. }
  1791. } elseif ($this->nestTransactionsWithSavepoints) {
  1792. if ($logger) {
  1793. $logger->startQuery('"RELEASE SAVEPOINT"');
  1794. }
  1796. $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1797. if ($logger) {
  1798. $logger->stopQuery();
  1799. }
  1800. }
  1802. --$this->transactionNestingLevel;
  1804. if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1805. return $result;
  1806. }
  1808. $this->beginTransaction();
  1810. return $result;
  1811. }
  1813. /**
  1814. * Commits all current nesting transactions.
  1815. */
  1816. private function commitAll(): void
  1817. {
  1818. while ($this->transactionNestingLevel !== 0) {
  1819. if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1820. // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1821. // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1822. $this->commit();
  1824. return;
  1825. }
  1827. $this->commit();
  1828. }
  1829. }
  1831. /**
  1832. * Cancels any database changes done during the current transaction.
  1833. *
  1834. * @return bool
  1835. *
  1836. * @throws ConnectionException If the rollback operation failed.
  1837. */
  1838. public function rollBack()
  1839. {
  1840. if ($this->transactionNestingLevel === 0) {
  1841. throw ConnectionException::noActiveTransaction();
  1842. }
  1844. $connection = $this->getWrappedConnection();
  1846. $logger = $this->_config->getSQLLogger();
  1848. if ($this->transactionNestingLevel === 1) {
  1849. if ($logger) {
  1850. $logger->startQuery('"ROLLBACK"');
  1851. }
  1853. $this->transactionNestingLevel = 0;
  1854. $connection->rollBack();
  1855. $this->isRollbackOnly = false;
  1856. if ($logger) {
  1857. $logger->stopQuery();
  1858. }
  1860. if ($this->autoCommit === false) {
  1861. $this->beginTransaction();
  1862. }
  1863. } elseif ($this->nestTransactionsWithSavepoints) {
  1864. if ($logger) {
  1865. $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1866. }
  1868. $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1869. --$this->transactionNestingLevel;
  1870. if ($logger) {
  1871. $logger->stopQuery();
  1872. }
  1873. } else {
  1874. $this->isRollbackOnly = true;
  1875. --$this->transactionNestingLevel;
  1876. }
  1878. return true;
  1879. }
  1881. /**
  1882. * Creates a new savepoint.
  1883. *
  1884. * @param string $savepoint The name of the savepoint to create.
  1885. *
  1886. * @return void
  1887. *
  1888. * @throws ConnectionException
  1889. */
  1890. public function createSavepoint($savepoint)
  1891. {
  1892. $platform = $this->getDatabasePlatform();
  1894. if (! $platform->supportsSavepoints()) {
  1895. throw ConnectionException::savepointsNotSupported();
  1896. }
  1898. $this->getWrappedConnection()->exec($platform->createSavePoint($savepoint));
  1899. }
  1901. /**
  1902. * Releases the given savepoint.
  1903. *
  1904. * @param string $savepoint The name of the savepoint to release.
  1905. *
  1906. * @return void
  1907. *
  1908. * @throws ConnectionException
  1909. */
  1910. public function releaseSavepoint($savepoint)
  1911. {
  1912. $platform = $this->getDatabasePlatform();
  1914. if (! $platform->supportsSavepoints()) {
  1915. throw ConnectionException::savepointsNotSupported();
  1916. }
  1918. if (! $platform->supportsReleaseSavepoints()) {
  1919. return;
  1920. }
  1922. $this->getWrappedConnection()->exec($platform->releaseSavePoint($savepoint));
  1923. }
  1925. /**
  1926. * Rolls back to the given savepoint.
  1927. *
  1928. * @param string $savepoint The name of the savepoint to rollback to.
  1929. *
  1930. * @return void
  1931. *
  1932. * @throws ConnectionException
  1933. */
  1934. public function rollbackSavepoint($savepoint)
  1935. {
  1936. $platform = $this->getDatabasePlatform();
  1938. if (! $platform->supportsSavepoints()) {
  1939. throw ConnectionException::savepointsNotSupported();
  1940. }
  1942. $this->getWrappedConnection()->exec($platform->rollbackSavePoint($savepoint));
  1943. }
  1945. /**
  1946. * Gets the wrapped driver connection.
  1947. *
  1948. * @return DriverConnection
  1949. */
  1950. public function getWrappedConnection()
  1951. {
  1952. $this->connect();
  1954. assert($this->_conn !== null);
  1956. return $this->_conn;
  1957. }
  1959. /**
  1960. * Gets the SchemaManager that can be used to inspect or change the
  1961. * database schema through the connection.
  1962. *
  1963. * @return AbstractSchemaManager
  1964. */
  1965. public function getSchemaManager()
  1966. {
  1967. if ($this->_schemaManager === null) {
  1968. $this->_schemaManager = $this->_driver->getSchemaManager($this);
  1969. }
  1971. return $this->_schemaManager;
  1972. }
  1974. /**
  1975. * Marks the current transaction so that the only possible
  1976. * outcome for the transaction to be rolled back.
  1977. *
  1978. * @return void
  1979. *
  1980. * @throws ConnectionException If no transaction is active.
  1981. */
  1982. public function setRollbackOnly()
  1983. {
  1984. if ($this->transactionNestingLevel === 0) {
  1985. throw ConnectionException::noActiveTransaction();
  1986. }
  1988. $this->isRollbackOnly = true;
  1989. }
  1991. /**
  1992. * Checks whether the current transaction is marked for rollback only.
  1993. *
  1994. * @return bool
  1995. *
  1996. * @throws ConnectionException If no transaction is active.
  1997. */
  1998. public function isRollbackOnly()
  1999. {
  2000. if ($this->transactionNestingLevel === 0) {
  2001. throw ConnectionException::noActiveTransaction();
  2002. }
  2004. return $this->isRollbackOnly;
  2005. }
  2007. /**
  2008. * Converts a given value to its database representation according to the conversion
  2009. * rules of a specific DBAL mapping type.
  2010. *
  2011. * @param mixed $value The value to convert.
  2012. * @param string $type The name of the DBAL mapping type.
  2013. *
  2014. * @return mixed The converted value.
  2015. */
  2016. public function convertToDatabaseValue($value, $type)
  2017. {
  2018. return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2019. }
  2021. /**
  2022. * Converts a given value to its PHP representation according to the conversion
  2023. * rules of a specific DBAL mapping type.
  2024. *
  2025. * @param mixed $value The value to convert.
  2026. * @param string $type The name of the DBAL mapping type.
  2027. *
  2028. * @return mixed The converted type.
  2029. */
  2030. public function convertToPHPValue($value, $type)
  2031. {
  2032. return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  2033. }
  2035. /**
  2036. * Binds a set of parameters, some or all of which are typed with a PDO binding type
  2037. * or DBAL mapping type, to a given statement.
  2038. *
  2039. * @internal Duck-typing used on the $stmt parameter to support driver statements as well as
  2040. * raw PDOStatement instances.
  2041. *
  2042. * @param \Doctrine\DBAL\Driver\Statement $stmt Prepared statement
  2043. * @param array<int, mixed>|array<string, mixed> $params Statement parameters
  2044. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  2045. *
  2046. * @return void
  2047. */
  2048. private function _bindTypedValues($stmt, array $params, array $types)
  2049. {
  2050. // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2051. if (is_int(key($params))) {
  2052. // Positional parameters
  2053. $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2054. $bindIndex = 1;
  2055. foreach ($params as $value) {
  2056. $typeIndex = $bindIndex + $typeOffset;
  2057. if (isset($types[$typeIndex])) {
  2058. $type = $types[$typeIndex];
  2059. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2060. $stmt->bindValue($bindIndex, $value, $bindingType);
  2061. } else {
  2062. $stmt->bindValue($bindIndex, $value);
  2063. }
  2065. ++$bindIndex;
  2066. }
  2067. } else {
  2068. // Named parameters
  2069. foreach ($params as $name => $value) {
  2070. if (isset($types[$name])) {
  2071. $type = $types[$name];
  2072. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2073. $stmt->bindValue($name, $value, $bindingType);
  2074. } else {
  2075. $stmt->bindValue($name, $value);
  2076. }
  2077. }
  2078. }
  2079. }
  2081. /**
  2082. * Gets the binding type of a given type. The given type can be a PDO or DBAL mapping type.
  2083. *
  2084. * @param mixed $value The value to bind.
  2085. * @param int|string|Type|null $type The type to bind (PDO or DBAL).
  2086. *
  2087. * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  2088. */
  2089. private function getBindingInfo($value, $type): array
  2090. {
  2091. if (is_string($type)) {
  2092. $type = Type::getType($type);
  2093. }
  2095. if ($type instanceof Type) {
  2096. $value = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2097. $bindingType = $type->getBindingType();
  2098. } else {
  2099. $bindingType = $type ?? ParameterType::STRING;
  2100. }
  2102. return [$value, $bindingType];
  2103. }
  2105. /**
  2106. * Resolves the parameters to a format which can be displayed.
  2107. *
  2108. * @internal This is a purely internal method. If you rely on this method, you are advised to
  2109. * copy/paste the code as this method may change, or be removed without prior notice.
  2110. *
  2111. * @param array<int, mixed>|array<string, mixed> $params Query parameters
  2112. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  2113. *
  2114. * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  2115. */
  2116. public function resolveParams(array $params, array $types)
  2117. {
  2118. $resolvedParams = [];
  2120. // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2121. if (is_int(key($params))) {
  2122. // Positional parameters
  2123. $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2124. $bindIndex = 1;
  2125. foreach ($params as $value) {
  2126. $typeIndex = $bindIndex + $typeOffset;
  2127. if (isset($types[$typeIndex])) {
  2128. $type = $types[$typeIndex];
  2129. [$value] = $this->getBindingInfo($value, $type);
  2130. $resolvedParams[$bindIndex] = $value;
  2131. } else {
  2132. $resolvedParams[$bindIndex] = $value;
  2133. }
  2135. ++$bindIndex;
  2136. }
  2137. } else {
  2138. // Named parameters
  2139. foreach ($params as $name => $value) {
  2140. if (isset($types[$name])) {
  2141. $type = $types[$name];
  2142. [$value] = $this->getBindingInfo($value, $type);
  2143. $resolvedParams[$name] = $value;
  2144. } else {
  2145. $resolvedParams[$name] = $value;
  2146. }
  2147. }
  2148. }
  2150. return $resolvedParams;
  2151. }
  2153. /**
  2154. * Creates a new instance of a SQL query builder.
  2155. *
  2156. * @return QueryBuilder
  2157. */
  2158. public function createQueryBuilder()
  2159. {
  2160. return new Query\QueryBuilder($this);
  2161. }
  2163. /**
  2164. * Ping the server
  2165. *
  2166. * When the server is not available the method returns FALSE.
  2167. * It is responsibility of the developer to handle this case
  2168. * and abort the request or reconnect manually:
  2169. *
  2170. * @deprecated
  2171. *
  2172. * @return bool
  2173. *
  2174. * @example
  2175. *
  2176. * if ($conn->ping() === false) {
  2177. * $conn->close();
  2178. * $conn->connect();
  2179. * }
  2180. *
  2181. * It is undefined if the underlying driver attempts to reconnect
  2182. * or disconnect when the connection is not available anymore
  2183. * as long it returns TRUE when a reconnect succeeded and
  2184. * FALSE when the connection was dropped.
  2185. */
  2186. public function ping()
  2187. {
  2188. Deprecation::trigger(
  2189. 'doctrine/dbal',
  2190. 'https://github.com/doctrine/dbal/pull/4119',
  2191. 'Retry and reconnecting lost connections now happens automatically, ping() will be removed in DBAL 3.'
  2192. );
  2194. $connection = $this->getWrappedConnection();
  2196. if ($connection instanceof PingableConnection) {
  2197. return $connection->ping();
  2198. }
  2200. try {
  2201. $this->query($this->getDatabasePlatform()->getDummySelectSQL());
  2203. return true;
  2204. } catch (DBALException $e) {
  2205. return false;
  2206. }
  2207. }
  2209. /**
  2210. * @internal
  2211. *
  2212. * @param array<int, mixed>|array<string, mixed> $params
  2213. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  2214. *
  2215. * @psalm-return never-return
  2216. *
  2217. * @throws Exception
  2218. */
  2219. public function handleExceptionDuringQuery(Throwable $e, string $sql, array $params = [], array $types = []): void
  2220. {
  2221. $this->throw(
  2222. Exception::driverExceptionDuringQuery(
  2223. $this->_driver,
  2224. $e,
  2225. $sql,
  2226. $this->resolveParams($params, $types)
  2227. )
  2228. );
  2229. }
  2231. /**
  2232. * @internal
  2233. *
  2234. * @psalm-return never-return
  2235. *
  2236. * @throws Exception
  2237. */
  2238. public function handleDriverException(Throwable $e): void
  2239. {
  2240. $this->throw(
  2241. Exception::driverException(
  2242. $this->_driver,
  2243. $e
  2244. )
  2245. );
  2246. }
  2248. /**
  2249. * @internal
  2250. *
  2251. * @psalm-return never-return
  2252. *
  2253. * @throws Exception
  2254. */
  2255. private function throw(Exception $e): void
  2256. {
  2257. if ($e instanceof ConnectionLost) {
  2258. $this->close();
  2259. }
  2261. throw $e;
  2262. }
  2264. private function ensureHasKeyValue(ResultStatement $stmt): void
  2265. {
  2266. $columnCount = $stmt->columnCount();
  2268. if ($columnCount < 2) {
  2269. throw NoKeyValue::fromColumnCount($columnCount);
  2270. }
  2271. }
  2272. }