vendor/doctrine/dbal/src/Connection.php line 1881

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayResult;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Driver\API\ExceptionConverter;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  13. use Doctrine\DBAL\Driver\Statement as DriverStatement;
  14. use Doctrine\DBAL\Event\TransactionBeginEventArgs;
  15. use Doctrine\DBAL\Event\TransactionCommitEventArgs;
  16. use Doctrine\DBAL\Event\TransactionRollBackEventArgs;
  17. use Doctrine\DBAL\Exception\ConnectionLost;
  18. use Doctrine\DBAL\Exception\DriverException;
  19. use Doctrine\DBAL\Exception\InvalidArgumentException;
  20. use Doctrine\DBAL\Platforms\AbstractPlatform;
  21. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  22. use Doctrine\DBAL\Query\QueryBuilder;
  23. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  24. use Doctrine\DBAL\Schema\DefaultSchemaManagerFactory;
  25. use Doctrine\DBAL\Schema\LegacySchemaManagerFactory;
  26. use Doctrine\DBAL\Schema\SchemaManagerFactory;
  27. use Doctrine\DBAL\SQL\Parser;
  28. use Doctrine\DBAL\Types\Type;
  29. use Doctrine\Deprecations\Deprecation;
  30. use LogicException;
  31. use SensitiveParameter;
  32. use Throwable;
  33. use Traversable;
  35. use function array_key_exists;
  36. use function assert;
  37. use function count;
  38. use function get_class;
  39. use function implode;
  40. use function is_array;
  41. use function is_int;
  42. use function is_string;
  43. use function key;
  44. use function method_exists;
  45. use function sprintf;
  47. /**
  48. * A database abstraction-level connection that implements features like events, transaction isolation levels,
  49. * configuration, emulated transaction nesting, lazy connecting and more.
  50. *
  51. * @psalm-import-type Params from DriverManager
  52. * @psalm-consistent-constructor
  53. */
  54. class Connection
  55. {
  56. /**
  57. * Represents an array of ints to be expanded by Doctrine SQL parsing.
  58. *
  59. * @deprecated Use {@see ArrayParameterType::INTEGER} instead.
  60. */
  61. public const PARAM_INT_ARRAY = ArrayParameterType::INTEGER;
  63. /**
  64. * Represents an array of strings to be expanded by Doctrine SQL parsing.
  65. *
  66. * @deprecated Use {@see ArrayParameterType::STRING} instead.
  67. */
  68. public const PARAM_STR_ARRAY = ArrayParameterType::STRING;
  70. /**
  71. * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
  72. *
  73. * @deprecated Use {@see ArrayParameterType::ASCII} instead.
  74. */
  75. public const PARAM_ASCII_STR_ARRAY = ArrayParameterType::ASCII;
  77. /**
  78. * Offset by which PARAM_* constants are detected as arrays of the param type.
  79. *
  80. * @internal Should be used only within the wrapper layer.
  81. */
  82. public const ARRAY_PARAM_OFFSET = 100;
  84. /**
  85. * The wrapped driver connection.
  86. *
  87. * @var DriverConnection|null
  88. */
  89. protected $_conn;
  91. /** @var Configuration */
  92. protected $_config;
  94. /**
  95. * @deprecated
  96. *
  97. * @var EventManager
  98. */
  99. protected $_eventManager;
  101. /**
  102. * @deprecated Use {@see createExpressionBuilder()} instead.
  103. *
  104. * @var ExpressionBuilder
  105. */
  106. protected $_expr;
  108. /**
  109. * The current auto-commit mode of this connection.
  110. */
  111. private bool $autoCommit = true;
  113. /**
  114. * The transaction nesting level.
  115. */
  116. private int $transactionNestingLevel = 0;
  118. /**
  119. * The currently active transaction isolation level or NULL before it has been determined.
  120. *
  121. * @var TransactionIsolationLevel::*|null
  122. */
  123. private $transactionIsolationLevel;
  125. /**
  126. * If nested transactions should use savepoints.
  127. */
  128. private bool $nestTransactionsWithSavepoints = false;
  130. /**
  131. * The parameters used during creation of the Connection instance.
  132. *
  133. * @var array<string,mixed>
  134. * @psalm-var Params
  135. */
  136. private array $params;
  138. /**
  139. * The database platform object used by the connection or NULL before it's initialized.
  140. */
  141. private ?AbstractPlatform $platform = null;
  143. private ?ExceptionConverter $exceptionConverter = null;
  144. private ?Parser $parser = null;
  146. /**
  147. * The schema manager.
  148. *
  149. * @deprecated Use {@see createSchemaManager()} instead.
  150. *
  151. * @var AbstractSchemaManager|null
  152. */
  153. protected $_schemaManager;
  155. /**
  156. * The used DBAL driver.
  157. *
  158. * @var Driver
  159. */
  160. protected $_driver;
  162. /**
  163. * Flag that indicates whether the current transaction is marked for rollback only.
  164. */
  165. private bool $isRollbackOnly = false;
  167. private SchemaManagerFactory $schemaManagerFactory;
  169. /**
  170. * Initializes a new instance of the Connection class.
  171. *
  172. * @internal The connection can be only instantiated by the driver manager.
  173. *
  174. * @param array<string,mixed> $params The connection parameters.
  175. * @param Driver $driver The driver to use.
  176. * @param Configuration|null $config The configuration, optional.
  177. * @param EventManager|null $eventManager The event manager, optional.
  178. * @psalm-param Params $params
  179. *
  180. * @throws Exception
  181. */
  182. public function __construct(
  183. #[SensitiveParameter]
  184. array $params,
  185. Driver $driver,
  186. ?Configuration $config = null,
  187. ?EventManager $eventManager = null
  188. ) {
  189. $this->_driver = $driver;
  190. $this->params = $params;
  192. // Create default config and event manager if none given
  193. $config ??= new Configuration();
  194. $eventManager ??= new EventManager();
  196. $this->_config = $config;
  197. $this->_eventManager = $eventManager;
  199. if (isset($params['platform'])) {
  200. if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  201. throw Exception::invalidPlatformType($params['platform']);
  202. }
  204. Deprecation::trigger(
  205. 'doctrine/dbal',
  206. 'https://github.com/doctrine/dbal/pull/5699',
  207. 'The "platform" connection parameter is deprecated.'
  208. . ' Use a driver middleware that would instantiate the platform instead.',
  209. );
  211. $this->platform = $params['platform'];
  212. $this->platform->setEventManager($this->_eventManager);
  213. $this->platform->setDisableTypeComments($config->getDisableTypeComments());
  214. }
  216. $this->_expr = $this->createExpressionBuilder();
  218. $this->autoCommit = $config->getAutoCommit();
  220. $schemaManagerFactory = $config->getSchemaManagerFactory();
  221. if ($schemaManagerFactory === null) {
  222. Deprecation::trigger(
  223. 'doctrine/dbal',
  224. 'https://github.com/doctrine/dbal/issues/5812',
  225. 'Not configuring a schema manager factory is deprecated.'
  226. . ' Use %s which is going to be the default in DBAL 4.',
  227. DefaultSchemaManagerFactory::class,
  228. );
  230. $schemaManagerFactory = new LegacySchemaManagerFactory();
  231. }
  233. $this->schemaManagerFactory = $schemaManagerFactory;
  234. }
  236. /**
  237. * Gets the parameters used during instantiation.
  238. *
  239. * @internal
  240. *
  241. * @return array<string,mixed>
  242. * @psalm-return Params
  243. */
  244. public function getParams()
  245. {
  246. return $this->params;
  247. }
  249. /**
  250. * Gets the name of the currently selected database.
  251. *
  252. * @return string|null The name of the database or NULL if a database is not selected.
  253. * The platforms which don't support the concept of a database (e.g. embedded databases)
  254. * must always return a string as an indicator of an implicitly selected database.
  255. *
  256. * @throws Exception
  257. */
  258. public function getDatabase()
  259. {
  260. $platform = $this->getDatabasePlatform();
  261. $query = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  262. $database = $this->fetchOne($query);
  264. assert(is_string($database) || $database === null);
  266. return $database;
  267. }
  269. /**
  270. * Gets the DBAL driver instance.
  271. *
  272. * @return Driver
  273. */
  274. public function getDriver()
  275. {
  276. return $this->_driver;
  277. }
  279. /**
  280. * Gets the Configuration used by the Connection.
  281. *
  282. * @return Configuration
  283. */
  284. public function getConfiguration()
  285. {
  286. return $this->_config;
  287. }
  289. /**
  290. * Gets the EventManager used by the Connection.
  291. *
  292. * @deprecated
  293. *
  294. * @return EventManager
  295. */
  296. public function getEventManager()
  297. {
  298. Deprecation::triggerIfCalledFromOutside(
  299. 'doctrine/dbal',
  300. 'https://github.com/doctrine/dbal/issues/5784',
  301. '%s is deprecated.',
  302. __METHOD__,
  303. );
  305. return $this->_eventManager;
  306. }
  308. /**
  309. * Gets the DatabasePlatform for the connection.
  310. *
  311. * @return AbstractPlatform
  312. *
  313. * @throws Exception
  314. */
  315. public function getDatabasePlatform()
  316. {
  317. if ($this->platform === null) {
  318. $this->platform = $this->detectDatabasePlatform();
  319. $this->platform->setEventManager($this->_eventManager);
  320. $this->platform->setDisableTypeComments($this->_config->getDisableTypeComments());
  321. }
  323. return $this->platform;
  324. }
  326. /**
  327. * Creates an expression builder for the connection.
  328. */
  329. public function createExpressionBuilder(): ExpressionBuilder
  330. {
  331. return new ExpressionBuilder($this);
  332. }
  334. /**
  335. * Gets the ExpressionBuilder for the connection.
  336. *
  337. * @deprecated Use {@see createExpressionBuilder()} instead.
  338. *
  339. * @return ExpressionBuilder
  340. */
  341. public function getExpressionBuilder()
  342. {
  343. Deprecation::triggerIfCalledFromOutside(
  344. 'doctrine/dbal',
  345. 'https://github.com/doctrine/dbal/issues/4515',
  346. 'Connection::getExpressionBuilder() is deprecated,'
  347. . ' use Connection::createExpressionBuilder() instead.',
  348. );
  350. return $this->_expr;
  351. }
  353. /**
  354. * Establishes the connection with the database.
  355. *
  356. * @internal This method will be made protected in DBAL 4.0.
  357. *
  358. * @return bool TRUE if the connection was successfully established, FALSE if
  359. * the connection is already open.
  360. *
  361. * @throws Exception
  362. *
  363. * @psalm-assert !null $this->_conn
  364. */
  365. public function connect()
  366. {
  367. Deprecation::triggerIfCalledFromOutside(
  368. 'doctrine/dbal',
  369. 'https://github.com/doctrine/dbal/issues/4966',
  370. 'Public access to Connection::connect() is deprecated.',
  371. );
  373. if ($this->_conn !== null) {
  374. return false;
  375. }
  377. try {
  378. $this->_conn = $this->_driver->connect($this->params);
  379. } catch (Driver\Exception $e) {
  380. throw $this->convertException($e);
  381. }
  383. if ($this->autoCommit === false) {
  384. $this->beginTransaction();
  385. }
  387. if ($this->_eventManager->hasListeners(Events::postConnect)) {
  388. Deprecation::trigger(
  389. 'doctrine/dbal',
  390. 'https://github.com/doctrine/dbal/issues/5784',
  391. 'Subscribing to %s events is deprecated. Implement a middleware instead.',
  392. Events::postConnect,
  393. );
  395. $eventArgs = new Event\ConnectionEventArgs($this);
  396. $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  397. }
  399. return true;
  400. }
  402. /**
  403. * Detects and sets the database platform.
  404. *
  405. * Evaluates custom platform class and version in order to set the correct platform.
  406. *
  407. * @throws Exception If an invalid platform was specified for this connection.
  408. */
  409. private function detectDatabasePlatform(): AbstractPlatform
  410. {
  411. $version = $this->getDatabasePlatformVersion();
  413. if ($version !== null) {
  414. assert($this->_driver instanceof VersionAwarePlatformDriver);
  416. return $this->_driver->createDatabasePlatformForVersion($version);
  417. }
  419. return $this->_driver->getDatabasePlatform();
  420. }
  422. /**
  423. * Returns the version of the related platform if applicable.
  424. *
  425. * Returns null if either the driver is not capable to create version
  426. * specific platform instances, no explicit server version was specified
  427. * or the underlying driver connection cannot determine the platform
  428. * version without having to query it (performance reasons).
  429. *
  430. * @return string|null
  431. *
  432. * @throws Throwable
  433. */
  434. private function getDatabasePlatformVersion()
  435. {
  436. // Driver does not support version specific platforms.
  437. if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  438. return null;
  439. }
  441. // Explicit platform version requested (supersedes auto-detection).
  442. if (isset($this->params['serverVersion'])) {
  443. return $this->params['serverVersion'];
  444. }
  446. if (isset($this->params['primary']) && isset($this->params['primary']['serverVersion'])) {
  447. return $this->params['primary']['serverVersion'];
  448. }
  450. // If not connected, we need to connect now to determine the platform version.
  451. if ($this->_conn === null) {
  452. try {
  453. $this->connect();
  454. } catch (Exception $originalException) {
  455. if (! isset($this->params['dbname'])) {
  456. throw $originalException;
  457. }
  459. Deprecation::trigger(
  460. 'doctrine/dbal',
  461. 'https://github.com/doctrine/dbal/pull/5707',
  462. 'Relying on a fallback connection used to determine the database platform while connecting'
  463. . ' to a non-existing database is deprecated. Either use an existing database name in'
  464. . ' connection parameters or omit the database name if the platform'
  465. . ' and the server configuration allow that.',
  466. );
  468. // The database to connect to might not yet exist.
  469. // Retry detection without database name connection parameter.
  470. $params = $this->params;
  472. unset($this->params['dbname']);
  474. try {
  475. $this->connect();
  476. } catch (Exception $fallbackException) {
  477. // Either the platform does not support database-less connections
  478. // or something else went wrong.
  479. throw $originalException;
  480. } finally {
  481. $this->params = $params;
  482. }
  484. $serverVersion = $this->getServerVersion();
  486. // Close "temporary" connection to allow connecting to the real database again.
  487. $this->close();
  489. return $serverVersion;
  490. }
  491. }
  493. return $this->getServerVersion();
  494. }
  496. /**
  497. * Returns the database server version if the underlying driver supports it.
  498. *
  499. * @return string|null
  500. *
  501. * @throws Exception
  502. */
  503. private function getServerVersion()
  504. {
  505. $connection = $this->getWrappedConnection();
  507. // Automatic platform version detection.
  508. if ($connection instanceof ServerInfoAwareConnection) {
  509. try {
  510. return $connection->getServerVersion();
  511. } catch (Driver\Exception $e) {
  512. throw $this->convertException($e);
  513. }
  514. }
  516. Deprecation::trigger(
  517. 'doctrine/dbal',
  518. 'https://github.com/doctrine/dbal/pull/4750',
  519. 'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  520. get_class($connection),
  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. * Prepares and executes an SQL query and returns the first row of the result
  576. * as an associative array.
  577. *
  578. * @param string $query SQL query
  579. * @param list<mixed>|array<string, mixed> $params Query parameters
  580. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  581. *
  582. * @return array<string, mixed>|false False is returned if no rows are found.
  583. *
  584. * @throws Exception
  585. */
  586. public function fetchAssociative(string $query, array $params = [], array $types = [])
  587. {
  588. return $this->executeQuery($query, $params, $types)->fetchAssociative();
  589. }
  591. /**
  592. * Prepares and executes an SQL query and returns the first row of the result
  593. * as a numerically indexed array.
  594. *
  595. * @param string $query SQL query
  596. * @param list<mixed>|array<string, mixed> $params Query parameters
  597. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  598. *
  599. * @return list<mixed>|false False is returned if no rows are found.
  600. *
  601. * @throws Exception
  602. */
  603. public function fetchNumeric(string $query, array $params = [], array $types = [])
  604. {
  605. return $this->executeQuery($query, $params, $types)->fetchNumeric();
  606. }
  608. /**
  609. * Prepares and executes an SQL query and returns the value of a single column
  610. * of the first row of the result.
  611. *
  612. * @param string $query SQL query
  613. * @param list<mixed>|array<string, mixed> $params Query parameters
  614. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  615. *
  616. * @return mixed|false False is returned if no rows are found.
  617. *
  618. * @throws Exception
  619. */
  620. public function fetchOne(string $query, array $params = [], array $types = [])
  621. {
  622. return $this->executeQuery($query, $params, $types)->fetchOne();
  623. }
  625. /**
  626. * Whether an actual connection to the database is established.
  627. *
  628. * @return bool
  629. */
  630. public function isConnected()
  631. {
  632. return $this->_conn !== null;
  633. }
  635. /**
  636. * Checks whether a transaction is currently active.
  637. *
  638. * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  639. */
  640. public function isTransactionActive()
  641. {
  642. return $this->transactionNestingLevel > 0;
  643. }
  645. /**
  646. * Adds condition based on the criteria to the query components
  647. *
  648. * @param array<string,mixed> $criteria Map of key columns to their values
  649. * @param string[] $columns Column names
  650. * @param mixed[] $values Column values
  651. * @param string[] $conditions Key conditions
  652. *
  653. * @throws Exception
  654. */
  655. private function addCriteriaCondition(
  656. array $criteria,
  657. array &$columns,
  658. array &$values,
  659. array &$conditions
  660. ): void {
  661. $platform = $this->getDatabasePlatform();
  663. foreach ($criteria as $columnName => $value) {
  664. if ($value === null) {
  665. $conditions[] = $platform->getIsNullExpression($columnName);
  666. continue;
  667. }
  669. $columns[] = $columnName;
  670. $values[] = $value;
  671. $conditions[] = $columnName . ' = ?';
  672. }
  673. }
  675. /**
  676. * Executes an SQL DELETE statement on a table.
  677. *
  678. * Table expression and columns are not escaped and are not safe for user-input.
  679. *
  680. * @param string $table Table name
  681. * @param array<string, mixed> $criteria Deletion criteria
  682. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  683. *
  684. * @return int|string The number of affected rows.
  685. *
  686. * @throws Exception
  687. */
  688. public function delete($table, array $criteria, array $types = [])
  689. {
  690. if (count($criteria) === 0) {
  691. throw InvalidArgumentException::fromEmptyCriteria();
  692. }
  694. $columns = $values = $conditions = [];
  696. $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  698. return $this->executeStatement(
  699. 'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  700. $values,
  701. is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  702. );
  703. }
  705. /**
  706. * Closes the connection.
  707. *
  708. * @return void
  709. */
  710. public function close()
  711. {
  712. $this->_conn = null;
  713. $this->transactionNestingLevel = 0;
  714. }
  716. /**
  717. * Sets the transaction isolation level.
  718. *
  719. * @param TransactionIsolationLevel::* $level The level to set.
  720. *
  721. * @return int|string
  722. *
  723. * @throws Exception
  724. */
  725. public function setTransactionIsolation($level)
  726. {
  727. $this->transactionIsolationLevel = $level;
  729. return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  730. }
  732. /**
  733. * Gets the currently active transaction isolation level.
  734. *
  735. * @return TransactionIsolationLevel::* The current transaction isolation level.
  736. *
  737. * @throws Exception
  738. */
  739. public function getTransactionIsolation()
  740. {
  741. return $this->transactionIsolationLevel ??= $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  742. }
  744. /**
  745. * Executes an SQL UPDATE statement on a table.
  746. *
  747. * Table expression and columns are not escaped and are not safe for user-input.
  748. *
  749. * @param string $table Table name
  750. * @param array<string, mixed> $data Column-value pairs
  751. * @param array<string, mixed> $criteria Update criteria
  752. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  753. *
  754. * @return int|string The number of affected rows.
  755. *
  756. * @throws Exception
  757. */
  758. public function update($table, array $data, array $criteria, array $types = [])
  759. {
  760. $columns = $values = $conditions = $set = [];
  762. foreach ($data as $columnName => $value) {
  763. $columns[] = $columnName;
  764. $values[] = $value;
  765. $set[] = $columnName . ' = ?';
  766. }
  768. $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  770. if (is_string(key($types))) {
  771. $types = $this->extractTypeValues($columns, $types);
  772. }
  774. $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  775. . ' WHERE ' . implode(' AND ', $conditions);
  777. return $this->executeStatement($sql, $values, $types);
  778. }
  780. /**
  781. * Inserts a table row with specified data.
  782. *
  783. * Table expression and columns are not escaped and are not safe for user-input.
  784. *
  785. * @param string $table Table name
  786. * @param array<string, mixed> $data Column-value pairs
  787. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  788. *
  789. * @return int|string The number of affected rows.
  790. *
  791. * @throws Exception
  792. */
  793. public function insert($table, array $data, array $types = [])
  794. {
  795. if (count($data) === 0) {
  796. return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  797. }
  799. $columns = [];
  800. $values = [];
  801. $set = [];
  803. foreach ($data as $columnName => $value) {
  804. $columns[] = $columnName;
  805. $values[] = $value;
  806. $set[] = '?';
  807. }
  809. return $this->executeStatement(
  810. 'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  811. ' VALUES (' . implode(', ', $set) . ')',
  812. $values,
  813. is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  814. );
  815. }
  817. /**
  818. * Extract ordered type list from an ordered column list and type map.
  819. *
  820. * @param array<int, string> $columnList
  821. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  822. *
  823. * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  824. */
  825. private function extractTypeValues(array $columnList, array $types): array
  826. {
  827. $typeValues = [];
  829. foreach ($columnList as $columnName) {
  830. $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  831. }
  833. return $typeValues;
  834. }
  836. /**
  837. * Quotes a string so it can be safely used as a table or column name, even if
  838. * it is a reserved name.
  839. *
  840. * Delimiting style depends on the underlying database platform that is being used.
  841. *
  842. * NOTE: Just because you CAN use quoted identifiers does not mean
  843. * you SHOULD use them. In general, they end up causing way more
  844. * problems than they solve.
  845. *
  846. * @param string $str The name to be quoted.
  847. *
  848. * @return string The quoted name.
  849. */
  850. public function quoteIdentifier($str)
  851. {
  852. return $this->getDatabasePlatform()->quoteIdentifier($str);
  853. }
  855. /**
  856. * The usage of this method is discouraged. Use prepared statements
  857. * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  858. *
  859. * @param mixed $value
  860. * @param int|string|Type|null $type
  861. *
  862. * @return mixed
  863. */
  864. public function quote($value, $type = ParameterType::STRING)
  865. {
  866. $connection = $this->getWrappedConnection();
  868. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  870. return $connection->quote($value, $bindingType);
  871. }
  873. /**
  874. * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  875. *
  876. * @param string $query SQL query
  877. * @param list<mixed>|array<string, mixed> $params Query parameters
  878. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  879. *
  880. * @return list<list<mixed>>
  881. *
  882. * @throws Exception
  883. */
  884. public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  885. {
  886. return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  887. }
  889. /**
  890. * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  891. *
  892. * @param string $query SQL query
  893. * @param list<mixed>|array<string, mixed> $params Query parameters
  894. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  895. *
  896. * @return list<array<string,mixed>>
  897. *
  898. * @throws Exception
  899. */
  900. public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  901. {
  902. return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  903. }
  905. /**
  906. * Prepares and executes an SQL query and returns the result as an associative array with the keys
  907. * mapped to the first column and the values mapped to the second column.
  908. *
  909. * @param string $query SQL query
  910. * @param list<mixed>|array<string, mixed> $params Query parameters
  911. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  912. *
  913. * @return array<mixed,mixed>
  914. *
  915. * @throws Exception
  916. */
  917. public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  918. {
  919. return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  920. }
  922. /**
  923. * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  924. * to the first column and the values being an associative array representing the rest of the columns
  925. * and their values.
  926. *
  927. * @param string $query SQL query
  928. * @param list<mixed>|array<string, mixed> $params Query parameters
  929. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  930. *
  931. * @return array<mixed,array<string,mixed>>
  932. *
  933. * @throws Exception
  934. */
  935. public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  936. {
  937. return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  938. }
  940. /**
  941. * Prepares and executes an SQL query and returns the result as an array of the first column values.
  942. *
  943. * @param string $query SQL query
  944. * @param list<mixed>|array<string, mixed> $params Query parameters
  945. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  946. *
  947. * @return list<mixed>
  948. *
  949. * @throws Exception
  950. */
  951. public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  952. {
  953. return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  954. }
  956. /**
  957. * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  958. *
  959. * @param string $query SQL query
  960. * @param list<mixed>|array<string, mixed> $params Query parameters
  961. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  962. *
  963. * @return Traversable<int,list<mixed>>
  964. *
  965. * @throws Exception
  966. */
  967. public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  968. {
  969. return $this->executeQuery($query, $params, $types)->iterateNumeric();
  970. }
  972. /**
  973. * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  974. * as associative arrays.
  975. *
  976. * @param string $query SQL query
  977. * @param list<mixed>|array<string, mixed> $params Query parameters
  978. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  979. *
  980. * @return Traversable<int,array<string,mixed>>
  981. *
  982. * @throws Exception
  983. */
  984. public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  985. {
  986. return $this->executeQuery($query, $params, $types)->iterateAssociative();
  987. }
  989. /**
  990. * Prepares and executes an SQL query and returns the result as an iterator with the keys
  991. * mapped to the first column and the values mapped to the second column.
  992. *
  993. * @param string $query SQL query
  994. * @param list<mixed>|array<string, mixed> $params Query parameters
  995. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  996. *
  997. * @return Traversable<mixed,mixed>
  998. *
  999. * @throws Exception
  1000. */
  1001. public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  1002. {
  1003. return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  1004. }
  1006. /**
  1007. * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  1008. * to the first column and the values being an associative array representing the rest of the columns
  1009. * and their values.
  1010. *
  1011. * @param string $query SQL query
  1012. * @param list<mixed>|array<string, mixed> $params Query parameters
  1013. * @param array<int, int|string>|array<string, int|string> $types Parameter types
  1014. *
  1015. * @return Traversable<mixed,array<string,mixed>>
  1016. *
  1017. * @throws Exception
  1018. */
  1019. public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  1020. {
  1021. return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  1022. }
  1024. /**
  1025. * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  1026. *
  1027. * @param string $query SQL query
  1028. * @param list<mixed>|array<string, mixed> $params Query parameters
  1029. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1030. *
  1031. * @return Traversable<int,mixed>
  1032. *
  1033. * @throws Exception
  1034. */
  1035. public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1036. {
  1037. return $this->executeQuery($query, $params, $types)->iterateColumn();
  1038. }
  1040. /**
  1041. * Prepares an SQL statement.
  1042. *
  1043. * @param string $sql The SQL statement to prepare.
  1044. *
  1045. * @throws Exception
  1046. */
  1047. public function prepare(string $sql): Statement
  1048. {
  1049. $connection = $this->getWrappedConnection();
  1051. try {
  1052. $statement = $connection->prepare($sql);
  1053. } catch (Driver\Exception $e) {
  1054. throw $this->convertExceptionDuringQuery($e, $sql);
  1055. }
  1057. return new Statement($this, $statement, $sql);
  1058. }
  1060. /**
  1061. * Executes an, optionally parameterized, SQL query.
  1062. *
  1063. * If the query is parametrized, a prepared statement is used.
  1064. * If an SQLLogger is configured, the execution is logged.
  1065. *
  1066. * @param string $sql SQL query
  1067. * @param list<mixed>|array<string, mixed> $params Query parameters
  1068. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1069. *
  1070. * @throws Exception
  1071. */
  1072. public function executeQuery(
  1073. string $sql,
  1074. array $params = [],
  1075. $types = [],
  1076. ?QueryCacheProfile $qcp = null
  1077. ): Result {
  1078. if ($qcp !== null) {
  1079. return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1080. }
  1082. $connection = $this->getWrappedConnection();
  1084. $logger = $this->_config->getSQLLogger();
  1085. if ($logger !== null) {
  1086. $logger->startQuery($sql, $params, $types);
  1087. }
  1089. try {
  1090. if (count($params) > 0) {
  1091. if ($this->needsArrayParameterConversion($params, $types)) {
  1092. [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1093. }
  1095. $stmt = $connection->prepare($sql);
  1097. $this->bindParameters($stmt, $params, $types);
  1099. $result = $stmt->execute();
  1100. } else {
  1101. $result = $connection->query($sql);
  1102. }
  1104. return new Result($result, $this);
  1105. } catch (Driver\Exception $e) {
  1106. throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1107. } finally {
  1108. if ($logger !== null) {
  1109. $logger->stopQuery();
  1110. }
  1111. }
  1112. }
  1114. /**
  1115. * Executes a caching query.
  1116. *
  1117. * @param string $sql SQL query
  1118. * @param list<mixed>|array<string, mixed> $params Query parameters
  1119. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1120. *
  1121. * @throws CacheException
  1122. * @throws Exception
  1123. */
  1124. public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1125. {
  1126. $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1128. if ($resultCache === null) {
  1129. throw CacheException::noResultDriverConfigured();
  1130. }
  1132. $connectionParams = $this->params;
  1133. unset($connectionParams['platform'], $connectionParams['password'], $connectionParams['url']);
  1135. [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1137. $item = $resultCache->getItem($cacheKey);
  1139. if ($item->isHit()) {
  1140. $value = $item->get();
  1141. if (! is_array($value)) {
  1142. $value = [];
  1143. }
  1145. if (isset($value[$realKey])) {
  1146. return new Result(new ArrayResult($value[$realKey]), $this);
  1147. }
  1148. } else {
  1149. $value = [];
  1150. }
  1152. $data = $this->fetchAllAssociative($sql, $params, $types);
  1154. $value[$realKey] = $data;
  1156. $item->set($value);
  1158. $lifetime = $qcp->getLifetime();
  1159. if ($lifetime > 0) {
  1160. $item->expiresAfter($lifetime);
  1161. }
  1163. $resultCache->save($item);
  1165. return new Result(new ArrayResult($data), $this);
  1166. }
  1168. /**
  1169. * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1170. *
  1171. * Could be used for:
  1172. * - DML statements: INSERT, UPDATE, DELETE, etc.
  1173. * - DDL statements: CREATE, DROP, ALTER, etc.
  1174. * - DCL statements: GRANT, REVOKE, etc.
  1175. * - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1176. * - Other statements that don't yield a row set.
  1177. *
  1178. * This method supports PDO binding types as well as DBAL mapping types.
  1179. *
  1180. * @param string $sql SQL statement
  1181. * @param list<mixed>|array<string, mixed> $params Statement parameters
  1182. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1183. *
  1184. * @return int|string The number of affected rows.
  1185. *
  1186. * @throws Exception
  1187. */
  1188. public function executeStatement($sql, array $params = [], array $types = [])
  1189. {
  1190. $connection = $this->getWrappedConnection();
  1192. $logger = $this->_config->getSQLLogger();
  1193. if ($logger !== null) {
  1194. $logger->startQuery($sql, $params, $types);
  1195. }
  1197. try {
  1198. if (count($params) > 0) {
  1199. if ($this->needsArrayParameterConversion($params, $types)) {
  1200. [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1201. }
  1203. $stmt = $connection->prepare($sql);
  1205. $this->bindParameters($stmt, $params, $types);
  1207. return $stmt->execute()
  1208. ->rowCount();
  1209. }
  1211. return $connection->exec($sql);
  1212. } catch (Driver\Exception $e) {
  1213. throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1214. } finally {
  1215. if ($logger !== null) {
  1216. $logger->stopQuery();
  1217. }
  1218. }
  1219. }
  1221. /**
  1222. * Returns the current transaction nesting level.
  1223. *
  1224. * @return int The nesting level. A value of 0 means there's no active transaction.
  1225. */
  1226. public function getTransactionNestingLevel()
  1227. {
  1228. return $this->transactionNestingLevel;
  1229. }
  1231. /**
  1232. * Returns the ID of the last inserted row, or the last value from a sequence object,
  1233. * depending on the underlying driver.
  1234. *
  1235. * Note: This method may not return a meaningful or consistent result across different drivers,
  1236. * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1237. * columns or sequences.
  1238. *
  1239. * @param string|null $name Name of the sequence object from which the ID should be returned.
  1240. *
  1241. * @return string|int|false A string representation of the last inserted ID.
  1242. *
  1243. * @throws Exception
  1244. */
  1245. public function lastInsertId($name = null)
  1246. {
  1247. if ($name !== null) {
  1248. Deprecation::trigger(
  1249. 'doctrine/dbal',
  1250. 'https://github.com/doctrine/dbal/issues/4687',
  1251. 'The usage of Connection::lastInsertId() with a sequence name is deprecated.',
  1252. );
  1253. }
  1255. try {
  1256. return $this->getWrappedConnection()->lastInsertId($name);
  1257. } catch (Driver\Exception $e) {
  1258. throw $this->convertException($e);
  1259. }
  1260. }
  1262. /**
  1263. * Executes a function in a transaction.
  1264. *
  1265. * The function gets passed this Connection instance as an (optional) parameter.
  1266. *
  1267. * If an exception occurs during execution of the function or transaction commit,
  1268. * the transaction is rolled back and the exception re-thrown.
  1269. *
  1270. * @param Closure(self):T $func The function to execute transactionally.
  1271. *
  1272. * @return T The value returned by $func
  1273. *
  1274. * @throws Throwable
  1275. *
  1276. * @template T
  1277. */
  1278. public function transactional(Closure $func)
  1279. {
  1280. $this->beginTransaction();
  1281. try {
  1282. $res = $func($this);
  1283. $this->commit();
  1285. return $res;
  1286. } catch (Throwable $e) {
  1287. $this->rollBack();
  1289. throw $e;
  1290. }
  1291. }
  1293. /**
  1294. * Sets if nested transactions should use savepoints.
  1295. *
  1296. * @param bool $nestTransactionsWithSavepoints
  1297. *
  1298. * @return void
  1299. *
  1300. * @throws Exception
  1301. */
  1302. public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1303. {
  1304. if (! $nestTransactionsWithSavepoints) {
  1305. Deprecation::trigger(
  1306. 'doctrine/dbal',
  1307. 'https://github.com/doctrine/dbal/pull/5383',
  1308. <<<'DEPRECATION'
  1309. Nesting transactions without enabling savepoints is deprecated.
  1310. Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1311. DEPRECATION,
  1312. self::class,
  1313. );
  1314. }
  1316. if ($this->transactionNestingLevel > 0) {
  1317. throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1318. }
  1320. $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1321. }
  1323. /**
  1324. * Gets if nested transactions should use savepoints.
  1325. *
  1326. * @return bool
  1327. */
  1328. public function getNestTransactionsWithSavepoints()
  1329. {
  1330. return $this->nestTransactionsWithSavepoints;
  1331. }
  1333. /**
  1334. * Returns the savepoint name to use for nested transactions.
  1335. *
  1336. * @return string
  1337. */
  1338. protected function _getNestedTransactionSavePointName()
  1339. {
  1340. return 'DOCTRINE_' . $this->transactionNestingLevel;
  1341. }
  1343. /**
  1344. * @return bool
  1345. *
  1346. * @throws Exception
  1347. */
  1348. public function beginTransaction()
  1349. {
  1350. $connection = $this->getWrappedConnection();
  1352. ++$this->transactionNestingLevel;
  1354. $logger = $this->_config->getSQLLogger();
  1356. if ($this->transactionNestingLevel === 1) {
  1357. if ($logger !== null) {
  1358. $logger->startQuery('"START TRANSACTION"');
  1359. }
  1361. $connection->beginTransaction();
  1363. if ($logger !== null) {
  1364. $logger->stopQuery();
  1365. }
  1366. } elseif ($this->nestTransactionsWithSavepoints) {
  1367. if ($logger !== null) {
  1368. $logger->startQuery('"SAVEPOINT"');
  1369. }
  1371. $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1372. if ($logger !== null) {
  1373. $logger->stopQuery();
  1374. }
  1375. } else {
  1376. Deprecation::trigger(
  1377. 'doctrine/dbal',
  1378. 'https://github.com/doctrine/dbal/pull/5383',
  1379. <<<'DEPRECATION'
  1380. Nesting transactions without enabling savepoints is deprecated.
  1381. Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1382. DEPRECATION,
  1383. self::class,
  1384. );
  1385. }
  1387. $eventManager = $this->getEventManager();
  1389. if ($eventManager->hasListeners(Events::onTransactionBegin)) {
  1390. Deprecation::trigger(
  1391. 'doctrine/dbal',
  1392. 'https://github.com/doctrine/dbal/issues/5784',
  1393. 'Subscribing to %s events is deprecated.',
  1394. Events::onTransactionBegin,
  1395. );
  1397. $eventManager->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1398. }
  1400. return true;
  1401. }
  1403. /**
  1404. * @return bool
  1405. *
  1406. * @throws Exception
  1407. */
  1408. public function commit()
  1409. {
  1410. if ($this->transactionNestingLevel === 0) {
  1411. throw ConnectionException::noActiveTransaction();
  1412. }
  1414. if ($this->isRollbackOnly) {
  1415. throw ConnectionException::commitFailedRollbackOnly();
  1416. }
  1418. $result = true;
  1420. $connection = $this->getWrappedConnection();
  1422. if ($this->transactionNestingLevel === 1) {
  1423. $result = $this->doCommit($connection);
  1424. } elseif ($this->nestTransactionsWithSavepoints) {
  1425. $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1426. }
  1428. --$this->transactionNestingLevel;
  1430. $eventManager = $this->getEventManager();
  1432. if ($eventManager->hasListeners(Events::onTransactionCommit)) {
  1433. Deprecation::trigger(
  1434. 'doctrine/dbal',
  1435. 'https://github.com/doctrine/dbal/issues/5784',
  1436. 'Subscribing to %s events is deprecated.',
  1437. Events::onTransactionCommit,
  1438. );
  1440. $eventManager->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  1441. }
  1443. if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1444. return $result;
  1445. }
  1447. $this->beginTransaction();
  1449. return $result;
  1450. }
  1452. /**
  1453. * @return bool
  1454. *
  1455. * @throws DriverException
  1456. */
  1457. private function doCommit(DriverConnection $connection)
  1458. {
  1459. $logger = $this->_config->getSQLLogger();
  1461. if ($logger !== null) {
  1462. $logger->startQuery('"COMMIT"');
  1463. }
  1465. $result = $connection->commit();
  1467. if ($logger !== null) {
  1468. $logger->stopQuery();
  1469. }
  1471. return $result;
  1472. }
  1474. /**
  1475. * Commits all current nesting transactions.
  1476. *
  1477. * @throws Exception
  1478. */
  1479. private function commitAll(): void
  1480. {
  1481. while ($this->transactionNestingLevel !== 0) {
  1482. if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1483. // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1484. // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1485. $this->commit();
  1487. return;
  1488. }
  1490. $this->commit();
  1491. }
  1492. }
  1494. /**
  1495. * Cancels any database changes done during the current transaction.
  1496. *
  1497. * @return bool
  1498. *
  1499. * @throws Exception
  1500. */
  1501. public function rollBack()
  1502. {
  1503. if ($this->transactionNestingLevel === 0) {
  1504. throw ConnectionException::noActiveTransaction();
  1505. }
  1507. $connection = $this->getWrappedConnection();
  1509. $logger = $this->_config->getSQLLogger();
  1511. if ($this->transactionNestingLevel === 1) {
  1512. if ($logger !== null) {
  1513. $logger->startQuery('"ROLLBACK"');
  1514. }
  1516. $this->transactionNestingLevel = 0;
  1517. $connection->rollBack();
  1518. $this->isRollbackOnly = false;
  1519. if ($logger !== null) {
  1520. $logger->stopQuery();
  1521. }
  1523. if ($this->autoCommit === false) {
  1524. $this->beginTransaction();
  1525. }
  1526. } elseif ($this->nestTransactionsWithSavepoints) {
  1527. if ($logger !== null) {
  1528. $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1529. }
  1531. $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1532. --$this->transactionNestingLevel;
  1533. if ($logger !== null) {
  1534. $logger->stopQuery();
  1535. }
  1536. } else {
  1537. $this->isRollbackOnly = true;
  1538. --$this->transactionNestingLevel;
  1539. }
  1541. $eventManager = $this->getEventManager();
  1543. if ($eventManager->hasListeners(Events::onTransactionRollBack)) {
  1544. Deprecation::trigger(
  1545. 'doctrine/dbal',
  1546. 'https://github.com/doctrine/dbal/issues/5784',
  1547. 'Subscribing to %s events is deprecated.',
  1548. Events::onTransactionRollBack,
  1549. );
  1551. $eventManager->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1552. }
  1554. return true;
  1555. }
  1557. /**
  1558. * Creates a new savepoint.
  1559. *
  1560. * @param string $savepoint The name of the savepoint to create.
  1561. *
  1562. * @return void
  1563. *
  1564. * @throws Exception
  1565. */
  1566. public function createSavepoint($savepoint)
  1567. {
  1568. $platform = $this->getDatabasePlatform();
  1570. if (! $platform->supportsSavepoints()) {
  1571. throw ConnectionException::savepointsNotSupported();
  1572. }
  1574. $this->executeStatement($platform->createSavePoint($savepoint));
  1575. }
  1577. /**
  1578. * Releases the given savepoint.
  1579. *
  1580. * @param string $savepoint The name of the savepoint to release.
  1581. *
  1582. * @return void
  1583. *
  1584. * @throws Exception
  1585. */
  1586. public function releaseSavepoint($savepoint)
  1587. {
  1588. $logger = $this->_config->getSQLLogger();
  1590. $platform = $this->getDatabasePlatform();
  1592. if (! $platform->supportsSavepoints()) {
  1593. throw ConnectionException::savepointsNotSupported();
  1594. }
  1596. if (! $platform->supportsReleaseSavepoints()) {
  1597. if ($logger !== null) {
  1598. $logger->stopQuery();
  1599. }
  1601. return;
  1602. }
  1604. if ($logger !== null) {
  1605. $logger->startQuery('"RELEASE SAVEPOINT"');
  1606. }
  1608. $this->executeStatement($platform->releaseSavePoint($savepoint));
  1610. if ($logger === null) {
  1611. return;
  1612. }
  1614. $logger->stopQuery();
  1615. }
  1617. /**
  1618. * Rolls back to the given savepoint.
  1619. *
  1620. * @param string $savepoint The name of the savepoint to rollback to.
  1621. *
  1622. * @return void
  1623. *
  1624. * @throws Exception
  1625. */
  1626. public function rollbackSavepoint($savepoint)
  1627. {
  1628. $platform = $this->getDatabasePlatform();
  1630. if (! $platform->supportsSavepoints()) {
  1631. throw ConnectionException::savepointsNotSupported();
  1632. }
  1634. $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1635. }
  1637. /**
  1638. * Gets the wrapped driver connection.
  1639. *
  1640. * @deprecated Use {@link getNativeConnection()} to access the native connection.
  1641. *
  1642. * @return DriverConnection
  1643. *
  1644. * @throws Exception
  1645. */
  1646. public function getWrappedConnection()
  1647. {
  1648. Deprecation::triggerIfCalledFromOutside(
  1649. 'doctrine/dbal',
  1650. 'https://github.com/doctrine/dbal/issues/4966',
  1651. 'Connection::getWrappedConnection() is deprecated.'
  1652. . ' Use Connection::getNativeConnection() to access the native connection.',
  1653. );
  1655. $this->connect();
  1657. return $this->_conn;
  1658. }
  1660. /** @return resource|object */
  1661. public function getNativeConnection()
  1662. {
  1663. $this->connect();
  1665. if (! method_exists($this->_conn, 'getNativeConnection')) {
  1666. throw new LogicException(sprintf(
  1667. 'The driver connection %s does not support accessing the native connection.',
  1668. get_class($this->_conn),
  1669. ));
  1670. }
  1672. return $this->_conn->getNativeConnection();
  1673. }
  1675. /**
  1676. * Creates a SchemaManager that can be used to inspect or change the
  1677. * database schema through the connection.
  1678. *
  1679. * @throws Exception
  1680. */
  1681. public function createSchemaManager(): AbstractSchemaManager
  1682. {
  1683. return $this->schemaManagerFactory->createSchemaManager($this);
  1684. }
  1686. /**
  1687. * Gets the SchemaManager that can be used to inspect or change the
  1688. * database schema through the connection.
  1689. *
  1690. * @deprecated Use {@see createSchemaManager()} instead.
  1691. *
  1692. * @return AbstractSchemaManager
  1693. *
  1694. * @throws Exception
  1695. */
  1696. public function getSchemaManager()
  1697. {
  1698. Deprecation::triggerIfCalledFromOutside(
  1699. 'doctrine/dbal',
  1700. 'https://github.com/doctrine/dbal/issues/4515',
  1701. 'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.',
  1702. );
  1704. return $this->_schemaManager ??= $this->createSchemaManager();
  1705. }
  1707. /**
  1708. * Marks the current transaction so that the only possible
  1709. * outcome for the transaction to be rolled back.
  1710. *
  1711. * @return void
  1712. *
  1713. * @throws ConnectionException If no transaction is active.
  1714. */
  1715. public function setRollbackOnly()
  1716. {
  1717. if ($this->transactionNestingLevel === 0) {
  1718. throw ConnectionException::noActiveTransaction();
  1719. }
  1721. $this->isRollbackOnly = true;
  1722. }
  1724. /**
  1725. * Checks whether the current transaction is marked for rollback only.
  1726. *
  1727. * @return bool
  1728. *
  1729. * @throws ConnectionException If no transaction is active.
  1730. */
  1731. public function isRollbackOnly()
  1732. {
  1733. if ($this->transactionNestingLevel === 0) {
  1734. throw ConnectionException::noActiveTransaction();
  1735. }
  1737. return $this->isRollbackOnly;
  1738. }
  1740. /**
  1741. * Converts a given value to its database representation according to the conversion
  1742. * rules of a specific DBAL mapping type.
  1743. *
  1744. * @param mixed $value The value to convert.
  1745. * @param string $type The name of the DBAL mapping type.
  1746. *
  1747. * @return mixed The converted value.
  1748. *
  1749. * @throws Exception
  1750. */
  1751. public function convertToDatabaseValue($value, $type)
  1752. {
  1753. return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1754. }
  1756. /**
  1757. * Converts a given value to its PHP representation according to the conversion
  1758. * rules of a specific DBAL mapping type.
  1759. *
  1760. * @param mixed $value The value to convert.
  1761. * @param string $type The name of the DBAL mapping type.
  1762. *
  1763. * @return mixed The converted type.
  1764. *
  1765. * @throws Exception
  1766. */
  1767. public function convertToPHPValue($value, $type)
  1768. {
  1769. return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1770. }
  1772. /**
  1773. * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1774. * or DBAL mapping type, to a given statement.
  1775. *
  1776. * @param DriverStatement $stmt Prepared statement
  1777. * @param list<mixed>|array<string, mixed> $params Statement parameters
  1778. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  1779. *
  1780. * @throws Exception
  1781. */
  1782. private function bindParameters(DriverStatement $stmt, array $params, array $types): void
  1783. {
  1784. // Check whether parameters are positional or named. Mixing is not allowed.
  1785. if (is_int(key($params))) {
  1786. $bindIndex = 1;
  1788. foreach ($params as $key => $value) {
  1789. if (isset($types[$key])) {
  1790. $type = $types[$key];
  1791. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1792. } else {
  1793. if (array_key_exists($key, $types)) {
  1794. Deprecation::trigger(
  1795. 'doctrine/dbal',
  1796. 'https://github.com/doctrine/dbal/pull/5550',
  1797. 'Using NULL as prepared statement parameter type is deprecated.'
  1798. . 'Omit or use ParameterType::STRING instead',
  1799. );
  1800. }
  1802. $bindingType = ParameterType::STRING;
  1803. }
  1805. $stmt->bindValue($bindIndex, $value, $bindingType);
  1807. ++$bindIndex;
  1808. }
  1809. } else {
  1810. // Named parameters
  1811. foreach ($params as $name => $value) {
  1812. if (isset($types[$name])) {
  1813. $type = $types[$name];
  1814. [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1815. } else {
  1816. if (array_key_exists($name, $types)) {
  1817. Deprecation::trigger(
  1818. 'doctrine/dbal',
  1819. 'https://github.com/doctrine/dbal/pull/5550',
  1820. 'Using NULL as prepared statement parameter type is deprecated.'
  1821. . 'Omit or use ParameterType::STRING instead',
  1822. );
  1823. }
  1825. $bindingType = ParameterType::STRING;
  1826. }
  1828. $stmt->bindValue($name, $value, $bindingType);
  1829. }
  1830. }
  1831. }
  1833. /**
  1834. * Gets the binding type of a given type.
  1835. *
  1836. * @param mixed $value The value to bind.
  1837. * @param int|string|Type|null $type The type to bind (PDO or DBAL).
  1838. *
  1839. * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1840. *
  1841. * @throws Exception
  1842. */
  1843. private function getBindingInfo($value, $type): array
  1844. {
  1845. if (is_string($type)) {
  1846. $type = Type::getType($type);
  1847. }
  1849. if ($type instanceof Type) {
  1850. $value = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1851. $bindingType = $type->getBindingType();
  1852. } else {
  1853. $bindingType = $type ?? ParameterType::STRING;
  1854. }
  1856. return [$value, $bindingType];
  1857. }
  1859. /**
  1860. * Creates a new instance of a SQL query builder.
  1861. *
  1862. * @return QueryBuilder
  1863. */
  1864. public function createQueryBuilder()
  1865. {
  1866. return new Query\QueryBuilder($this);
  1867. }
  1869. /**
  1870. * @internal
  1871. *
  1872. * @param list<mixed>|array<string, mixed> $params
  1873. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1874. */
  1875. final public function convertExceptionDuringQuery(
  1876. Driver\Exception $e,
  1877. string $sql,
  1878. array $params = [],
  1879. array $types = []
  1880. ): DriverException {
  1881. return $this->handleDriverException($e, new Query($sql, $params, $types));
  1882. }
  1884. /** @internal */
  1885. final public function convertException(Driver\Exception $e): DriverException
  1886. {
  1887. return $this->handleDriverException($e, null);
  1888. }
  1890. /**
  1891. * @param array<int, mixed>|array<string, mixed> $params
  1892. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1893. *
  1894. * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1895. */
  1896. private function expandArrayParameters(string $sql, array $params, array $types): array
  1897. {
  1898. $this->parser ??= $this->getDatabasePlatform()->createSQLParser();
  1899. $visitor = new ExpandArrayParameters($params, $types);
  1901. $this->parser->parse($sql, $visitor);
  1903. return [
  1904. $visitor->getSQL(),
  1905. $visitor->getParameters(),
  1906. $visitor->getTypes(),
  1907. ];
  1908. }
  1910. /**
  1911. * @param array<int, mixed>|array<string, mixed> $params
  1912. * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1913. */
  1914. private function needsArrayParameterConversion(array $params, array $types): bool
  1915. {
  1916. if (is_string(key($params))) {
  1917. return true;
  1918. }
  1920. foreach ($types as $type) {
  1921. if (
  1922. $type === ArrayParameterType::INTEGER
  1923. || $type === ArrayParameterType::STRING
  1924. || $type === ArrayParameterType::ASCII
  1925. || $type === ArrayParameterType::BINARY
  1926. ) {
  1927. return true;
  1928. }
  1929. }
  1931. return false;
  1932. }
  1934. private function handleDriverException(
  1935. Driver\Exception $driverException,
  1936. ?Query $query
  1937. ): DriverException {
  1938. $this->exceptionConverter ??= $this->_driver->getExceptionConverter();
  1939. $exception = $this->exceptionConverter->convert($driverException, $query);
  1941. if ($exception instanceof ConnectionLost) {
  1942. $this->close();
  1943. }
  1945. return $exception;
  1946. }
  1948. /**
  1949. * BC layer for a wide-spread use-case of old DBAL APIs
  1950. *
  1951. * @deprecated Use {@see executeStatement()} instead
  1952. *
  1953. * @param array<mixed> $params The query parameters
  1954. * @param array<int|string|null> $types The parameter types
  1955. */
  1956. public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1957. {
  1958. Deprecation::trigger(
  1959. 'doctrine/dbal',
  1960. 'https://github.com/doctrine/dbal/pull/4163',
  1961. '%s is deprecated, please use executeStatement() instead.',
  1962. __METHOD__,
  1963. );
  1965. return $this->executeStatement($sql, $params, $types);
  1966. }
  1968. /**
  1969. * BC layer for a wide-spread use-case of old DBAL APIs
  1970. *
  1971. * @deprecated Use {@see executeQuery()} instead
  1972. */
  1973. public function query(string $sql): Result
  1974. {
  1975. Deprecation::trigger(
  1976. 'doctrine/dbal',
  1977. 'https://github.com/doctrine/dbal/pull/4163',
  1978. '%s is deprecated, please use executeQuery() instead.',
  1979. __METHOD__,
  1980. );
  1982. return $this->executeQuery($sql);
  1983. }
  1985. /**
  1986. * BC layer for a wide-spread use-case of old DBAL APIs
  1987. *
  1988. * @deprecated please use {@see executeStatement()} instead
  1989. */
  1990. public function exec(string $sql): int
  1991. {
  1992. Deprecation::trigger(
  1993. 'doctrine/dbal',
  1994. 'https://github.com/doctrine/dbal/pull/4163',
  1995. '%s is deprecated, please use executeStatement() instead.',
  1996. __METHOD__,
  1997. );
  1999. return $this->executeStatement($sql);
  2000. }
  2001. }