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

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