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

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\Exception as TheDriverException;
  13. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  14. use Doctrine\DBAL\Driver\Statement as DriverStatement;
  15. use Doctrine\DBAL\Event\TransactionBeginEventArgs;
  16. use Doctrine\DBAL\Event\TransactionCommitEventArgs;
  17. use Doctrine\DBAL\Event\TransactionRollBackEventArgs;
  18. use Doctrine\DBAL\Exception\ConnectionLost;
  19. use Doctrine\DBAL\Exception\DeadlockException;
  20. use Doctrine\DBAL\Exception\DriverException;
  21. use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
  22. use Doctrine\DBAL\Exception\InvalidArgumentException;
  23. use Doctrine\DBAL\Exception\TransactionRolledBack;
  24. use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
  25. use Doctrine\DBAL\Platforms\AbstractPlatform;
  26. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  27. use Doctrine\DBAL\Query\QueryBuilder;
  28. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  29. use Doctrine\DBAL\Schema\DefaultSchemaManagerFactory;
  30. use Doctrine\DBAL\Schema\LegacySchemaManagerFactory;
  31. use Doctrine\DBAL\Schema\SchemaManagerFactory;
  32. use Doctrine\DBAL\SQL\Parser;
  33. use Doctrine\DBAL\Types\Type;
  34. use Doctrine\Deprecations\Deprecation;
  35. use LogicException;
  36. use SensitiveParameter;
  37. use Throwable;
  38. use Traversable;
  40. use function array_key_exists;
  41. use function assert;
  42. use function count;
  43. use function get_class;
  44. use function implode;
  45. use function is_array;
  46. use function is_int;
  47. use function is_string;
  48. use function key;
  49. use function method_exists;
  50. use function sprintf;
  52. /**
  53.  * A database abstraction-level connection that implements features like events, transaction isolation levels,
  54.  * configuration, emulated transaction nesting, lazy connecting and more.
  55.  *
  56.  * @phpstan-import-type Params from DriverManager
  57.  * @phpstan-consistent-constructor
  58.  */
  59. class Connection
  60. {
  61.     /**
  62.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  63.      *
  64.      * @deprecated Use {@see ArrayParameterType::INTEGER} instead.
  65.      */
  66.     public const PARAM_INT_ARRAY = ArrayParameterType::INTEGER;
  68.     /**
  69.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  70.      *
  71.      * @deprecated Use {@see ArrayParameterType::STRING} instead.
  72.      */
  73.     public const PARAM_STR_ARRAY = ArrayParameterType::STRING;
  75.     /**
  76.      * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
  77.      *
  78.      * @deprecated Use {@see ArrayParameterType::ASCII} instead.
  79.      */
  80.     public const PARAM_ASCII_STR_ARRAY = ArrayParameterType::ASCII;
  82.     /**
  83.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  84.      *
  85.      * @internal Should be used only within the wrapper layer.
  86.      */
  87.     public const ARRAY_PARAM_OFFSET = 100;
  89.     /**
  90.      * The wrapped driver connection.
  91.      *
  92.      * @var DriverConnection|null
  93.      */
  94.     protected $_conn;
  96.     /** @var Configuration */
  97.     protected $_config;
  99.     /**
  100.      * @deprecated
  101.      *
  102.      * @var EventManager
  103.      */
  104.     protected $_eventManager;
  106.     /**
  107.      * @deprecated Use {@see createExpressionBuilder()} instead.
  108.      *
  109.      * @var ExpressionBuilder
  110.      */
  111.     protected $_expr;
  113.     /**
  114.      * The current auto-commit mode of this connection.
  115.      */
  116.     private bool $autoCommit = true;
  118.     /**
  119.      * The transaction nesting level.
  120.      */
  121.     private int $transactionNestingLevel = 0;
  123.     /**
  124.      * The currently active transaction isolation level or NULL before it has been determined.
  125.      *
  126.      * @var TransactionIsolationLevel::*|null
  127.      */
  128.     private $transactionIsolationLevel;
  130.     /**
  131.      * If nested transactions should use savepoints.
  132.      */
  133.     private bool $nestTransactionsWithSavepoints = false;
  135.     /**
  136.      * The parameters used during creation of the Connection instance.
  137.      *
  138.      * @var array<string,mixed>
  139.      * @phpstan-var Params
  140.      */
  141.     private array $params;
  143.     /**
  144.      * The database platform object used by the connection or NULL before it's initialized.
  145.      */
  146.     private ?AbstractPlatform $platform = null;
  148.     private ?ExceptionConverter $exceptionConverter = null;
  149.     private ?Parser $parser                         = null;
  151.     /**
  152.      * The schema manager.
  153.      *
  154.      * @deprecated Use {@see createSchemaManager()} instead.
  155.      *
  156.      * @var AbstractSchemaManager|null
  157.      */
  158.     protected $_schemaManager;
  160.     /**
  161.      * The used DBAL driver.
  162.      *
  163.      * @var Driver
  164.      */
  165.     protected $_driver;
  167.     /**
  168.      * Flag that indicates whether the current transaction is marked for rollback only.
  169.      */
  170.     private bool $isRollbackOnly = false;
  172.     private SchemaManagerFactory $schemaManagerFactory;
  174.     /**
  175.      * Initializes a new instance of the Connection class.
  176.      *
  177.      * @internal The connection can be only instantiated by the driver manager.
  178.      *
  179.      * @param array<string,mixed> $params       The connection parameters.
  180.      * @param Driver              $driver       The driver to use.
  181.      * @param Configuration|null  $config       The configuration, optional.
  182.      * @param EventManager|null   $eventManager The event manager, optional.
  183.      * @phpstan-param Params $params
  184.      *
  185.      * @throws Exception
  186.      */
  187.     public function __construct(
  188.         #[SensitiveParameter]
  189.         array $params,
  190.         Driver $driver,
  191.         ?Configuration $config = null,
  192.         ?EventManager $eventManager = null
  193.     ) {
  194.         $this->_driver = $driver;
  195.         $this->params  = $params;
  197.         // Create default config and event manager if none given
  198.         $config       ??= new Configuration();
  199.         $eventManager ??= new EventManager();
  201.         $this->_config       = $config;
  202.         $this->_eventManager = $eventManager;
  204.         if (isset($params['platform'])) {
  205.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  206.                 throw Exception::invalidPlatformType($params['platform']);
  207.             }
  209.             Deprecation::trigger(
  210.                 'doctrine/dbal',
  211.                 'https://github.com/doctrine/dbal/pull/5699',
  212.                 'The "platform" connection parameter is deprecated.'
  213.                     . ' Use a driver middleware that would instantiate the platform instead.',
  214.             );
  216.             $this->platform = $params['platform'];
  217.             $this->platform->setEventManager($this->_eventManager);
  218.             $this->platform->setDisableTypeComments($config->getDisableTypeComments());
  219.         }
  221.         $this->_expr = $this->createExpressionBuilder();
  223.         $this->autoCommit = $config->getAutoCommit();
  225.         $schemaManagerFactory = $config->getSchemaManagerFactory();
  226.         if ($schemaManagerFactory === null) {
  227.             Deprecation::trigger(
  228.                 'doctrine/dbal',
  229.                 'https://github.com/doctrine/dbal/issues/5812',
  230.                 'Not configuring a schema manager factory is deprecated.'
  231.                     . ' Use %s which is going to be the default in DBAL 4.',
  232.                 DefaultSchemaManagerFactory::class,
  233.             );
  235.             $schemaManagerFactory = new LegacySchemaManagerFactory();
  236.         }
  238.         $this->schemaManagerFactory = $schemaManagerFactory;
  239.     }
  241.     /**
  242.      * Gets the parameters used during instantiation.
  243.      *
  244.      * @internal
  245.      *
  246.      * @return array<string,mixed>
  247.      * @phpstan-return Params
  248.      */
  249.     public function getParams()
  250.     {
  251.         return $this->params;
  252.     }
  254.     /**
  255.      * Gets the name of the currently selected database.
  256.      *
  257.      * @return string|null The name of the database or NULL if a database is not selected.
  258.      *                     The platforms which don't support the concept of a database (e.g. embedded databases)
  259.      *                     must always return a string as an indicator of an implicitly selected database.
  260.      *
  261.      * @throws Exception
  262.      */
  263.     public function getDatabase()
  264.     {
  265.         $platform = $this->getDatabasePlatform();
  266.         $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  267.         $database = $this->fetchOne($query);
  269.         assert(is_string($database) || $database === null);
  271.         return $database;
  272.     }
  274.     /**
  275.      * Gets the DBAL driver instance.
  276.      *
  277.      * @return Driver
  278.      */
  279.     public function getDriver()
  280.     {
  281.         return $this->_driver;
  282.     }
  284.     /**
  285.      * Gets the Configuration used by the Connection.
  286.      *
  287.      * @return Configuration
  288.      */
  289.     public function getConfiguration()
  290.     {
  291.         return $this->_config;
  292.     }
  294.     /**
  295.      * Gets the EventManager used by the Connection.
  296.      *
  297.      * @deprecated
  298.      *
  299.      * @return EventManager
  300.      */
  301.     public function getEventManager()
  302.     {
  303.         Deprecation::triggerIfCalledFromOutside(
  304.             'doctrine/dbal',
  305.             'https://github.com/doctrine/dbal/issues/5784',
  306.             '%s is deprecated.',
  307.             __METHOD__,
  308.         );
  310.         return $this->_eventManager;
  311.     }
  313.     /**
  314.      * Gets the DatabasePlatform for the connection.
  315.      *
  316.      * @return AbstractPlatform
  317.      *
  318.      * @throws Exception
  319.      */
  320.     public function getDatabasePlatform()
  321.     {
  322.         if ($this->platform === null) {
  323.             $this->platform = $this->detectDatabasePlatform();
  324.             $this->platform->setEventManager($this->_eventManager);
  325.             $this->platform->setDisableTypeComments($this->_config->getDisableTypeComments());
  326.         }
  328.         return $this->platform;
  329.     }
  331.     /**
  332.      * Creates an expression builder for the connection.
  333.      */
  334.     public function createExpressionBuilder(): ExpressionBuilder
  335.     {
  336.         return new ExpressionBuilder($this);
  337.     }
  339.     /**
  340.      * Gets the ExpressionBuilder for the connection.
  341.      *
  342.      * @deprecated Use {@see createExpressionBuilder()} instead.
  343.      *
  344.      * @return ExpressionBuilder
  345.      */
  346.     public function getExpressionBuilder()
  347.     {
  348.         Deprecation::triggerIfCalledFromOutside(
  349.             'doctrine/dbal',
  350.             'https://github.com/doctrine/dbal/issues/4515',
  351.             'Connection::getExpressionBuilder() is deprecated,'
  352.                 . ' use Connection::createExpressionBuilder() instead.',
  353.         );
  355.         return $this->_expr;
  356.     }
  358.     /**
  359.      * Establishes the connection with the database.
  360.      *
  361.      * @internal This method will be made protected in DBAL 4.0.
  362.      *
  363.      * @return bool TRUE if the connection was successfully established, FALSE if
  364.      *              the connection is already open.
  365.      *
  366.      * @throws Exception
  367.      *
  368.      * @phpstan-assert !null $this->_conn
  369.      */
  370.     public function connect()
  371.     {
  372.         Deprecation::triggerIfCalledFromOutside(
  373.             'doctrine/dbal',
  374.             'https://github.com/doctrine/dbal/issues/4966',
  375.             'Public access to Connection::connect() is deprecated.',
  376.         );
  378.         if ($this->_conn !== null) {
  379.             return false;
  380.         }
  382.         try {
  383.             $this->_conn = $this->_driver->connect($this->params);
  384.         } catch (Driver\Exception $e) {
  385.             throw $this->convertException($e);
  386.         }
  388.         if ($this->autoCommit === false) {
  389.             $this->beginTransaction();
  390.         }
  392.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  393.             Deprecation::trigger(
  394.                 'doctrine/dbal',
  395.                 'https://github.com/doctrine/dbal/issues/5784',
  396.                 'Subscribing to %s events is deprecated. Implement a middleware instead.',
  397.                 Events::postConnect,
  398.             );
  400.             $eventArgs = new Event\ConnectionEventArgs($this);
  401.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  402.         }
  404.         return true;
  405.     }
  407.     /**
  408.      * Detects and sets the database platform.
  409.      *
  410.      * Evaluates custom platform class and version in order to set the correct platform.
  411.      *
  412.      * @throws Exception If an invalid platform was specified for this connection.
  413.      */
  414.     private function detectDatabasePlatform(): AbstractPlatform
  415.     {
  416.         $version = $this->getDatabasePlatformVersion();
  418.         if ($version !== null) {
  419.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  421.             return $this->_driver->createDatabasePlatformForVersion($version);
  422.         }
  424.         return $this->_driver->getDatabasePlatform();
  425.     }
  427.     /**
  428.      * Returns the version of the related platform if applicable.
  429.      *
  430.      * Returns null if either the driver is not capable to create version
  431.      * specific platform instances, no explicit server version was specified
  432.      * or the underlying driver connection cannot determine the platform
  433.      * version without having to query it (performance reasons).
  434.      *
  435.      * @return string|null
  436.      *
  437.      * @throws Throwable
  438.      */
  439.     private function getDatabasePlatformVersion()
  440.     {
  441.         // Driver does not support version specific platforms.
  442.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  443.             return null;
  444.         }
  446.         // Explicit platform version requested (supersedes auto-detection).
  447.         if (isset($this->params['serverVersion'])) {
  448.             return $this->params['serverVersion'];
  449.         }
  451.         if (isset($this->params['primary']) && isset($this->params['primary']['serverVersion'])) {
  452.             return $this->params['primary']['serverVersion'];
  453.         }
  455.         // If not connected, we need to connect now to determine the platform version.
  456.         if ($this->_conn === null) {
  457.             try {
  458.                 $this->connect();
  459.             } catch (Exception $originalException) {
  460.                 if (! isset($this->params['dbname'])) {
  461.                     throw $originalException;
  462.                 }
  464.                 Deprecation::trigger(
  465.                     'doctrine/dbal',
  466.                     'https://github.com/doctrine/dbal/pull/5707',
  467.                     'Relying on a fallback connection used to determine the database platform while connecting'
  468.                         . ' to a non-existing database is deprecated. Either use an existing database name in'
  469.                         . ' connection parameters or omit the database name if the platform'
  470.                         . ' and the server configuration allow that.',
  471.                 );
  473.                 // The database to connect to might not yet exist.
  474.                 // Retry detection without database name connection parameter.
  475.                 $params = $this->params;
  477.                 unset($this->params['dbname']);
  479.                 try {
  480.                     $this->connect();
  481.                 } catch (Exception $fallbackException) {
  482.                     // Either the platform does not support database-less connections
  483.                     // or something else went wrong.
  484.                     throw $originalException;
  485.                 } finally {
  486.                     $this->params = $params;
  487.                 }
  489.                 $serverVersion = $this->getServerVersion();
  491.                 // Close "temporary" connection to allow connecting to the real database again.
  492.                 $this->close();
  494.                 return $serverVersion;
  495.             }
  496.         }
  498.         return $this->getServerVersion();
  499.     }
  501.     /**
  502.      * Returns the database server version if the underlying driver supports it.
  503.      *
  504.      * @return string|null
  505.      *
  506.      * @throws Exception
  507.      */
  508.     private function getServerVersion()
  509.     {
  510.         $connection = $this->getWrappedConnection();
  512.         // Automatic platform version detection.
  513.         if ($connection instanceof ServerInfoAwareConnection) {
  514.             try {
  515.                 return $connection->getServerVersion();
  516.             } catch (Driver\Exception $e) {
  517.                 throw $this->convertException($e);
  518.             }
  519.         }
  521.         Deprecation::trigger(
  522.             'doctrine/dbal',
  523.             'https://github.com/doctrine/dbal/pull/4750',
  524.             'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  525.             get_class($connection),
  526.         );
  528.         // Unable to detect platform version.
  529.         return null;
  530.     }
  532.     /**
  533.      * Returns the current auto-commit mode for this connection.
  534.      *
  535.      * @see    setAutoCommit
  536.      *
  537.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  538.      */
  539.     public function isAutoCommit()
  540.     {
  541.         return $this->autoCommit === true;
  542.     }
  544.     /**
  545.      * Sets auto-commit mode for this connection.
  546.      *
  547.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  548.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  549.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  550.      *
  551.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  552.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  553.      *
  554.      * @see   isAutoCommit
  555.      *
  556.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  557.      *
  558.      * @return void
  559.      */
  560.     public function setAutoCommit($autoCommit)
  561.     {
  562.         $autoCommit = (bool) $autoCommit;
  564.         // Mode not changed, no-op.
  565.         if ($autoCommit === $this->autoCommit) {
  566.             return;
  567.         }
  569.         $this->autoCommit = $autoCommit;
  571.         // Commit all currently active transactions if any when switching auto-commit mode.
  572.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  573.             return;
  574.         }
  576.         $this->commitAll();
  577.     }
  579.     /**
  580.      * Prepares and executes an SQL query and returns the first row of the result
  581.      * as an associative array.
  582.      *
  583.      * @param string                                                               $query  SQL query
  584.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  585.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  586.      *
  587.      * @return array<string, mixed>|false False is returned if no rows are found.
  588.      *
  589.      * @throws Exception
  590.      */
  591.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  592.     {
  593.         return $this->executeQuery($query, $params, $types)->fetchAssociative();
  594.     }
  596.     /**
  597.      * Prepares and executes an SQL query and returns the first row of the result
  598.      * as a numerically indexed array.
  599.      *
  600.      * @param string                                                               $query  SQL query
  601.      * @param list<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 list<mixed>|false False is returned if no rows are found.
  605.      *
  606.      * @throws Exception
  607.      */
  608.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  609.     {
  610.         return $this->executeQuery($query, $params, $types)->fetchNumeric();
  611.     }
  613.     /**
  614.      * Prepares and executes an SQL query and returns the value of a single column
  615.      * of the first row of the result.
  616.      *
  617.      * @param string                                                               $query  SQL query
  618.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  619.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  620.      *
  621.      * @return mixed|false False is returned if no rows are found.
  622.      *
  623.      * @throws Exception
  624.      */
  625.     public function fetchOne(string $query, array $params = [], array $types = [])
  626.     {
  627.         return $this->executeQuery($query, $params, $types)->fetchOne();
  628.     }
  630.     /**
  631.      * Whether an actual connection to the database is established.
  632.      *
  633.      * @return bool
  634.      */
  635.     public function isConnected()
  636.     {
  637.         return $this->_conn !== null;
  638.     }
  640.     /**
  641.      * Checks whether a transaction is currently active.
  642.      *
  643.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  644.      */
  645.     public function isTransactionActive()
  646.     {
  647.         return $this->transactionNestingLevel > 0;
  648.     }
  650.     /**
  651.      * Adds condition based on the criteria to the query components
  652.      *
  653.      * @param array<string,mixed> $criteria   Map of key columns to their values
  654.      * @param string[]            $columns    Column names
  655.      * @param mixed[]             $values     Column values
  656.      * @param string[]            $conditions Key conditions
  657.      *
  658.      * @throws Exception
  659.      */
  660.     private function addCriteriaCondition(
  661.         array $criteria,
  662.         array &$columns,
  663.         array &$values,
  664.         array &$conditions
  665.     ): void {
  666.         $platform = $this->getDatabasePlatform();
  668.         foreach ($criteria as $columnName => $value) {
  669.             if ($value === null) {
  670.                 $conditions[] = $platform->getIsNullExpression($columnName);
  671.                 continue;
  672.             }
  674.             $columns[]    = $columnName;
  675.             $values[]     = $value;
  676.             $conditions[] = $columnName . ' = ?';
  677.         }
  678.     }
  680.     /**
  681.      * Executes an SQL DELETE statement on a table.
  682.      *
  683.      * Table expression and columns are not escaped and are not safe for user-input.
  684.      *
  685.      * @param string                                                               $table    Table name
  686.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  687.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  688.      *
  689.      * @return int|string The number of affected rows.
  690.      *
  691.      * @throws Exception
  692.      */
  693.     public function delete($table, array $criteria, array $types = [])
  694.     {
  695.         if (count($criteria) === 0) {
  696.             throw InvalidArgumentException::fromEmptyCriteria();
  697.         }
  699.         $columns = $values = $conditions = [];
  701.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  703.         return $this->executeStatement(
  704.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  705.             $values,
  706.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  707.         );
  708.     }
  710.     /**
  711.      * Closes the connection.
  712.      *
  713.      * @return void
  714.      */
  715.     public function close()
  716.     {
  717.         $this->_conn                   = null;
  718.         $this->transactionNestingLevel = 0;
  719.     }
  721.     /**
  722.      * Sets the transaction isolation level.
  723.      *
  724.      * @param TransactionIsolationLevel::* $level The level to set.
  725.      *
  726.      * @return int|string
  727.      *
  728.      * @throws Exception
  729.      */
  730.     public function setTransactionIsolation($level)
  731.     {
  732.         $this->transactionIsolationLevel = $level;
  734.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  735.     }
  737.     /**
  738.      * Gets the currently active transaction isolation level.
  739.      *
  740.      * @return TransactionIsolationLevel::* The current transaction isolation level.
  741.      *
  742.      * @throws Exception
  743.      */
  744.     public function getTransactionIsolation()
  745.     {
  746.         return $this->transactionIsolationLevel ??= $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  747.     }
  749.     /**
  750.      * Executes an SQL UPDATE statement on a table.
  751.      *
  752.      * Table expression and columns are not escaped and are not safe for user-input.
  753.      *
  754.      * @param string                                                               $table    Table name
  755.      * @param array<string, mixed>                                                 $data     Column-value pairs
  756.      * @param array<string, mixed>                                                 $criteria Update criteria
  757.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  758.      *
  759.      * @return int|string The number of affected rows.
  760.      *
  761.      * @throws Exception
  762.      */
  763.     public function update($table, array $data, array $criteria, array $types = [])
  764.     {
  765.         $columns = $values = $conditions = $set = [];
  767.         foreach ($data as $columnName => $value) {
  768.             $columns[] = $columnName;
  769.             $values[]  = $value;
  770.             $set[]     = $columnName . ' = ?';
  771.         }
  773.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  775.         if (is_string(key($types))) {
  776.             $types = $this->extractTypeValues($columns, $types);
  777.         }
  779.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  780.                 . ' WHERE ' . implode(' AND ', $conditions);
  782.         return $this->executeStatement($sql, $values, $types);
  783.     }
  785.     /**
  786.      * Inserts a table row with specified data.
  787.      *
  788.      * Table expression and columns are not escaped and are not safe for user-input.
  789.      *
  790.      * @param string                                                               $table Table name
  791.      * @param array<string, mixed>                                                 $data  Column-value pairs
  792.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  793.      *
  794.      * @return int|string The number of affected rows.
  795.      *
  796.      * @throws Exception
  797.      */
  798.     public function insert($table, array $data, array $types = [])
  799.     {
  800.         if (count($data) === 0) {
  801.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  802.         }
  804.         $columns = [];
  805.         $values  = [];
  806.         $set     = [];
  808.         foreach ($data as $columnName => $value) {
  809.             $columns[] = $columnName;
  810.             $values[]  = $value;
  811.             $set[]     = '?';
  812.         }
  814.         return $this->executeStatement(
  815.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  816.             ' VALUES (' . implode(', ', $set) . ')',
  817.             $values,
  818.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  819.         );
  820.     }
  822.     /**
  823.      * Extract ordered type list from an ordered column list and type map.
  824.      *
  825.      * @param array<int, string>                                                   $columnList
  826.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  827.      *
  828.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  829.      */
  830.     private function extractTypeValues(array $columnList, array $types): array
  831.     {
  832.         $typeValues = [];
  834.         foreach ($columnList as $columnName) {
  835.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  836.         }
  838.         return $typeValues;
  839.     }
  841.     /**
  842.      * Quotes a string so it can be safely used as a table or column name, even if
  843.      * it is a reserved name.
  844.      *
  845.      * Delimiting style depends on the underlying database platform that is being used.
  846.      *
  847.      * NOTE: Just because you CAN use quoted identifiers does not mean
  848.      * you SHOULD use them. In general, they end up causing way more
  849.      * problems than they solve.
  850.      *
  851.      * @param string $str The name to be quoted.
  852.      *
  853.      * @return string The quoted name.
  854.      */
  855.     public function quoteIdentifier($str)
  856.     {
  857.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  858.     }
  860.     /**
  861.      * The usage of this method is discouraged. Use prepared statements
  862.      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  863.      *
  864.      * @param mixed                $value
  865.      * @param int|string|Type|null $type
  866.      *
  867.      * @return mixed
  868.      */
  869.     public function quote($value, $type = ParameterType::STRING)
  870.     {
  871.         $connection = $this->getWrappedConnection();
  873.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  875.         return $connection->quote($value, $bindingType);
  876.     }
  878.     /**
  879.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  880.      *
  881.      * @param string                                                               $query  SQL query
  882.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  883.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  884.      *
  885.      * @return list<list<mixed>>
  886.      *
  887.      * @throws Exception
  888.      */
  889.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  890.     {
  891.         return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  892.     }
  894.     /**
  895.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  896.      *
  897.      * @param string                                                               $query  SQL query
  898.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  899.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  900.      *
  901.      * @return list<array<string,mixed>>
  902.      *
  903.      * @throws Exception
  904.      */
  905.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  906.     {
  907.         return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  908.     }
  910.     /**
  911.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  912.      * mapped to the first column and the values mapped to the second column.
  913.      *
  914.      * @param string                                                               $query  SQL query
  915.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  916.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  917.      *
  918.      * @return array<mixed,mixed>
  919.      *
  920.      * @throws Exception
  921.      */
  922.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  923.     {
  924.         return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  925.     }
  927.     /**
  928.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  929.      * to the first column and the values being an associative array representing the rest of the columns
  930.      * and their values.
  931.      *
  932.      * @param string                                                               $query  SQL query
  933.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  934.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  935.      *
  936.      * @return array<mixed,array<string,mixed>>
  937.      *
  938.      * @throws Exception
  939.      */
  940.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  941.     {
  942.         return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  943.     }
  945.     /**
  946.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  947.      *
  948.      * @param string                                                               $query  SQL query
  949.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  950.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  951.      *
  952.      * @return list<mixed>
  953.      *
  954.      * @throws Exception
  955.      */
  956.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  957.     {
  958.         return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  959.     }
  961.     /**
  962.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  963.      *
  964.      * @param string                                                               $query  SQL query
  965.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  966.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  967.      *
  968.      * @return Traversable<int,list<mixed>>
  969.      *
  970.      * @throws Exception
  971.      */
  972.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  973.     {
  974.         return $this->executeQuery($query, $params, $types)->iterateNumeric();
  975.     }
  977.     /**
  978.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  979.      * as associative arrays.
  980.      *
  981.      * @param string                                                               $query  SQL query
  982.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  983.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  984.      *
  985.      * @return Traversable<int,array<string,mixed>>
  986.      *
  987.      * @throws Exception
  988.      */
  989.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  990.     {
  991.         return $this->executeQuery($query, $params, $types)->iterateAssociative();
  992.     }
  994.     /**
  995.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  996.      * mapped to the first column and the values mapped to the second column.
  997.      *
  998.      * @param string                                                               $query  SQL query
  999.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1000.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1001.      *
  1002.      * @return Traversable<mixed,mixed>
  1003.      *
  1004.      * @throws Exception
  1005.      */
  1006.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  1007.     {
  1008.         return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  1009.     }
  1011.     /**
  1012.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  1013.      * to the first column and the values being an associative array representing the rest of the columns
  1014.      * and their values.
  1015.      *
  1016.      * @param string                                           $query  SQL query
  1017.      * @param list<mixed>|array<string, mixed>                 $params Query parameters
  1018.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1019.      *
  1020.      * @return Traversable<mixed,array<string,mixed>>
  1021.      *
  1022.      * @throws Exception
  1023.      */
  1024.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  1025.     {
  1026.         return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  1027.     }
  1029.     /**
  1030.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  1031.      *
  1032.      * @param string                                                               $query  SQL query
  1033.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1034.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1035.      *
  1036.      * @return Traversable<int,mixed>
  1037.      *
  1038.      * @throws Exception
  1039.      */
  1040.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1041.     {
  1042.         return $this->executeQuery($query, $params, $types)->iterateColumn();
  1043.     }
  1045.     /**
  1046.      * Prepares an SQL statement.
  1047.      *
  1048.      * @param string $sql The SQL statement to prepare.
  1049.      *
  1050.      * @throws Exception
  1051.      */
  1052.     public function prepare(string $sql): Statement
  1053.     {
  1054.         $connection = $this->getWrappedConnection();
  1056.         try {
  1057.             $statement = $connection->prepare($sql);
  1058.         } catch (Driver\Exception $e) {
  1059.             throw $this->convertExceptionDuringQuery($e, $sql);
  1060.         }
  1062.         return new Statement($this, $statement, $sql);
  1063.     }
  1065.     /**
  1066.      * Executes an, optionally parameterized, SQL query.
  1067.      *
  1068.      * If the query is parametrized, a prepared statement is used.
  1069.      * If an SQLLogger is configured, the execution is logged.
  1070.      *
  1071.      * @param string                                                               $sql    SQL query
  1072.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1073.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1074.      *
  1075.      * @throws Exception
  1076.      */
  1077.     public function executeQuery(
  1078.         string $sql,
  1079.         array $params = [],
  1080.         $types = [],
  1081.         ?QueryCacheProfile $qcp = null
  1082.     ): Result {
  1083.         if ($qcp !== null) {
  1084.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1085.         }
  1087.         $connection = $this->getWrappedConnection();
  1089.         $logger = $this->_config->getSQLLogger();
  1090.         if ($logger !== null) {
  1091.             $logger->startQuery($sql, $params, $types);
  1092.         }
  1094.         try {
  1095.             if (count($params) > 0) {
  1096.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1097.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1098.                 }
  1100.                 $stmt = $connection->prepare($sql);
  1102.                 $this->bindParameters($stmt, $params, $types);
  1104.                 $result = $stmt->execute();
  1105.             } else {
  1106.                 $result = $connection->query($sql);
  1107.             }
  1109.             return new Result($result, $this);
  1110.         } catch (Driver\Exception $e) {
  1111.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1112.         } finally {
  1113.             if ($logger !== null) {
  1114.                 $logger->stopQuery();
  1115.             }
  1116.         }
  1117.     }
  1119.     /**
  1120.      * Executes a caching query.
  1121.      *
  1122.      * @param string                                                               $sql    SQL query
  1123.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1124.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1125.      *
  1126.      * @throws CacheException
  1127.      * @throws Exception
  1128.      */
  1129.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1130.     {
  1131.         $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1133.         if ($resultCache === null) {
  1134.             throw CacheException::noResultDriverConfigured();
  1135.         }
  1137.         $connectionParams = $this->params;
  1138.         unset($connectionParams['platform'], $connectionParams['password'], $connectionParams['url']);
  1140.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1142.         $item = $resultCache->getItem($cacheKey);
  1144.         if ($item->isHit()) {
  1145.             $value = $item->get();
  1146.             if (! is_array($value)) {
  1147.                 $value = [];
  1148.             }
  1150.             if (isset($value[$realKey])) {
  1151.                 return new Result(new ArrayResult($value[$realKey]), $this);
  1152.             }
  1153.         } else {
  1154.             $value = [];
  1155.         }
  1157.         $data = $this->fetchAllAssociative($sql, $params, $types);
  1159.         $value[$realKey] = $data;
  1161.         $item->set($value);
  1163.         $lifetime = $qcp->getLifetime();
  1164.         if ($lifetime > 0) {
  1165.             $item->expiresAfter($lifetime);
  1166.         }
  1168.         $resultCache->save($item);
  1170.         return new Result(new ArrayResult($data), $this);
  1171.     }
  1173.     /**
  1174.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1175.      *
  1176.      * Could be used for:
  1177.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1178.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1179.      *  - DCL statements: GRANT, REVOKE, etc.
  1180.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1181.      *  - Other statements that don't yield a row set.
  1182.      *
  1183.      * This method supports PDO binding types as well as DBAL mapping types.
  1184.      *
  1185.      * @param string                                                               $sql    SQL statement
  1186.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1187.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1188.      *
  1189.      * @return int|string The number of affected rows.
  1190.      *
  1191.      * @throws Exception
  1192.      */
  1193.     public function executeStatement($sql, array $params = [], array $types = [])
  1194.     {
  1195.         $connection = $this->getWrappedConnection();
  1197.         $logger = $this->_config->getSQLLogger();
  1198.         if ($logger !== null) {
  1199.             $logger->startQuery($sql, $params, $types);
  1200.         }
  1202.         try {
  1203.             if (count($params) > 0) {
  1204.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1205.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1206.                 }
  1208.                 $stmt = $connection->prepare($sql);
  1210.                 $this->bindParameters($stmt, $params, $types);
  1212.                 return $stmt->execute()
  1213.                     ->rowCount();
  1214.             }
  1216.             return $connection->exec($sql);
  1217.         } catch (Driver\Exception $e) {
  1218.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1219.         } finally {
  1220.             if ($logger !== null) {
  1221.                 $logger->stopQuery();
  1222.             }
  1223.         }
  1224.     }
  1226.     /**
  1227.      * Returns the current transaction nesting level.
  1228.      *
  1229.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1230.      */
  1231.     public function getTransactionNestingLevel()
  1232.     {
  1233.         return $this->transactionNestingLevel;
  1234.     }
  1236.     /**
  1237.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1238.      * depending on the underlying driver.
  1239.      *
  1240.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1241.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1242.      * columns or sequences.
  1243.      *
  1244.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1245.      *
  1246.      * @return string|int|false A string representation of the last inserted ID.
  1247.      *
  1248.      * @throws Exception
  1249.      */
  1250.     public function lastInsertId($name = null)
  1251.     {
  1252.         if ($name !== null) {
  1253.             Deprecation::trigger(
  1254.                 'doctrine/dbal',
  1255.                 'https://github.com/doctrine/dbal/issues/4687',
  1256.                 'The usage of Connection::lastInsertId() with a sequence name is deprecated.',
  1257.             );
  1258.         }
  1260.         try {
  1261.             return $this->getWrappedConnection()->lastInsertId($name);
  1262.         } catch (Driver\Exception $e) {
  1263.             throw $this->convertException($e);
  1264.         }
  1265.     }
  1267.     /**
  1268.      * Executes a function in a transaction.
  1269.      *
  1270.      * The function gets passed this Connection instance as an (optional) parameter.
  1271.      *
  1272.      * If an exception occurs during execution of the function or transaction commit,
  1273.      * the transaction is rolled back and the exception re-thrown.
  1274.      *
  1275.      * @param Closure(self):T $func The function to execute transactionally.
  1276.      *
  1277.      * @return T The value returned by $func
  1278.      *
  1279.      * @throws Throwable
  1280.      *
  1281.      * @template T
  1282.      */
  1283.     public function transactional(Closure $func)
  1284.     {
  1285.         $this->beginTransaction();
  1287.         $successful = false;
  1289.         try {
  1290.             $res = $func($this);
  1292.             $successful = true;
  1293.         } finally {
  1294.             if (! $successful) {
  1295.                 $this->rollBack();
  1296.             }
  1297.         }
  1299.         $shouldRollback = true;
  1300.         try {
  1301.             $this->commit();
  1303.             $shouldRollback = false;
  1304.         } catch (TheDriverException $t) {
  1305.             $convertedException = $this->handleDriverException($t, null);
  1306.             $shouldRollback     = ! (
  1307.                 $convertedException instanceof TransactionRolledBack
  1308.                 || $convertedException instanceof UniqueConstraintViolationException
  1309.                 || $convertedException instanceof ForeignKeyConstraintViolationException
  1310.                 || $convertedException instanceof DeadlockException
  1311.             );
  1313.             throw $t;
  1314.         } finally {
  1315.             if ($shouldRollback) {
  1316.                 $this->rollBack();
  1317.             }
  1318.         }
  1320.         return $res;
  1321.     }
  1323.     /**
  1324.      * Sets if nested transactions should use savepoints.
  1325.      *
  1326.      * @param bool $nestTransactionsWithSavepoints
  1327.      *
  1328.      * @return void
  1329.      *
  1330.      * @throws Exception
  1331.      */
  1332.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1333.     {
  1334.         if (! $nestTransactionsWithSavepoints) {
  1335.             Deprecation::trigger(
  1336.                 'doctrine/dbal',
  1337.                 'https://github.com/doctrine/dbal/pull/5383',
  1338.                 <<<'DEPRECATION'
  1339.                 Nesting transactions without enabling savepoints is deprecated.
  1340.                 Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1341.                 DEPRECATION,
  1342.                 self::class,
  1343.             );
  1344.         }
  1346.         if ($this->transactionNestingLevel > 0) {
  1347.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1348.         }
  1350.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1351.     }
  1353.     /**
  1354.      * Gets if nested transactions should use savepoints.
  1355.      *
  1356.      * @return bool
  1357.      */
  1358.     public function getNestTransactionsWithSavepoints()
  1359.     {
  1360.         return $this->nestTransactionsWithSavepoints;
  1361.     }
  1363.     /**
  1364.      * Returns the savepoint name to use for nested transactions.
  1365.      *
  1366.      * @return string
  1367.      */
  1368.     protected function _getNestedTransactionSavePointName()
  1369.     {
  1370.         return 'DOCTRINE_' . $this->transactionNestingLevel;
  1371.     }
  1373.     /**
  1374.      * @return bool
  1375.      *
  1376.      * @throws Exception
  1377.      */
  1378.     public function beginTransaction()
  1379.     {
  1380.         $connection = $this->getWrappedConnection();
  1382.         ++$this->transactionNestingLevel;
  1384.         $logger = $this->_config->getSQLLogger();
  1386.         if ($this->transactionNestingLevel === 1) {
  1387.             if ($logger !== null) {
  1388.                 $logger->startQuery('"START TRANSACTION"');
  1389.             }
  1391.             $connection->beginTransaction();
  1393.             if ($logger !== null) {
  1394.                 $logger->stopQuery();
  1395.             }
  1396.         } elseif ($this->nestTransactionsWithSavepoints) {
  1397.             if ($logger !== null) {
  1398.                 $logger->startQuery('"SAVEPOINT"');
  1399.             }
  1401.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1402.             if ($logger !== null) {
  1403.                 $logger->stopQuery();
  1404.             }
  1405.         } else {
  1406.             Deprecation::trigger(
  1407.                 'doctrine/dbal',
  1408.                 'https://github.com/doctrine/dbal/pull/5383',
  1409.                 <<<'DEPRECATION'
  1410.                 Nesting transactions without enabling savepoints is deprecated.
  1411.                 Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1412.                 DEPRECATION,
  1413.                 self::class,
  1414.             );
  1415.         }
  1417.         $eventManager = $this->getEventManager();
  1419.         if ($eventManager->hasListeners(Events::onTransactionBegin)) {
  1420.             Deprecation::trigger(
  1421.                 'doctrine/dbal',
  1422.                 'https://github.com/doctrine/dbal/issues/5784',
  1423.                 'Subscribing to %s events is deprecated.',
  1424.                 Events::onTransactionBegin,
  1425.             );
  1427.             $eventManager->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1428.         }
  1430.         return true;
  1431.     }
  1433.     /**
  1434.      * @return bool
  1435.      *
  1436.      * @throws Exception
  1437.      */
  1438.     public function commit()
  1439.     {
  1440.         if ($this->transactionNestingLevel === 0) {
  1441.             throw ConnectionException::noActiveTransaction();
  1442.         }
  1444.         if ($this->isRollbackOnly) {
  1445.             throw ConnectionException::commitFailedRollbackOnly();
  1446.         }
  1448.         $result = true;
  1450.         $connection = $this->getWrappedConnection();
  1452.         try {
  1453.             if ($this->transactionNestingLevel === 1) {
  1454.                 $result = $this->doCommit($connection);
  1455.             } elseif ($this->nestTransactionsWithSavepoints) {
  1456.                 $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1457.             }
  1458.         } finally {
  1459.             $this->updateTransactionStateAfterCommit();
  1460.         }
  1462.         return $result;
  1463.     }
  1465.     private function updateTransactionStateAfterCommit(): void
  1466.     {
  1467.         --$this->transactionNestingLevel;
  1469.         $eventManager = $this->getEventManager();
  1471.         if ($eventManager->hasListeners(Events::onTransactionCommit)) {
  1472.             Deprecation::trigger(
  1473.                 'doctrine/dbal',
  1474.                 'https://github.com/doctrine/dbal/issues/5784',
  1475.                 'Subscribing to %s events is deprecated.',
  1476.                 Events::onTransactionCommit,
  1477.             );
  1479.             $eventManager->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  1480.         }
  1482.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1483.             return;
  1484.         }
  1486.         $this->beginTransaction();
  1487.     }
  1489.     /**
  1490.      * @return bool
  1491.      *
  1492.      * @throws DriverException
  1493.      */
  1494.     private function doCommit(DriverConnection $connection)
  1495.     {
  1496.         $logger = $this->_config->getSQLLogger();
  1498.         if ($logger !== null) {
  1499.             $logger->startQuery('"COMMIT"');
  1500.         }
  1502.         $result = $connection->commit();
  1504.         if ($logger !== null) {
  1505.             $logger->stopQuery();
  1506.         }
  1508.         return $result;
  1509.     }
  1511.     /**
  1512.      * Commits all current nesting transactions.
  1513.      *
  1514.      * @throws Exception
  1515.      */
  1516.     private function commitAll(): void
  1517.     {
  1518.         while ($this->transactionNestingLevel !== 0) {
  1519.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1520.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1521.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1522.                 $this->commit();
  1524.                 return;
  1525.             }
  1527.             $this->commit();
  1528.         }
  1529.     }
  1531.     /**
  1532.      * Cancels any database changes done during the current transaction.
  1533.      *
  1534.      * @return bool
  1535.      *
  1536.      * @throws Exception
  1537.      */
  1538.     public function rollBack()
  1539.     {
  1540.         if ($this->transactionNestingLevel === 0) {
  1541.             throw ConnectionException::noActiveTransaction();
  1542.         }
  1544.         $connection = $this->getWrappedConnection();
  1546.         $logger = $this->_config->getSQLLogger();
  1548.         if ($this->transactionNestingLevel === 1) {
  1549.             if ($logger !== null) {
  1550.                 $logger->startQuery('"ROLLBACK"');
  1551.             }
  1553.             $this->transactionNestingLevel = 0;
  1554.             $connection->rollBack();
  1555.             $this->isRollbackOnly = false;
  1556.             if ($logger !== null) {
  1557.                 $logger->stopQuery();
  1558.             }
  1560.             if ($this->autoCommit === false) {
  1561.                 $this->beginTransaction();
  1562.             }
  1563.         } elseif ($this->nestTransactionsWithSavepoints) {
  1564.             if ($logger !== null) {
  1565.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1566.             }
  1568.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1569.             --$this->transactionNestingLevel;
  1570.             if ($logger !== null) {
  1571.                 $logger->stopQuery();
  1572.             }
  1573.         } else {
  1574.             $this->isRollbackOnly = true;
  1575.             --$this->transactionNestingLevel;
  1576.         }
  1578.         $eventManager = $this->getEventManager();
  1580.         if ($eventManager->hasListeners(Events::onTransactionRollBack)) {
  1581.             Deprecation::trigger(
  1582.                 'doctrine/dbal',
  1583.                 'https://github.com/doctrine/dbal/issues/5784',
  1584.                 'Subscribing to %s events is deprecated.',
  1585.                 Events::onTransactionRollBack,
  1586.             );
  1588.             $eventManager->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1589.         }
  1591.         return true;
  1592.     }
  1594.     /**
  1595.      * Creates a new savepoint.
  1596.      *
  1597.      * @param string $savepoint The name of the savepoint to create.
  1598.      *
  1599.      * @return void
  1600.      *
  1601.      * @throws Exception
  1602.      */
  1603.     public function createSavepoint($savepoint)
  1604.     {
  1605.         $platform = $this->getDatabasePlatform();
  1607.         if (! $platform->supportsSavepoints()) {
  1608.             throw ConnectionException::savepointsNotSupported();
  1609.         }
  1611.         $this->executeStatement($platform->createSavePoint($savepoint));
  1612.     }
  1614.     /**
  1615.      * Releases the given savepoint.
  1616.      *
  1617.      * @param string $savepoint The name of the savepoint to release.
  1618.      *
  1619.      * @return void
  1620.      *
  1621.      * @throws Exception
  1622.      */
  1623.     public function releaseSavepoint($savepoint)
  1624.     {
  1625.         $logger = $this->_config->getSQLLogger();
  1627.         $platform = $this->getDatabasePlatform();
  1629.         if (! $platform->supportsSavepoints()) {
  1630.             throw ConnectionException::savepointsNotSupported();
  1631.         }
  1633.         if (! $platform->supportsReleaseSavepoints()) {
  1634.             if ($logger !== null) {
  1635.                 $logger->stopQuery();
  1636.             }
  1638.             return;
  1639.         }
  1641.         if ($logger !== null) {
  1642.             $logger->startQuery('"RELEASE SAVEPOINT"');
  1643.         }
  1645.         $this->executeStatement($platform->releaseSavePoint($savepoint));
  1647.         if ($logger === null) {
  1648.             return;
  1649.         }
  1651.         $logger->stopQuery();
  1652.     }
  1654.     /**
  1655.      * Rolls back to the given savepoint.
  1656.      *
  1657.      * @param string $savepoint The name of the savepoint to rollback to.
  1658.      *
  1659.      * @return void
  1660.      *
  1661.      * @throws Exception
  1662.      */
  1663.     public function rollbackSavepoint($savepoint)
  1664.     {
  1665.         $platform = $this->getDatabasePlatform();
  1667.         if (! $platform->supportsSavepoints()) {
  1668.             throw ConnectionException::savepointsNotSupported();
  1669.         }
  1671.         $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1672.     }
  1674.     /**
  1675.      * Gets the wrapped driver connection.
  1676.      *
  1677.      * @deprecated Use {@link getNativeConnection()} to access the native connection.
  1678.      *
  1679.      * @return DriverConnection
  1680.      *
  1681.      * @throws Exception
  1682.      */
  1683.     public function getWrappedConnection()
  1684.     {
  1685.         Deprecation::triggerIfCalledFromOutside(
  1686.             'doctrine/dbal',
  1687.             'https://github.com/doctrine/dbal/issues/4966',
  1688.             'Connection::getWrappedConnection() is deprecated.'
  1689.                 . ' Use Connection::getNativeConnection() to access the native connection.',
  1690.         );
  1692.         $this->connect();
  1694.         return $this->_conn;
  1695.     }
  1697.     /** @return resource|object */
  1698.     public function getNativeConnection()
  1699.     {
  1700.         $this->connect();
  1702.         if (! method_exists($this->_conn, 'getNativeConnection')) {
  1703.             throw new LogicException(sprintf(
  1704.                 'The driver connection %s does not support accessing the native connection.',
  1705.                 get_class($this->_conn),
  1706.             ));
  1707.         }
  1709.         return $this->_conn->getNativeConnection();
  1710.     }
  1712.     /**
  1713.      * Creates a SchemaManager that can be used to inspect or change the
  1714.      * database schema through the connection.
  1715.      *
  1716.      * @throws Exception
  1717.      */
  1718.     public function createSchemaManager(): AbstractSchemaManager
  1719.     {
  1720.         return $this->schemaManagerFactory->createSchemaManager($this);
  1721.     }
  1723.     /**
  1724.      * Gets the SchemaManager that can be used to inspect or change the
  1725.      * database schema through the connection.
  1726.      *
  1727.      * @deprecated Use {@see createSchemaManager()} instead.
  1728.      *
  1729.      * @return AbstractSchemaManager
  1730.      *
  1731.      * @throws Exception
  1732.      */
  1733.     public function getSchemaManager()
  1734.     {
  1735.         Deprecation::triggerIfCalledFromOutside(
  1736.             'doctrine/dbal',
  1737.             'https://github.com/doctrine/dbal/issues/4515',
  1738.             'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.',
  1739.         );
  1741.         return $this->_schemaManager ??= $this->createSchemaManager();
  1742.     }
  1744.     /**
  1745.      * Marks the current transaction so that the only possible
  1746.      * outcome for the transaction to be rolled back.
  1747.      *
  1748.      * @return void
  1749.      *
  1750.      * @throws ConnectionException If no transaction is active.
  1751.      */
  1752.     public function setRollbackOnly()
  1753.     {
  1754.         if ($this->transactionNestingLevel === 0) {
  1755.             throw ConnectionException::noActiveTransaction();
  1756.         }
  1758.         $this->isRollbackOnly = true;
  1759.     }
  1761.     /**
  1762.      * Checks whether the current transaction is marked for rollback only.
  1763.      *
  1764.      * @return bool
  1765.      *
  1766.      * @throws ConnectionException If no transaction is active.
  1767.      */
  1768.     public function isRollbackOnly()
  1769.     {
  1770.         if ($this->transactionNestingLevel === 0) {
  1771.             throw ConnectionException::noActiveTransaction();
  1772.         }
  1774.         return $this->isRollbackOnly;
  1775.     }
  1777.     /**
  1778.      * Converts a given value to its database representation according to the conversion
  1779.      * rules of a specific DBAL mapping type.
  1780.      *
  1781.      * @param mixed  $value The value to convert.
  1782.      * @param string $type  The name of the DBAL mapping type.
  1783.      *
  1784.      * @return mixed The converted value.
  1785.      *
  1786.      * @throws Exception
  1787.      */
  1788.     public function convertToDatabaseValue($value, $type)
  1789.     {
  1790.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1791.     }
  1793.     /**
  1794.      * Converts a given value to its PHP representation according to the conversion
  1795.      * rules of a specific DBAL mapping type.
  1796.      *
  1797.      * @param mixed  $value The value to convert.
  1798.      * @param string $type  The name of the DBAL mapping type.
  1799.      *
  1800.      * @return mixed The converted type.
  1801.      *
  1802.      * @throws Exception
  1803.      */
  1804.     public function convertToPHPValue($value, $type)
  1805.     {
  1806.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1807.     }
  1809.     /**
  1810.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1811.      * or DBAL mapping type, to a given statement.
  1812.      *
  1813.      * @param DriverStatement                                                      $stmt   Prepared statement
  1814.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1815.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1816.      *
  1817.      * @throws Exception
  1818.      */
  1819.     private function bindParameters(DriverStatement $stmt, array $params, array $types): void
  1820.     {
  1821.         // Check whether parameters are positional or named. Mixing is not allowed.
  1822.         if (is_int(key($params))) {
  1823.             $bindIndex = 1;
  1825.             foreach ($params as $key => $value) {
  1826.                 if (isset($types[$key])) {
  1827.                     $type                  = $types[$key];
  1828.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1829.                 } else {
  1830.                     if (array_key_exists($key, $types)) {
  1831.                         Deprecation::trigger(
  1832.                             'doctrine/dbal',
  1833.                             'https://github.com/doctrine/dbal/pull/5550',
  1834.                             'Using NULL as prepared statement parameter type is deprecated.'
  1835.                                 . 'Omit or use ParameterType::STRING instead',
  1836.                         );
  1837.                     }
  1839.                     $bindingType = ParameterType::STRING;
  1840.                 }
  1842.                 $stmt->bindValue($bindIndex, $value, $bindingType);
  1844.                 ++$bindIndex;
  1845.             }
  1846.         } else {
  1847.             // Named parameters
  1848.             foreach ($params as $name => $value) {
  1849.                 if (isset($types[$name])) {
  1850.                     $type                  = $types[$name];
  1851.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1852.                 } else {
  1853.                     if (array_key_exists($name, $types)) {
  1854.                         Deprecation::trigger(
  1855.                             'doctrine/dbal',
  1856.                             'https://github.com/doctrine/dbal/pull/5550',
  1857.                             'Using NULL as prepared statement parameter type is deprecated.'
  1858.                                 . 'Omit or use ParameterType::STRING instead',
  1859.                         );
  1860.                     }
  1862.                     $bindingType = ParameterType::STRING;
  1863.                 }
  1865.                 $stmt->bindValue($name, $value, $bindingType);
  1866.             }
  1867.         }
  1868.     }
  1870.     /**
  1871.      * Gets the binding type of a given type.
  1872.      *
  1873.      * @param mixed                $value The value to bind.
  1874.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  1875.      *
  1876.      * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1877.      *
  1878.      * @throws Exception
  1879.      */
  1880.     private function getBindingInfo($value, $type): array
  1881.     {
  1882.         if (is_string($type)) {
  1883.             $type = Type::getType($type);
  1884.         }
  1886.         if ($type instanceof Type) {
  1887.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1888.             $bindingType = $type->getBindingType();
  1889.         } else {
  1890.             $bindingType = $type ?? ParameterType::STRING;
  1891.         }
  1893.         return [$value, $bindingType];
  1894.     }
  1896.     /**
  1897.      * Creates a new instance of a SQL query builder.
  1898.      *
  1899.      * @return QueryBuilder
  1900.      */
  1901.     public function createQueryBuilder()
  1902.     {
  1903.         return new Query\QueryBuilder($this);
  1904.     }
  1906.     /**
  1907.      * @internal
  1908.      *
  1909.      * @param list<mixed>|array<string, mixed>                                     $params
  1910.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1911.      */
  1912.     final public function convertExceptionDuringQuery(
  1913.         Driver\Exception $e,
  1914.         string $sql,
  1915.         array $params = [],
  1916.         array $types = []
  1917.     ): DriverException {
  1918.         return $this->handleDriverException($e, new Query($sql, $params, $types));
  1919.     }
  1921.     /** @internal */
  1922.     final public function convertException(Driver\Exception $e): DriverException
  1923.     {
  1924.         return $this->handleDriverException($e, null);
  1925.     }
  1927.     /**
  1928.      * @param array<int, mixed>|array<string, mixed>                               $params
  1929.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1930.      *
  1931.      * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1932.      */
  1933.     private function expandArrayParameters(string $sql, array $params, array $types): array
  1934.     {
  1935.         $this->parser ??= $this->getDatabasePlatform()->createSQLParser();
  1936.         $visitor        = new ExpandArrayParameters($params, $types);
  1938.         $this->parser->parse($sql, $visitor);
  1940.         return [
  1941.             $visitor->getSQL(),
  1942.             $visitor->getParameters(),
  1943.             $visitor->getTypes(),
  1944.         ];
  1945.     }
  1947.     /**
  1948.      * @param array<int, mixed>|array<string, mixed>                               $params
  1949.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1950.      */
  1951.     private function needsArrayParameterConversion(array $params, array $types): bool
  1952.     {
  1953.         if (is_string(key($params))) {
  1954.             return true;
  1955.         }
  1957.         foreach ($types as $type) {
  1958.             if (
  1959.                 $type === ArrayParameterType::INTEGER
  1960.                 || $type === ArrayParameterType::STRING
  1961.                 || $type === ArrayParameterType::ASCII
  1962.                 || $type === ArrayParameterType::BINARY
  1963.             ) {
  1964.                 return true;
  1965.             }
  1966.         }
  1968.         return false;
  1969.     }
  1971.     private function handleDriverException(
  1972.         Driver\Exception $driverException,
  1973.         ?Query $query
  1974.     ): DriverException {
  1975.         $this->exceptionConverter ??= $this->_driver->getExceptionConverter();
  1976.         $exception                  = $this->exceptionConverter->convert($driverException, $query);
  1978.         if ($exception instanceof ConnectionLost) {
  1979.             $this->close();
  1980.         }
  1982.         return $exception;
  1983.     }
  1985.     /**
  1986.      * BC layer for a wide-spread use-case of old DBAL APIs
  1987.      *
  1988.      * @deprecated Use {@see executeStatement()} instead
  1989.      *
  1990.      * @param array<mixed>           $params The query parameters
  1991.      * @param array<int|string|null> $types  The parameter types
  1992.      */
  1993.     public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1994.     {
  1995.         Deprecation::trigger(
  1996.             'doctrine/dbal',
  1997.             'https://github.com/doctrine/dbal/pull/4163',
  1998.             '%s is deprecated, please use executeStatement() instead.',
  1999.             __METHOD__,
  2000.         );
  2002.         return $this->executeStatement($sql, $params, $types);
  2003.     }
  2005.     /**
  2006.      * BC layer for a wide-spread use-case of old DBAL APIs
  2007.      *
  2008.      * @deprecated Use {@see executeQuery()} instead
  2009.      */
  2010.     public function query(string $sql): Result
  2011.     {
  2012.         Deprecation::trigger(
  2013.             'doctrine/dbal',
  2014.             'https://github.com/doctrine/dbal/pull/4163',
  2015.             '%s is deprecated, please use executeQuery() instead.',
  2016.             __METHOD__,
  2017.         );
  2019.         return $this->executeQuery($sql);
  2020.     }
  2022.     /**
  2023.      * BC layer for a wide-spread use-case of old DBAL APIs
  2024.      *
  2025.      * @deprecated please use {@see executeStatement()} instead
  2026.      */
  2027.     public function exec(string $sql): int
  2028.     {
  2029.         Deprecation::trigger(
  2030.             'doctrine/dbal',
  2031.             'https://github.com/doctrine/dbal/pull/4163',
  2032.             '%s is deprecated, please use executeStatement() instead.',
  2033.             __METHOD__,
  2034.         );
  2036.         return $this->executeStatement($sql);
  2037.     }
  2038. }