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

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