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

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\SQL\Parser;
  25. use Doctrine\DBAL\Types\Type;
  26. use Doctrine\Deprecations\Deprecation;
  27. use LogicException;
  28. use Throwable;
  29. use Traversable;
  31. use function array_key_exists;
  32. use function assert;
  33. use function count;
  34. use function get_class;
  35. use function implode;
  36. use function is_int;
  37. use function is_string;
  38. use function key;
  39. use function method_exists;
  40. use function sprintf;
  42. /**
  43.  * A database abstraction-level connection that implements features like events, transaction isolation levels,
  44.  * configuration, emulated transaction nesting, lazy connecting and more.
  45.  *
  46.  * @psalm-import-type Params from DriverManager
  47.  * @psalm-consistent-constructor
  48.  */
  49. class Connection
  50. {
  51.     /**
  52.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  53.      */
  54.     public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  56.     /**
  57.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  58.      */
  59.     public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  61.     /**
  62.      * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
  63.      */
  64.     public const PARAM_ASCII_STR_ARRAY = ParameterType::ASCII + self::ARRAY_PARAM_OFFSET;
  66.     /**
  67.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  68.      *
  69.      * @internal Should be used only within the wrapper layer.
  70.      */
  71.     public const ARRAY_PARAM_OFFSET = 100;
  73.     /**
  74.      * The wrapped driver connection.
  75.      *
  76.      * @var \Doctrine\DBAL\Driver\Connection|null
  77.      */
  78.     protected $_conn;
  80.     /** @var Configuration */
  81.     protected $_config;
  83.     /**
  84.      * @deprecated
  85.      *
  86.      * @var EventManager
  87.      */
  88.     protected $_eventManager;
  90.     /**
  91.      * @deprecated Use {@see createExpressionBuilder()} instead.
  92.      *
  93.      * @var ExpressionBuilder
  94.      */
  95.     protected $_expr;
  97.     /**
  98.      * The current auto-commit mode of this connection.
  99.      */
  100.     private bool $autoCommit = true;
  102.     /**
  103.      * The transaction nesting level.
  104.      */
  105.     private int $transactionNestingLevel = 0;
  107.     /**
  108.      * The currently active transaction isolation level or NULL before it has been determined.
  109.      *
  110.      * @var TransactionIsolationLevel::*|null
  111.      */
  112.     private $transactionIsolationLevel;
  114.     /**
  115.      * If nested transactions should use savepoints.
  116.      */
  117.     private bool $nestTransactionsWithSavepoints = false;
  119.     /**
  120.      * The parameters used during creation of the Connection instance.
  121.      *
  122.      * @var array<string,mixed>
  123.      * @psalm-var Params
  124.      */
  125.     private array $params;
  127.     /**
  128.      * The database platform object used by the connection or NULL before it's initialized.
  129.      */
  130.     private ?AbstractPlatform $platform = null;
  132.     private ?ExceptionConverter $exceptionConverter = null;
  133.     private ?Parser $parser                         = null;
  135.     /**
  136.      * The schema manager.
  137.      *
  138.      * @deprecated Use {@see createSchemaManager()} instead.
  139.      *
  140.      * @var AbstractSchemaManager|null
  141.      */
  142.     protected $_schemaManager;
  144.     /**
  145.      * The used DBAL driver.
  146.      *
  147.      * @var Driver
  148.      */
  149.     protected $_driver;
  151.     /**
  152.      * Flag that indicates whether the current transaction is marked for rollback only.
  153.      */
  154.     private bool $isRollbackOnly = false;
  156.     /**
  157.      * Initializes a new instance of the Connection class.
  158.      *
  159.      * @internal The connection can be only instantiated by the driver manager.
  160.      *
  161.      * @param array<string,mixed> $params       The connection parameters.
  162.      * @param Driver              $driver       The driver to use.
  163.      * @param Configuration|null  $config       The configuration, optional.
  164.      * @param EventManager|null   $eventManager The event manager, optional.
  165.      * @psalm-param Params $params
  166.      * @phpstan-param array<string,mixed> $params
  167.      *
  168.      * @throws Exception
  169.      */
  170.     public function __construct(
  171.         array $params,
  172.         Driver $driver,
  173.         ?Configuration $config = null,
  174.         ?EventManager $eventManager = null
  175.     ) {
  176.         $this->_driver = $driver;
  177.         $this->params  = $params;
  179.         // Create default config and event manager if none given
  180.         $config       ??= new Configuration();
  181.         $eventManager ??= new EventManager();
  183.         $this->_config       = $config;
  184.         $this->_eventManager = $eventManager;
  186.         if (isset($params['platform'])) {
  187.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  188.                 throw Exception::invalidPlatformType($params['platform']);
  189.             }
  191.             Deprecation::trigger(
  192.                 'doctrine/dbal',
  193.                 'https://github.com/doctrine/dbal/pull/5699',
  194.                 'The "platform" connection parameter is deprecated.'
  195.                     . ' Use a driver middleware that would instantiate the platform instead.',
  196.             );
  198.             $this->platform = $params['platform'];
  199.             $this->platform->setEventManager($this->_eventManager);
  200.         }
  202.         $this->_expr = $this->createExpressionBuilder();
  204.         $this->autoCommit = $config->getAutoCommit();
  205.     }
  207.     /**
  208.      * Gets the parameters used during instantiation.
  209.      *
  210.      * @internal
  211.      *
  212.      * @return array<string,mixed>
  213.      * @psalm-return Params
  214.      */
  215.     public function getParams()
  216.     {
  217.         return $this->params;
  218.     }
  220.     /**
  221.      * Gets the name of the currently selected database.
  222.      *
  223.      * @return string|null The name of the database or NULL if a database is not selected.
  224.      *                     The platforms which don't support the concept of a database (e.g. embedded databases)
  225.      *                     must always return a string as an indicator of an implicitly selected database.
  226.      *
  227.      * @throws Exception
  228.      */
  229.     public function getDatabase()
  230.     {
  231.         $platform = $this->getDatabasePlatform();
  232.         $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  233.         $database = $this->fetchOne($query);
  235.         assert(is_string($database) || $database === null);
  237.         return $database;
  238.     }
  240.     /**
  241.      * Gets the DBAL driver instance.
  242.      *
  243.      * @return Driver
  244.      */
  245.     public function getDriver()
  246.     {
  247.         return $this->_driver;
  248.     }
  250.     /**
  251.      * Gets the Configuration used by the Connection.
  252.      *
  253.      * @return Configuration
  254.      */
  255.     public function getConfiguration()
  256.     {
  257.         return $this->_config;
  258.     }
  260.     /**
  261.      * Gets the EventManager used by the Connection.
  262.      *
  263.      * @deprecated
  264.      *
  265.      * @return EventManager
  266.      */
  267.     public function getEventManager()
  268.     {
  269.         Deprecation::triggerIfCalledFromOutside(
  270.             'doctrine/dbal',
  271.             'https://github.com/doctrine/dbal/issues/5784',
  272.             '%s is deprecated.',
  273.             __METHOD__,
  274.         );
  276.         return $this->_eventManager;
  277.     }
  279.     /**
  280.      * Gets the DatabasePlatform for the connection.
  281.      *
  282.      * @return AbstractPlatform
  283.      *
  284.      * @throws Exception
  285.      */
  286.     public function getDatabasePlatform()
  287.     {
  288.         if ($this->platform === null) {
  289.             $this->platform = $this->detectDatabasePlatform();
  290.             $this->platform->setEventManager($this->_eventManager);
  291.         }
  293.         return $this->platform;
  294.     }
  296.     /**
  297.      * Creates an expression builder for the connection.
  298.      */
  299.     public function createExpressionBuilder(): ExpressionBuilder
  300.     {
  301.         return new ExpressionBuilder($this);
  302.     }
  304.     /**
  305.      * Gets the ExpressionBuilder for the connection.
  306.      *
  307.      * @deprecated Use {@see createExpressionBuilder()} instead.
  308.      *
  309.      * @return ExpressionBuilder
  310.      */
  311.     public function getExpressionBuilder()
  312.     {
  313.         Deprecation::triggerIfCalledFromOutside(
  314.             'doctrine/dbal',
  315.             'https://github.com/doctrine/dbal/issues/4515',
  316.             'Connection::getExpressionBuilder() is deprecated,'
  317.                 . ' use Connection::createExpressionBuilder() instead.',
  318.         );
  320.         return $this->_expr;
  321.     }
  323.     /**
  324.      * Establishes the connection with the database.
  325.      *
  326.      * @internal This method will be made protected in DBAL 4.0.
  327.      *
  328.      * @return bool TRUE if the connection was successfully established, FALSE if
  329.      *              the connection is already open.
  330.      *
  331.      * @throws Exception
  332.      */
  333.     public function connect()
  334.     {
  335.         Deprecation::triggerIfCalledFromOutside(
  336.             'doctrine/dbal',
  337.             'https://github.com/doctrine/dbal/issues/4966',
  338.             'Public access to Connection::connect() is deprecated.',
  339.         );
  341.         if ($this->_conn !== null) {
  342.             return false;
  343.         }
  345.         try {
  346.             $this->_conn = $this->_driver->connect($this->params);
  347.         } catch (Driver\Exception $e) {
  348.             throw $this->convertException($e);
  349.         }
  351.         if ($this->autoCommit === false) {
  352.             $this->beginTransaction();
  353.         }
  355.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  356.             Deprecation::trigger(
  357.                 'doctrine/dbal',
  358.                 'https://github.com/doctrine/dbal/issues/5784',
  359.                 'Subscribing to %s events is deprecated. Implement a middleware instead.',
  360.                 Events::postConnect,
  361.             );
  363.             $eventArgs = new Event\ConnectionEventArgs($this);
  364.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  365.         }
  367.         return true;
  368.     }
  370.     /**
  371.      * Detects and sets the database platform.
  372.      *
  373.      * Evaluates custom platform class and version in order to set the correct platform.
  374.      *
  375.      * @throws Exception If an invalid platform was specified for this connection.
  376.      */
  377.     private function detectDatabasePlatform(): AbstractPlatform
  378.     {
  379.         $version = $this->getDatabasePlatformVersion();
  381.         if ($version !== null) {
  382.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  384.             return $this->_driver->createDatabasePlatformForVersion($version);
  385.         }
  387.         return $this->_driver->getDatabasePlatform();
  388.     }
  390.     /**
  391.      * Returns the version of the related platform if applicable.
  392.      *
  393.      * Returns null if either the driver is not capable to create version
  394.      * specific platform instances, no explicit server version was specified
  395.      * or the underlying driver connection cannot determine the platform
  396.      * version without having to query it (performance reasons).
  397.      *
  398.      * @return string|null
  399.      *
  400.      * @throws Throwable
  401.      */
  402.     private function getDatabasePlatformVersion()
  403.     {
  404.         // Driver does not support version specific platforms.
  405.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  406.             return null;
  407.         }
  409.         // Explicit platform version requested (supersedes auto-detection).
  410.         if (isset($this->params['serverVersion'])) {
  411.             return $this->params['serverVersion'];
  412.         }
  414.         // If not connected, we need to connect now to determine the platform version.
  415.         if ($this->_conn === null) {
  416.             try {
  417.                 $this->connect();
  418.             } catch (Exception $originalException) {
  419.                 if (! isset($this->params['dbname'])) {
  420.                     throw $originalException;
  421.                 }
  423.                 Deprecation::trigger(
  424.                     'doctrine/dbal',
  425.                     'https://github.com/doctrine/dbal/pull/5707',
  426.                     'Relying on a fallback connection used to determine the database platform while connecting'
  427.                         . ' to a non-existing database is deprecated. Either use an existing database name in'
  428.                         . ' connection parameters or omit the database name if the platform'
  429.                         . ' and the server configuration allow that.',
  430.                 );
  432.                 // The database to connect to might not yet exist.
  433.                 // Retry detection without database name connection parameter.
  434.                 $params = $this->params;
  436.                 unset($this->params['dbname']);
  438.                 try {
  439.                     $this->connect();
  440.                 } catch (Exception $fallbackException) {
  441.                     // Either the platform does not support database-less connections
  442.                     // or something else went wrong.
  443.                     throw $originalException;
  444.                 } finally {
  445.                     $this->params = $params;
  446.                 }
  448.                 $serverVersion = $this->getServerVersion();
  450.                 // Close "temporary" connection to allow connecting to the real database again.
  451.                 $this->close();
  453.                 return $serverVersion;
  454.             }
  455.         }
  457.         return $this->getServerVersion();
  458.     }
  460.     /**
  461.      * Returns the database server version if the underlying driver supports it.
  462.      *
  463.      * @return string|null
  464.      *
  465.      * @throws Exception
  466.      */
  467.     private function getServerVersion()
  468.     {
  469.         $connection = $this->getWrappedConnection();
  471.         // Automatic platform version detection.
  472.         if ($connection instanceof ServerInfoAwareConnection) {
  473.             try {
  474.                 return $connection->getServerVersion();
  475.             } catch (Driver\Exception $e) {
  476.                 throw $this->convertException($e);
  477.             }
  478.         }
  480.         Deprecation::trigger(
  481.             'doctrine/dbal',
  482.             'https://github.com/doctrine/dbal/pull/4750',
  483.             'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  484.             get_class($connection),
  485.         );
  487.         // Unable to detect platform version.
  488.         return null;
  489.     }
  491.     /**
  492.      * Returns the current auto-commit mode for this connection.
  493.      *
  494.      * @see    setAutoCommit
  495.      *
  496.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  497.      */
  498.     public function isAutoCommit()
  499.     {
  500.         return $this->autoCommit === true;
  501.     }
  503.     /**
  504.      * Sets auto-commit mode for this connection.
  505.      *
  506.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  507.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  508.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  509.      *
  510.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  511.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  512.      *
  513.      * @see   isAutoCommit
  514.      *
  515.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  516.      *
  517.      * @return void
  518.      */
  519.     public function setAutoCommit($autoCommit)
  520.     {
  521.         $autoCommit = (bool) $autoCommit;
  523.         // Mode not changed, no-op.
  524.         if ($autoCommit === $this->autoCommit) {
  525.             return;
  526.         }
  528.         $this->autoCommit = $autoCommit;
  530.         // Commit all currently active transactions if any when switching auto-commit mode.
  531.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  532.             return;
  533.         }
  535.         $this->commitAll();
  536.     }
  538.     /**
  539.      * Prepares and executes an SQL query and returns the first row of the result
  540.      * as an associative array.
  541.      *
  542.      * @param string                                                               $query  SQL query
  543.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  544.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  545.      *
  546.      * @return array<string, mixed>|false False is returned if no rows are found.
  547.      *
  548.      * @throws Exception
  549.      */
  550.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  551.     {
  552.         return $this->executeQuery($query, $params, $types)->fetchAssociative();
  553.     }
  555.     /**
  556.      * Prepares and executes an SQL query and returns the first row of the result
  557.      * as a numerically indexed array.
  558.      *
  559.      * @param string                                                               $query  SQL query
  560.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  561.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  562.      *
  563.      * @return list<mixed>|false False is returned if no rows are found.
  564.      *
  565.      * @throws Exception
  566.      */
  567.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  568.     {
  569.         return $this->executeQuery($query, $params, $types)->fetchNumeric();
  570.     }
  572.     /**
  573.      * Prepares and executes an SQL query and returns the value of a single column
  574.      * of the first row of the result.
  575.      *
  576.      * @param string                                                               $query  SQL query
  577.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  578.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  579.      *
  580.      * @return mixed|false False is returned if no rows are found.
  581.      *
  582.      * @throws Exception
  583.      */
  584.     public function fetchOne(string $query, array $params = [], array $types = [])
  585.     {
  586.         return $this->executeQuery($query, $params, $types)->fetchOne();
  587.     }
  589.     /**
  590.      * Whether an actual connection to the database is established.
  591.      *
  592.      * @return bool
  593.      */
  594.     public function isConnected()
  595.     {
  596.         return $this->_conn !== null;
  597.     }
  599.     /**
  600.      * Checks whether a transaction is currently active.
  601.      *
  602.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  603.      */
  604.     public function isTransactionActive()
  605.     {
  606.         return $this->transactionNestingLevel > 0;
  607.     }
  609.     /**
  610.      * Adds condition based on the criteria to the query components
  611.      *
  612.      * @param array<string,mixed> $criteria   Map of key columns to their values
  613.      * @param string[]            $columns    Column names
  614.      * @param mixed[]             $values     Column values
  615.      * @param string[]            $conditions Key conditions
  616.      *
  617.      * @throws Exception
  618.      */
  619.     private function addCriteriaCondition(
  620.         array $criteria,
  621.         array &$columns,
  622.         array &$values,
  623.         array &$conditions
  624.     ): void {
  625.         $platform = $this->getDatabasePlatform();
  627.         foreach ($criteria as $columnName => $value) {
  628.             if ($value === null) {
  629.                 $conditions[] = $platform->getIsNullExpression($columnName);
  630.                 continue;
  631.             }
  633.             $columns[]    = $columnName;
  634.             $values[]     = $value;
  635.             $conditions[] = $columnName . ' = ?';
  636.         }
  637.     }
  639.     /**
  640.      * Executes an SQL DELETE statement on a table.
  641.      *
  642.      * Table expression and columns are not escaped and are not safe for user-input.
  643.      *
  644.      * @param string                                                               $table    Table name
  645.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  646.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  647.      *
  648.      * @return int|string The number of affected rows.
  649.      *
  650.      * @throws Exception
  651.      */
  652.     public function delete($table, array $criteria, array $types = [])
  653.     {
  654.         if (count($criteria) === 0) {
  655.             throw InvalidArgumentException::fromEmptyCriteria();
  656.         }
  658.         $columns = $values = $conditions = [];
  660.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  662.         return $this->executeStatement(
  663.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  664.             $values,
  665.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  666.         );
  667.     }
  669.     /**
  670.      * Closes the connection.
  671.      *
  672.      * @return void
  673.      */
  674.     public function close()
  675.     {
  676.         $this->_conn                   = null;
  677.         $this->transactionNestingLevel = 0;
  678.     }
  680.     /**
  681.      * Sets the transaction isolation level.
  682.      *
  683.      * @param TransactionIsolationLevel::* $level The level to set.
  684.      *
  685.      * @return int|string
  686.      *
  687.      * @throws Exception
  688.      */
  689.     public function setTransactionIsolation($level)
  690.     {
  691.         $this->transactionIsolationLevel = $level;
  693.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  694.     }
  696.     /**
  697.      * Gets the currently active transaction isolation level.
  698.      *
  699.      * @return TransactionIsolationLevel::* The current transaction isolation level.
  700.      *
  701.      * @throws Exception
  702.      */
  703.     public function getTransactionIsolation()
  704.     {
  705.         return $this->transactionIsolationLevel ??= $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  706.     }
  708.     /**
  709.      * Executes an SQL UPDATE statement on a table.
  710.      *
  711.      * Table expression and columns are not escaped and are not safe for user-input.
  712.      *
  713.      * @param string                                                               $table    Table name
  714.      * @param array<string, mixed>                                                 $data     Column-value pairs
  715.      * @param array<string, mixed>                                                 $criteria Update criteria
  716.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  717.      *
  718.      * @return int|string The number of affected rows.
  719.      *
  720.      * @throws Exception
  721.      */
  722.     public function update($table, array $data, array $criteria, array $types = [])
  723.     {
  724.         $columns = $values = $conditions = $set = [];
  726.         foreach ($data as $columnName => $value) {
  727.             $columns[] = $columnName;
  728.             $values[]  = $value;
  729.             $set[]     = $columnName . ' = ?';
  730.         }
  732.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  734.         if (is_string(key($types))) {
  735.             $types = $this->extractTypeValues($columns, $types);
  736.         }
  738.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  739.                 . ' WHERE ' . implode(' AND ', $conditions);
  741.         return $this->executeStatement($sql, $values, $types);
  742.     }
  744.     /**
  745.      * Inserts a table row with specified data.
  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<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  752.      *
  753.      * @return int|string The number of affected rows.
  754.      *
  755.      * @throws Exception
  756.      */
  757.     public function insert($table, array $data, array $types = [])
  758.     {
  759.         if (count($data) === 0) {
  760.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  761.         }
  763.         $columns = [];
  764.         $values  = [];
  765.         $set     = [];
  767.         foreach ($data as $columnName => $value) {
  768.             $columns[] = $columnName;
  769.             $values[]  = $value;
  770.             $set[]     = '?';
  771.         }
  773.         return $this->executeStatement(
  774.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  775.             ' VALUES (' . implode(', ', $set) . ')',
  776.             $values,
  777.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types,
  778.         );
  779.     }
  781.     /**
  782.      * Extract ordered type list from an ordered column list and type map.
  783.      *
  784.      * @param array<int, string>                                                   $columnList
  785.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  786.      *
  787.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  788.      */
  789.     private function extractTypeValues(array $columnList, array $types): array
  790.     {
  791.         $typeValues = [];
  793.         foreach ($columnList as $columnName) {
  794.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  795.         }
  797.         return $typeValues;
  798.     }
  800.     /**
  801.      * Quotes a string so it can be safely used as a table or column name, even if
  802.      * it is a reserved name.
  803.      *
  804.      * Delimiting style depends on the underlying database platform that is being used.
  805.      *
  806.      * NOTE: Just because you CAN use quoted identifiers does not mean
  807.      * you SHOULD use them. In general, they end up causing way more
  808.      * problems than they solve.
  809.      *
  810.      * @param string $str The name to be quoted.
  811.      *
  812.      * @return string The quoted name.
  813.      */
  814.     public function quoteIdentifier($str)
  815.     {
  816.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  817.     }
  819.     /**
  820.      * The usage of this method is discouraged. Use prepared statements
  821.      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  822.      *
  823.      * @param mixed                $value
  824.      * @param int|string|Type|null $type
  825.      *
  826.      * @return mixed
  827.      */
  828.     public function quote($value, $type = ParameterType::STRING)
  829.     {
  830.         $connection = $this->getWrappedConnection();
  832.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  834.         return $connection->quote($value, $bindingType);
  835.     }
  837.     /**
  838.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  839.      *
  840.      * @param string                                                               $query  SQL query
  841.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  842.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  843.      *
  844.      * @return list<list<mixed>>
  845.      *
  846.      * @throws Exception
  847.      */
  848.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  849.     {
  850.         return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  851.     }
  853.     /**
  854.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  855.      *
  856.      * @param string                                                               $query  SQL query
  857.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  858.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  859.      *
  860.      * @return list<array<string,mixed>>
  861.      *
  862.      * @throws Exception
  863.      */
  864.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  865.     {
  866.         return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  867.     }
  869.     /**
  870.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  871.      * mapped to the first column and the values mapped to the second column.
  872.      *
  873.      * @param string                                                               $query  SQL query
  874.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  875.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  876.      *
  877.      * @return array<mixed,mixed>
  878.      *
  879.      * @throws Exception
  880.      */
  881.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  882.     {
  883.         return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  884.     }
  886.     /**
  887.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  888.      * to the first column and the values being an associative array representing the rest of the columns
  889.      * and their values.
  890.      *
  891.      * @param string                                                               $query  SQL query
  892.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  893.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  894.      *
  895.      * @return array<mixed,array<string,mixed>>
  896.      *
  897.      * @throws Exception
  898.      */
  899.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  900.     {
  901.         return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  902.     }
  904.     /**
  905.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  906.      *
  907.      * @param string                                                               $query  SQL query
  908.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  909.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  910.      *
  911.      * @return list<mixed>
  912.      *
  913.      * @throws Exception
  914.      */
  915.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  916.     {
  917.         return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  918.     }
  920.     /**
  921.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  922.      *
  923.      * @param string                                                               $query  SQL query
  924.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  925.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  926.      *
  927.      * @return Traversable<int,list<mixed>>
  928.      *
  929.      * @throws Exception
  930.      */
  931.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  932.     {
  933.         return $this->executeQuery($query, $params, $types)->iterateNumeric();
  934.     }
  936.     /**
  937.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  938.      * as associative arrays.
  939.      *
  940.      * @param string                                                               $query  SQL query
  941.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  942.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  943.      *
  944.      * @return Traversable<int,array<string,mixed>>
  945.      *
  946.      * @throws Exception
  947.      */
  948.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  949.     {
  950.         return $this->executeQuery($query, $params, $types)->iterateAssociative();
  951.     }
  953.     /**
  954.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  955.      * mapped to the first column and the values mapped to the second column.
  956.      *
  957.      * @param string                                                               $query  SQL query
  958.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  959.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  960.      *
  961.      * @return Traversable<mixed,mixed>
  962.      *
  963.      * @throws Exception
  964.      */
  965.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  966.     {
  967.         return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  968.     }
  970.     /**
  971.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  972.      * to the first column and the values being an associative array representing the rest of the columns
  973.      * and their values.
  974.      *
  975.      * @param string                                           $query  SQL query
  976.      * @param list<mixed>|array<string, mixed>                 $params Query parameters
  977.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  978.      *
  979.      * @return Traversable<mixed,array<string,mixed>>
  980.      *
  981.      * @throws Exception
  982.      */
  983.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  984.     {
  985.         return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  986.     }
  988.     /**
  989.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  990.      *
  991.      * @param string                                                               $query  SQL query
  992.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  993.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  994.      *
  995.      * @return Traversable<int,mixed>
  996.      *
  997.      * @throws Exception
  998.      */
  999.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1000.     {
  1001.         return $this->executeQuery($query, $params, $types)->iterateColumn();
  1002.     }
  1004.     /**
  1005.      * Prepares an SQL statement.
  1006.      *
  1007.      * @param string $sql The SQL statement to prepare.
  1008.      *
  1009.      * @throws Exception
  1010.      */
  1011.     public function prepare(string $sql): Statement
  1012.     {
  1013.         $connection = $this->getWrappedConnection();
  1015.         try {
  1016.             $statement = $connection->prepare($sql);
  1017.         } catch (Driver\Exception $e) {
  1018.             throw $this->convertExceptionDuringQuery($e, $sql);
  1019.         }
  1021.         return new Statement($this, $statement, $sql);
  1022.     }
  1024.     /**
  1025.      * Executes an, optionally parametrized, SQL query.
  1026.      *
  1027.      * If the query is parametrized, a prepared statement is used.
  1028.      * If an SQLLogger is configured, the execution is logged.
  1029.      *
  1030.      * @param string                                                               $sql    SQL query
  1031.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1032.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1033.      *
  1034.      * @throws Exception
  1035.      */
  1036.     public function executeQuery(
  1037.         string $sql,
  1038.         array $params = [],
  1039.         $types = [],
  1040.         ?QueryCacheProfile $qcp = null
  1041.     ): Result {
  1042.         if ($qcp !== null) {
  1043.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1044.         }
  1046.         $connection = $this->getWrappedConnection();
  1048.         $logger = $this->_config->getSQLLogger();
  1049.         if ($logger !== null) {
  1050.             $logger->startQuery($sql, $params, $types);
  1051.         }
  1053.         try {
  1054.             if (count($params) > 0) {
  1055.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1056.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1057.                 }
  1059.                 $stmt = $connection->prepare($sql);
  1061.                 $this->bindParameters($stmt, $params, $types);
  1063.                 $result = $stmt->execute();
  1064.             } else {
  1065.                 $result = $connection->query($sql);
  1066.             }
  1068.             return new Result($result, $this);
  1069.         } catch (Driver\Exception $e) {
  1070.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1071.         } finally {
  1072.             if ($logger !== null) {
  1073.                 $logger->stopQuery();
  1074.             }
  1075.         }
  1076.     }
  1078.     /**
  1079.      * Executes a caching query.
  1080.      *
  1081.      * @param string                                                               $sql    SQL query
  1082.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1083.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1084.      *
  1085.      * @throws CacheException
  1086.      * @throws Exception
  1087.      */
  1088.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1089.     {
  1090.         $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1092.         if ($resultCache === null) {
  1093.             throw CacheException::noResultDriverConfigured();
  1094.         }
  1096.         $connectionParams = $this->params;
  1097.         unset($connectionParams['platform']);
  1099.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1101.         $item = $resultCache->getItem($cacheKey);
  1103.         if ($item->isHit()) {
  1104.             $value = $item->get();
  1105.             if (isset($value[$realKey])) {
  1106.                 return new Result(new ArrayResult($value[$realKey]), $this);
  1107.             }
  1108.         } else {
  1109.             $value = [];
  1110.         }
  1112.         $data = $this->fetchAllAssociative($sql, $params, $types);
  1114.         $value[$realKey] = $data;
  1116.         $item->set($value);
  1118.         $lifetime = $qcp->getLifetime();
  1119.         if ($lifetime > 0) {
  1120.             $item->expiresAfter($lifetime);
  1121.         }
  1123.         $resultCache->save($item);
  1125.         return new Result(new ArrayResult($data), $this);
  1126.     }
  1128.     /**
  1129.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1130.      *
  1131.      * Could be used for:
  1132.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1133.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1134.      *  - DCL statements: GRANT, REVOKE, etc.
  1135.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1136.      *  - Other statements that don't yield a row set.
  1137.      *
  1138.      * This method supports PDO binding types as well as DBAL mapping types.
  1139.      *
  1140.      * @param string                                                               $sql    SQL statement
  1141.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1142.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1143.      *
  1144.      * @return int|string The number of affected rows.
  1145.      *
  1146.      * @throws Exception
  1147.      */
  1148.     public function executeStatement($sql, array $params = [], array $types = [])
  1149.     {
  1150.         $connection = $this->getWrappedConnection();
  1152.         $logger = $this->_config->getSQLLogger();
  1153.         if ($logger !== null) {
  1154.             $logger->startQuery($sql, $params, $types);
  1155.         }
  1157.         try {
  1158.             if (count($params) > 0) {
  1159.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1160.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1161.                 }
  1163.                 $stmt = $connection->prepare($sql);
  1165.                 $this->bindParameters($stmt, $params, $types);
  1167.                 return $stmt->execute()
  1168.                     ->rowCount();
  1169.             }
  1171.             return $connection->exec($sql);
  1172.         } catch (Driver\Exception $e) {
  1173.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1174.         } finally {
  1175.             if ($logger !== null) {
  1176.                 $logger->stopQuery();
  1177.             }
  1178.         }
  1179.     }
  1181.     /**
  1182.      * Returns the current transaction nesting level.
  1183.      *
  1184.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1185.      */
  1186.     public function getTransactionNestingLevel()
  1187.     {
  1188.         return $this->transactionNestingLevel;
  1189.     }
  1191.     /**
  1192.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1193.      * depending on the underlying driver.
  1194.      *
  1195.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1196.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1197.      * columns or sequences.
  1198.      *
  1199.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1200.      *
  1201.      * @return string|int|false A string representation of the last inserted ID.
  1202.      *
  1203.      * @throws Exception
  1204.      */
  1205.     public function lastInsertId($name = null)
  1206.     {
  1207.         if ($name !== null) {
  1208.             Deprecation::trigger(
  1209.                 'doctrine/dbal',
  1210.                 'https://github.com/doctrine/dbal/issues/4687',
  1211.                 'The usage of Connection::lastInsertId() with a sequence name is deprecated.',
  1212.             );
  1213.         }
  1215.         try {
  1216.             return $this->getWrappedConnection()->lastInsertId($name);
  1217.         } catch (Driver\Exception $e) {
  1218.             throw $this->convertException($e);
  1219.         }
  1220.     }
  1222.     /**
  1223.      * Executes a function in a transaction.
  1224.      *
  1225.      * The function gets passed this Connection instance as an (optional) parameter.
  1226.      *
  1227.      * If an exception occurs during execution of the function or transaction commit,
  1228.      * the transaction is rolled back and the exception re-thrown.
  1229.      *
  1230.      * @param Closure(self):T $func The function to execute transactionally.
  1231.      *
  1232.      * @return T The value returned by $func
  1233.      *
  1234.      * @throws Throwable
  1235.      *
  1236.      * @template T
  1237.      */
  1238.     public function transactional(Closure $func)
  1239.     {
  1240.         $this->beginTransaction();
  1241.         try {
  1242.             $res = $func($this);
  1243.             $this->commit();
  1245.             return $res;
  1246.         } catch (Throwable $e) {
  1247.             $this->rollBack();
  1249.             throw $e;
  1250.         }
  1251.     }
  1253.     /**
  1254.      * Sets if nested transactions should use savepoints.
  1255.      *
  1256.      * @param bool $nestTransactionsWithSavepoints
  1257.      *
  1258.      * @return void
  1259.      *
  1260.      * @throws Exception
  1261.      */
  1262.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1263.     {
  1264.         if (! $nestTransactionsWithSavepoints) {
  1265.             Deprecation::trigger(
  1266.                 'doctrine/dbal',
  1267.                 'https://github.com/doctrine/dbal/pull/5383',
  1268.                 <<<'DEPRECATION'
  1269.                 Nesting transactions without enabling savepoints is deprecated.
  1270.                 Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1271.                 DEPRECATION,
  1272.                 self::class,
  1273.             );
  1274.         }
  1276.         if ($this->transactionNestingLevel > 0) {
  1277.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1278.         }
  1280.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1281.             throw ConnectionException::savepointsNotSupported();
  1282.         }
  1284.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1285.     }
  1287.     /**
  1288.      * Gets if nested transactions should use savepoints.
  1289.      *
  1290.      * @return bool
  1291.      */
  1292.     public function getNestTransactionsWithSavepoints()
  1293.     {
  1294.         return $this->nestTransactionsWithSavepoints;
  1295.     }
  1297.     /**
  1298.      * Returns the savepoint name to use for nested transactions.
  1299.      *
  1300.      * @return string
  1301.      */
  1302.     protected function _getNestedTransactionSavePointName()
  1303.     {
  1304.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1305.     }
  1307.     /**
  1308.      * @return bool
  1309.      *
  1310.      * @throws Exception
  1311.      */
  1312.     public function beginTransaction()
  1313.     {
  1314.         $connection = $this->getWrappedConnection();
  1316.         ++$this->transactionNestingLevel;
  1318.         $logger = $this->_config->getSQLLogger();
  1320.         if ($this->transactionNestingLevel === 1) {
  1321.             if ($logger !== null) {
  1322.                 $logger->startQuery('"START TRANSACTION"');
  1323.             }
  1325.             $connection->beginTransaction();
  1327.             if ($logger !== null) {
  1328.                 $logger->stopQuery();
  1329.             }
  1330.         } elseif ($this->nestTransactionsWithSavepoints) {
  1331.             if ($logger !== null) {
  1332.                 $logger->startQuery('"SAVEPOINT"');
  1333.             }
  1335.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1336.             if ($logger !== null) {
  1337.                 $logger->stopQuery();
  1338.             }
  1339.         } else {
  1340.             Deprecation::trigger(
  1341.                 'doctrine/dbal',
  1342.                 'https://github.com/doctrine/dbal/pull/5383',
  1343.                 <<<'DEPRECATION'
  1344.                 Nesting transactions without enabling savepoints is deprecated.
  1345.                 Call %s::setNestTransactionsWithSavepoints(true) to enable savepoints.
  1346.                 DEPRECATION,
  1347.                 self::class,
  1348.             );
  1349.         }
  1351.         $eventManager = $this->getEventManager();
  1353.         if ($eventManager->hasListeners(Events::onTransactionBegin)) {
  1354.             Deprecation::trigger(
  1355.                 'doctrine/dbal',
  1356.                 'https://github.com/doctrine/dbal/issues/5784',
  1357.                 'Subscribing to %s events is deprecated.',
  1358.                 Events::onTransactionBegin,
  1359.             );
  1361.             $eventManager->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1362.         }
  1364.         return true;
  1365.     }
  1367.     /**
  1368.      * @return bool
  1369.      *
  1370.      * @throws Exception
  1371.      */
  1372.     public function commit()
  1373.     {
  1374.         if ($this->transactionNestingLevel === 0) {
  1375.             throw ConnectionException::noActiveTransaction();
  1376.         }
  1378.         if ($this->isRollbackOnly) {
  1379.             throw ConnectionException::commitFailedRollbackOnly();
  1380.         }
  1382.         $result = true;
  1384.         $connection = $this->getWrappedConnection();
  1386.         if ($this->transactionNestingLevel === 1) {
  1387.             $result = $this->doCommit($connection);
  1388.         } elseif ($this->nestTransactionsWithSavepoints) {
  1389.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1390.         }
  1392.         --$this->transactionNestingLevel;
  1394.         $eventManager = $this->getEventManager();
  1396.         if ($eventManager->hasListeners(Events::onTransactionCommit)) {
  1397.             Deprecation::trigger(
  1398.                 'doctrine/dbal',
  1399.                 'https://github.com/doctrine/dbal/issues/5784',
  1400.                 'Subscribing to %s events is deprecated.',
  1401.                 Events::onTransactionCommit,
  1402.             );
  1404.             $eventManager->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  1405.         }
  1407.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1408.             return $result;
  1409.         }
  1411.         $this->beginTransaction();
  1413.         return $result;
  1414.     }
  1416.     /**
  1417.      * @return bool
  1418.      *
  1419.      * @throws DriverException
  1420.      */
  1421.     private function doCommit(DriverConnection $connection)
  1422.     {
  1423.         $logger = $this->_config->getSQLLogger();
  1425.         if ($logger !== null) {
  1426.             $logger->startQuery('"COMMIT"');
  1427.         }
  1429.         $result = $connection->commit();
  1431.         if ($logger !== null) {
  1432.             $logger->stopQuery();
  1433.         }
  1435.         return $result;
  1436.     }
  1438.     /**
  1439.      * Commits all current nesting transactions.
  1440.      *
  1441.      * @throws Exception
  1442.      */
  1443.     private function commitAll(): void
  1444.     {
  1445.         while ($this->transactionNestingLevel !== 0) {
  1446.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1447.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1448.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1449.                 $this->commit();
  1451.                 return;
  1452.             }
  1454.             $this->commit();
  1455.         }
  1456.     }
  1458.     /**
  1459.      * Cancels any database changes done during the current transaction.
  1460.      *
  1461.      * @return bool
  1462.      *
  1463.      * @throws Exception
  1464.      */
  1465.     public function rollBack()
  1466.     {
  1467.         if ($this->transactionNestingLevel === 0) {
  1468.             throw ConnectionException::noActiveTransaction();
  1469.         }
  1471.         $connection = $this->getWrappedConnection();
  1473.         $logger = $this->_config->getSQLLogger();
  1475.         if ($this->transactionNestingLevel === 1) {
  1476.             if ($logger !== null) {
  1477.                 $logger->startQuery('"ROLLBACK"');
  1478.             }
  1480.             $this->transactionNestingLevel = 0;
  1481.             $connection->rollBack();
  1482.             $this->isRollbackOnly = false;
  1483.             if ($logger !== null) {
  1484.                 $logger->stopQuery();
  1485.             }
  1487.             if ($this->autoCommit === false) {
  1488.                 $this->beginTransaction();
  1489.             }
  1490.         } elseif ($this->nestTransactionsWithSavepoints) {
  1491.             if ($logger !== null) {
  1492.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1493.             }
  1495.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1496.             --$this->transactionNestingLevel;
  1497.             if ($logger !== null) {
  1498.                 $logger->stopQuery();
  1499.             }
  1500.         } else {
  1501.             $this->isRollbackOnly = true;
  1502.             --$this->transactionNestingLevel;
  1503.         }
  1505.         $eventManager = $this->getEventManager();
  1507.         if ($eventManager->hasListeners(Events::onTransactionRollBack)) {
  1508.             Deprecation::trigger(
  1509.                 'doctrine/dbal',
  1510.                 'https://github.com/doctrine/dbal/issues/5784',
  1511.                 'Subscribing to %s events is deprecated.',
  1512.                 Events::onTransactionRollBack,
  1513.             );
  1515.             $eventManager->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1516.         }
  1518.         return true;
  1519.     }
  1521.     /**
  1522.      * Creates a new savepoint.
  1523.      *
  1524.      * @param string $savepoint The name of the savepoint to create.
  1525.      *
  1526.      * @return void
  1527.      *
  1528.      * @throws Exception
  1529.      */
  1530.     public function createSavepoint($savepoint)
  1531.     {
  1532.         $platform = $this->getDatabasePlatform();
  1534.         if (! $platform->supportsSavepoints()) {
  1535.             throw ConnectionException::savepointsNotSupported();
  1536.         }
  1538.         $this->executeStatement($platform->createSavePoint($savepoint));
  1539.     }
  1541.     /**
  1542.      * Releases the given savepoint.
  1543.      *
  1544.      * @param string $savepoint The name of the savepoint to release.
  1545.      *
  1546.      * @return void
  1547.      *
  1548.      * @throws Exception
  1549.      */
  1550.     public function releaseSavepoint($savepoint)
  1551.     {
  1552.         $logger = $this->_config->getSQLLogger();
  1554.         $platform = $this->getDatabasePlatform();
  1556.         if (! $platform->supportsSavepoints()) {
  1557.             throw ConnectionException::savepointsNotSupported();
  1558.         }
  1560.         if (! $platform->supportsReleaseSavepoints()) {
  1561.             if ($logger !== null) {
  1562.                 $logger->stopQuery();
  1563.             }
  1565.             return;
  1566.         }
  1568.         if ($logger !== null) {
  1569.             $logger->startQuery('"RELEASE SAVEPOINT"');
  1570.         }
  1572.         $this->executeStatement($platform->releaseSavePoint($savepoint));
  1574.         if ($logger === null) {
  1575.             return;
  1576.         }
  1578.         $logger->stopQuery();
  1579.     }
  1581.     /**
  1582.      * Rolls back to the given savepoint.
  1583.      *
  1584.      * @param string $savepoint The name of the savepoint to rollback to.
  1585.      *
  1586.      * @return void
  1587.      *
  1588.      * @throws Exception
  1589.      */
  1590.     public function rollbackSavepoint($savepoint)
  1591.     {
  1592.         $platform = $this->getDatabasePlatform();
  1594.         if (! $platform->supportsSavepoints()) {
  1595.             throw ConnectionException::savepointsNotSupported();
  1596.         }
  1598.         $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1599.     }
  1601.     /**
  1602.      * Gets the wrapped driver connection.
  1603.      *
  1604.      * @deprecated Use {@link getNativeConnection()} to access the native connection.
  1605.      *
  1606.      * @return DriverConnection
  1607.      *
  1608.      * @throws Exception
  1609.      */
  1610.     public function getWrappedConnection()
  1611.     {
  1612.         Deprecation::triggerIfCalledFromOutside(
  1613.             'doctrine/dbal',
  1614.             'https://github.com/doctrine/dbal/issues/4966',
  1615.             'Connection::getWrappedConnection() is deprecated.'
  1616.                 . ' Use Connection::getNativeConnection() to access the native connection.',
  1617.         );
  1619.         $this->connect();
  1621.         assert($this->_conn !== null);
  1623.         return $this->_conn;
  1624.     }
  1626.     /** @return resource|object */
  1627.     public function getNativeConnection()
  1628.     {
  1629.         $this->connect();
  1631.         assert($this->_conn !== null);
  1632.         if (! method_exists($this->_conn, 'getNativeConnection')) {
  1633.             throw new LogicException(sprintf(
  1634.                 'The driver connection %s does not support accessing the native connection.',
  1635.                 get_class($this->_conn),
  1636.             ));
  1637.         }
  1639.         return $this->_conn->getNativeConnection();
  1640.     }
  1642.     /**
  1643.      * Creates a SchemaManager that can be used to inspect or change the
  1644.      * database schema through the connection.
  1645.      *
  1646.      * @throws Exception
  1647.      */
  1648.     public function createSchemaManager(): AbstractSchemaManager
  1649.     {
  1650.         return $this->_driver->getSchemaManager(
  1651.             $this,
  1652.             $this->getDatabasePlatform(),
  1653.         );
  1654.     }
  1656.     /**
  1657.      * Gets the SchemaManager that can be used to inspect or change the
  1658.      * database schema through the connection.
  1659.      *
  1660.      * @deprecated Use {@see createSchemaManager()} instead.
  1661.      *
  1662.      * @return AbstractSchemaManager
  1663.      *
  1664.      * @throws Exception
  1665.      */
  1666.     public function getSchemaManager()
  1667.     {
  1668.         Deprecation::triggerIfCalledFromOutside(
  1669.             'doctrine/dbal',
  1670.             'https://github.com/doctrine/dbal/issues/4515',
  1671.             'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.',
  1672.         );
  1674.         return $this->_schemaManager ??= $this->createSchemaManager();
  1675.     }
  1677.     /**
  1678.      * Marks the current transaction so that the only possible
  1679.      * outcome for the transaction to be rolled back.
  1680.      *
  1681.      * @return void
  1682.      *
  1683.      * @throws ConnectionException If no transaction is active.
  1684.      */
  1685.     public function setRollbackOnly()
  1686.     {
  1687.         if ($this->transactionNestingLevel === 0) {
  1688.             throw ConnectionException::noActiveTransaction();
  1689.         }
  1691.         $this->isRollbackOnly = true;
  1692.     }
  1694.     /**
  1695.      * Checks whether the current transaction is marked for rollback only.
  1696.      *
  1697.      * @return bool
  1698.      *
  1699.      * @throws ConnectionException If no transaction is active.
  1700.      */
  1701.     public function isRollbackOnly()
  1702.     {
  1703.         if ($this->transactionNestingLevel === 0) {
  1704.             throw ConnectionException::noActiveTransaction();
  1705.         }
  1707.         return $this->isRollbackOnly;
  1708.     }
  1710.     /**
  1711.      * Converts a given value to its database representation according to the conversion
  1712.      * rules of a specific DBAL mapping type.
  1713.      *
  1714.      * @param mixed  $value The value to convert.
  1715.      * @param string $type  The name of the DBAL mapping type.
  1716.      *
  1717.      * @return mixed The converted value.
  1718.      *
  1719.      * @throws Exception
  1720.      */
  1721.     public function convertToDatabaseValue($value, $type)
  1722.     {
  1723.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1724.     }
  1726.     /**
  1727.      * Converts a given value to its PHP representation according to the conversion
  1728.      * rules of a specific DBAL mapping type.
  1729.      *
  1730.      * @param mixed  $value The value to convert.
  1731.      * @param string $type  The name of the DBAL mapping type.
  1732.      *
  1733.      * @return mixed The converted type.
  1734.      *
  1735.      * @throws Exception
  1736.      */
  1737.     public function convertToPHPValue($value, $type)
  1738.     {
  1739.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1740.     }
  1742.     /**
  1743.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1744.      * or DBAL mapping type, to a given statement.
  1745.      *
  1746.      * @param DriverStatement                                                      $stmt   Prepared statement
  1747.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1748.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1749.      *
  1750.      * @throws Exception
  1751.      */
  1752.     private function bindParameters(DriverStatement $stmt, array $params, array $types): void
  1753.     {
  1754.         // Check whether parameters are positional or named. Mixing is not allowed.
  1755.         if (is_int(key($params))) {
  1756.             $bindIndex = 1;
  1758.             foreach ($params as $key => $value) {
  1759.                 if (isset($types[$key])) {
  1760.                     $type                  = $types[$key];
  1761.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1762.                 } else {
  1763.                     if (array_key_exists($key, $types)) {
  1764.                         Deprecation::trigger(
  1765.                             'doctrine/dbal',
  1766.                             'https://github.com/doctrine/dbal/pull/5550',
  1767.                             'Using NULL as prepared statement parameter type is deprecated.'
  1768.                                 . 'Omit or use Parameter::STRING instead',
  1769.                         );
  1770.                     }
  1772.                     $bindingType = ParameterType::STRING;
  1773.                 }
  1775.                 $stmt->bindValue($bindIndex, $value, $bindingType);
  1777.                 ++$bindIndex;
  1778.             }
  1779.         } else {
  1780.             // Named parameters
  1781.             foreach ($params as $name => $value) {
  1782.                 if (isset($types[$name])) {
  1783.                     $type                  = $types[$name];
  1784.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1785.                 } else {
  1786.                     if (array_key_exists($name, $types)) {
  1787.                         Deprecation::trigger(
  1788.                             'doctrine/dbal',
  1789.                             'https://github.com/doctrine/dbal/pull/5550',
  1790.                             'Using NULL as prepared statement parameter type is deprecated.'
  1791.                                 . 'Omit or use Parameter::STRING instead',
  1792.                         );
  1793.                     }
  1795.                     $bindingType = ParameterType::STRING;
  1796.                 }
  1798.                 $stmt->bindValue($name, $value, $bindingType);
  1799.             }
  1800.         }
  1801.     }
  1803.     /**
  1804.      * Gets the binding type of a given type.
  1805.      *
  1806.      * @param mixed                $value The value to bind.
  1807.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  1808.      *
  1809.      * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1810.      *
  1811.      * @throws Exception
  1812.      */
  1813.     private function getBindingInfo($value, $type): array
  1814.     {
  1815.         if (is_string($type)) {
  1816.             $type = Type::getType($type);
  1817.         }
  1819.         if ($type instanceof Type) {
  1820.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1821.             $bindingType = $type->getBindingType();
  1822.         } else {
  1823.             $bindingType = $type ?? ParameterType::STRING;
  1824.         }
  1826.         return [$value, $bindingType];
  1827.     }
  1829.     /**
  1830.      * Creates a new instance of a SQL query builder.
  1831.      *
  1832.      * @return QueryBuilder
  1833.      */
  1834.     public function createQueryBuilder()
  1835.     {
  1836.         return new Query\QueryBuilder($this);
  1837.     }
  1839.     /**
  1840.      * @internal
  1841.      *
  1842.      * @param list<mixed>|array<string, mixed>                                     $params
  1843.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1844.      */
  1845.     final public function convertExceptionDuringQuery(
  1846.         Driver\Exception $e,
  1847.         string $sql,
  1848.         array $params = [],
  1849.         array $types = []
  1850.     ): DriverException {
  1851.         return $this->handleDriverException($e, new Query($sql, $params, $types));
  1852.     }
  1854.     /** @internal */
  1855.     final public function convertException(Driver\Exception $e): DriverException
  1856.     {
  1857.         return $this->handleDriverException($e, null);
  1858.     }
  1860.     /**
  1861.      * @param array<int, mixed>|array<string, mixed>                               $params
  1862.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1863.      *
  1864.      * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1865.      */
  1866.     private function expandArrayParameters(string $sql, array $params, array $types): array
  1867.     {
  1868.         $this->parser ??= $this->getDatabasePlatform()->createSQLParser();
  1869.         $visitor        = new ExpandArrayParameters($params, $types);
  1871.         $this->parser->parse($sql, $visitor);
  1873.         return [
  1874.             $visitor->getSQL(),
  1875.             $visitor->getParameters(),
  1876.             $visitor->getTypes(),
  1877.         ];
  1878.     }
  1880.     /**
  1881.      * @param array<int, mixed>|array<string, mixed>                               $params
  1882.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1883.      */
  1884.     private function needsArrayParameterConversion(array $params, array $types): bool
  1885.     {
  1886.         if (is_string(key($params))) {
  1887.             return true;
  1888.         }
  1890.         foreach ($types as $type) {
  1891.             if (
  1892.                 $type === self::PARAM_INT_ARRAY
  1893.                 || $type === self::PARAM_STR_ARRAY
  1894.                 || $type === self::PARAM_ASCII_STR_ARRAY
  1895.             ) {
  1896.                 return true;
  1897.             }
  1898.         }
  1900.         return false;
  1901.     }
  1903.     private function handleDriverException(
  1904.         Driver\Exception $driverException,
  1905.         ?Query $query
  1906.     ): DriverException {
  1907.         $this->exceptionConverter ??= $this->_driver->getExceptionConverter();
  1908.         $exception                  = $this->exceptionConverter->convert($driverException, $query);
  1910.         if ($exception instanceof ConnectionLost) {
  1911.             $this->close();
  1912.         }
  1914.         return $exception;
  1915.     }
  1917.     /**
  1918.      * BC layer for a wide-spread use-case of old DBAL APIs
  1919.      *
  1920.      * @deprecated This API is deprecated and will be removed after 2022
  1921.      *
  1922.      * @param array<mixed>           $params The query parameters
  1923.      * @param array<int|string|null> $types  The parameter types
  1924.      */
  1925.     public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1926.     {
  1927.         return $this->executeStatement($sql, $params, $types);
  1928.     }
  1930.     /**
  1931.      * BC layer for a wide-spread use-case of old DBAL APIs
  1932.      *
  1933.      * @deprecated This API is deprecated and will be removed after 2022
  1934.      */
  1935.     public function query(string $sql): Result
  1936.     {
  1937.         return $this->executeQuery($sql);
  1938.     }
  1940.     /**
  1941.      * BC layer for a wide-spread use-case of old DBAL APIs
  1942.      *
  1943.      * @deprecated This API is deprecated and will be removed after 2022
  1944.      */
  1945.     public function exec(string $sql): int
  1946.     {
  1947.         return $this->executeStatement($sql);
  1948.     }
  1949. }