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

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayResult;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Driver\API\ExceptionConverter;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  13. use Doctrine\DBAL\Driver\Statement as DriverStatement;
  14. use Doctrine\DBAL\Event\TransactionBeginEventArgs;
  15. use Doctrine\DBAL\Event\TransactionCommitEventArgs;
  16. use Doctrine\DBAL\Event\TransactionRollBackEventArgs;
  17. use Doctrine\DBAL\Exception\ConnectionLost;
  18. use Doctrine\DBAL\Exception\DriverException;
  19. use Doctrine\DBAL\Exception\InvalidArgumentException;
  20. use Doctrine\DBAL\Platforms\AbstractPlatform;
  21. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  22. use Doctrine\DBAL\Query\QueryBuilder;
  23. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  24. use Doctrine\DBAL\SQL\Parser;
  25. use Doctrine\DBAL\Types\Type;
  26. use Doctrine\Deprecations\Deprecation;
  27. use Throwable;
  28. use Traversable;
  30. use function assert;
  31. use function count;
  32. use function get_class;
  33. use function implode;
  34. use function is_int;
  35. use function is_string;
  36. use function key;
  38. /**
  39.  * A database abstraction-level connection that implements features like events, transaction isolation levels,
  40.  * configuration, emulated transaction nesting, lazy connecting and more.
  41.  *
  42.  * @psalm-import-type Params from DriverManager
  43.  */
  44. class Connection
  45. {
  46.     /**
  47.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  48.      */
  49.     public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  51.     /**
  52.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  53.      */
  54.     public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  56.     /**
  57.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  58.      */
  59.     public const ARRAY_PARAM_OFFSET = 100;
  61.     /**
  62.      * The wrapped driver connection.
  63.      *
  64.      * @var \Doctrine\DBAL\Driver\Connection|null
  65.      */
  66.     protected $_conn;
  68.     /** @var Configuration */
  69.     protected $_config;
  71.     /** @var EventManager */
  72.     protected $_eventManager;
  74.     /**
  75.      * @deprecated Use {@see createExpressionBuilder()} instead.
  76.      *
  77.      * @var ExpressionBuilder
  78.      */
  79.     protected $_expr;
  81.     /**
  82.      * The current auto-commit mode of this connection.
  83.      *
  84.      * @var bool
  85.      */
  86.     private $autoCommit = true;
  88.     /**
  89.      * The transaction nesting level.
  90.      *
  91.      * @var int
  92.      */
  93.     private $transactionNestingLevel = 0;
  95.     /**
  96.      * The currently active transaction isolation level or NULL before it has been determined.
  97.      *
  98.      * @var int|null
  99.      */
  100.     private $transactionIsolationLevel;
  102.     /**
  103.      * If nested transactions should use savepoints.
  104.      *
  105.      * @var bool
  106.      */
  107.     private $nestTransactionsWithSavepoints = false;
  109.     /**
  110.      * The parameters used during creation of the Connection instance.
  111.      *
  112.      * @var array<string,mixed>
  113.      * @phpstan-var array<string,mixed>
  114.      * @psalm-var Params
  115.      */
  116.     private $params;
  118.     /**
  119.      * The database platform object used by the connection or NULL before it's initialized.
  120.      *
  121.      * @var AbstractPlatform|null
  122.      */
  123.     private $platform;
  125.     /** @var ExceptionConverter|null */
  126.     private $exceptionConverter;
  128.     /** @var Parser|null */
  129.     private $parser;
  131.     /**
  132.      * The schema manager.
  133.      *
  134.      * @deprecated Use {@see createSchemaManager()} instead.
  135.      *
  136.      * @var AbstractSchemaManager|null
  137.      */
  138.     protected $_schemaManager;
  140.     /**
  141.      * The used DBAL driver.
  142.      *
  143.      * @var Driver
  144.      */
  145.     protected $_driver;
  147.     /**
  148.      * Flag that indicates whether the current transaction is marked for rollback only.
  149.      *
  150.      * @var bool
  151.      */
  152.     private $isRollbackOnly = false;
  154.     /**
  155.      * Initializes a new instance of the Connection class.
  156.      *
  157.      * @internal The connection can be only instantiated by the driver manager.
  158.      *
  159.      * @param array<string,mixed> $params       The connection parameters.
  160.      * @param Driver              $driver       The driver to use.
  161.      * @param Configuration|null  $config       The configuration, optional.
  162.      * @param EventManager|null   $eventManager The event manager, optional.
  163.      * @psalm-param Params $params
  164.      * @phpstan-param array<string,mixed> $params
  165.      *
  166.      * @throws Exception
  167.      */
  168.     public function __construct(
  169.         array $params,
  170.         Driver $driver,
  171.         ?Configuration $config = null,
  172.         ?EventManager $eventManager = null
  173.     ) {
  174.         $this->_driver = $driver;
  175.         $this->params  = $params;
  177.         if (isset($params['platform'])) {
  178.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  179.                 throw Exception::invalidPlatformType($params['platform']);
  180.             }
  182.             $this->platform = $params['platform'];
  183.         }
  185.         // Create default config and event manager if none given
  186.         if ($config === null) {
  187.             $config = new Configuration();
  188.         }
  190.         if ($eventManager === null) {
  191.             $eventManager = new EventManager();
  192.         }
  194.         $this->_config       = $config;
  195.         $this->_eventManager = $eventManager;
  197.         $this->_expr = $this->createExpressionBuilder();
  199.         $this->autoCommit = $config->getAutoCommit();
  200.     }
  202.     /**
  203.      * Gets the parameters used during instantiation.
  204.      *
  205.      * @internal
  206.      *
  207.      * @return array<string,mixed>
  208.      * @psalm-return Params
  209.      * @phpstan-return array<string,mixed>
  210.      */
  211.     public function getParams()
  212.     {
  213.         return $this->params;
  214.     }
  216.     /**
  217.      * Gets the name of the currently selected database.
  218.      *
  219.      * @return string|null The name of the database or NULL if a database is not selected.
  220.      *                     The platforms which don't support the concept of a database (e.g. embedded databases)
  221.      *                     must always return a string as an indicator of an implicitly selected database.
  222.      *
  223.      * @throws Exception
  224.      */
  225.     public function getDatabase()
  226.     {
  227.         $platform = $this->getDatabasePlatform();
  228.         $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  229.         $database = $this->fetchOne($query);
  231.         assert(is_string($database) || $database === null);
  233.         return $database;
  234.     }
  236.     /**
  237.      * Gets the DBAL driver instance.
  238.      *
  239.      * @return Driver
  240.      */
  241.     public function getDriver()
  242.     {
  243.         return $this->_driver;
  244.     }
  246.     /**
  247.      * Gets the Configuration used by the Connection.
  248.      *
  249.      * @return Configuration
  250.      */
  251.     public function getConfiguration()
  252.     {
  253.         return $this->_config;
  254.     }
  256.     /**
  257.      * Gets the EventManager used by the Connection.
  258.      *
  259.      * @return EventManager
  260.      */
  261.     public function getEventManager()
  262.     {
  263.         return $this->_eventManager;
  264.     }
  266.     /**
  267.      * Gets the DatabasePlatform for the connection.
  268.      *
  269.      * @return AbstractPlatform
  270.      *
  271.      * @throws Exception
  272.      */
  273.     public function getDatabasePlatform()
  274.     {
  275.         if ($this->platform === null) {
  276.             $this->platform = $this->detectDatabasePlatform();
  277.             $this->platform->setEventManager($this->_eventManager);
  278.         }
  280.         return $this->platform;
  281.     }
  283.     /**
  284.      * Creates an expression builder for the connection.
  285.      */
  286.     public function createExpressionBuilder(): ExpressionBuilder
  287.     {
  288.         return new ExpressionBuilder($this);
  289.     }
  291.     /**
  292.      * Gets the ExpressionBuilder for the connection.
  293.      *
  294.      * @deprecated Use {@see createExpressionBuilder()} instead.
  295.      *
  296.      * @return ExpressionBuilder
  297.      */
  298.     public function getExpressionBuilder()
  299.     {
  300.         Deprecation::triggerIfCalledFromOutside(
  301.             'doctrine/dbal',
  302.             'https://github.com/doctrine/dbal/issues/4515',
  303.             'Connection::getExpressionBuilder() is deprecated,'
  304.                 . ' use Connection::createExpressionBuilder() instead.'
  305.         );
  307.         return $this->_expr;
  308.     }
  310.     /**
  311.      * Establishes the connection with the database.
  312.      *
  313.      * @return bool TRUE if the connection was successfully established, FALSE if
  314.      *              the connection is already open.
  315.      *
  316.      * @throws Exception
  317.      */
  318.     public function connect()
  319.     {
  320.         if ($this->_conn !== null) {
  321.             return false;
  322.         }
  324.         try {
  325.             $this->_conn = $this->_driver->connect($this->params);
  326.         } catch (Driver\Exception $e) {
  327.             throw $this->convertException($e);
  328.         }
  330.         if ($this->autoCommit === false) {
  331.             $this->beginTransaction();
  332.         }
  334.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  335.             $eventArgs = new Event\ConnectionEventArgs($this);
  336.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  337.         }
  339.         return true;
  340.     }
  342.     /**
  343.      * Detects and sets the database platform.
  344.      *
  345.      * Evaluates custom platform class and version in order to set the correct platform.
  346.      *
  347.      * @throws Exception If an invalid platform was specified for this connection.
  348.      */
  349.     private function detectDatabasePlatform(): AbstractPlatform
  350.     {
  351.         $version = $this->getDatabasePlatformVersion();
  353.         if ($version !== null) {
  354.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  356.             return $this->_driver->createDatabasePlatformForVersion($version);
  357.         }
  359.         return $this->_driver->getDatabasePlatform();
  360.     }
  362.     /**
  363.      * Returns the version of the related platform if applicable.
  364.      *
  365.      * Returns null if either the driver is not capable to create version
  366.      * specific platform instances, no explicit server version was specified
  367.      * or the underlying driver connection cannot determine the platform
  368.      * version without having to query it (performance reasons).
  369.      *
  370.      * @return string|null
  371.      *
  372.      * @throws Throwable
  373.      */
  374.     private function getDatabasePlatformVersion()
  375.     {
  376.         // Driver does not support version specific platforms.
  377.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  378.             return null;
  379.         }
  381.         // Explicit platform version requested (supersedes auto-detection).
  382.         if (isset($this->params['serverVersion'])) {
  383.             return $this->params['serverVersion'];
  384.         }
  386.         // If not connected, we need to connect now to determine the platform version.
  387.         if ($this->_conn === null) {
  388.             try {
  389.                 $this->connect();
  390.             } catch (Exception $originalException) {
  391.                 if (! isset($this->params['dbname'])) {
  392.                     throw $originalException;
  393.                 }
  395.                 // The database to connect to might not yet exist.
  396.                 // Retry detection without database name connection parameter.
  397.                 $params = $this->params;
  399.                 unset($this->params['dbname']);
  401.                 try {
  402.                     $this->connect();
  403.                 } catch (Exception $fallbackException) {
  404.                     // Either the platform does not support database-less connections
  405.                     // or something else went wrong.
  406.                     throw $originalException;
  407.                 } finally {
  408.                     $this->params = $params;
  409.                 }
  411.                 $serverVersion = $this->getServerVersion();
  413.                 // Close "temporary" connection to allow connecting to the real database again.
  414.                 $this->close();
  416.                 return $serverVersion;
  417.             }
  418.         }
  420.         return $this->getServerVersion();
  421.     }
  423.     /**
  424.      * Returns the database server version if the underlying driver supports it.
  425.      *
  426.      * @return string|null
  427.      *
  428.      * @throws Exception
  429.      */
  430.     private function getServerVersion()
  431.     {
  432.         $connection = $this->getWrappedConnection();
  434.         // Automatic platform version detection.
  435.         if ($connection instanceof ServerInfoAwareConnection) {
  436.             try {
  437.                 return $connection->getServerVersion();
  438.             } catch (Driver\Exception $e) {
  439.                 throw $this->convertException($e);
  440.             }
  441.         }
  443.         Deprecation::trigger(
  444.             'doctrine/dbal',
  445.             'https://github.com/doctrine/dbal/pulls/4750',
  446.             'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  447.             get_class($connection)
  448.         );
  450.         // Unable to detect platform version.
  451.         return null;
  452.     }
  454.     /**
  455.      * Returns the current auto-commit mode for this connection.
  456.      *
  457.      * @see    setAutoCommit
  458.      *
  459.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  460.      */
  461.     public function isAutoCommit()
  462.     {
  463.         return $this->autoCommit === true;
  464.     }
  466.     /**
  467.      * Sets auto-commit mode for this connection.
  468.      *
  469.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  470.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  471.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  472.      *
  473.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  474.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  475.      *
  476.      * @see   isAutoCommit
  477.      *
  478.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  479.      *
  480.      * @return void
  481.      */
  482.     public function setAutoCommit($autoCommit)
  483.     {
  484.         $autoCommit = (bool) $autoCommit;
  486.         // Mode not changed, no-op.
  487.         if ($autoCommit === $this->autoCommit) {
  488.             return;
  489.         }
  491.         $this->autoCommit = $autoCommit;
  493.         // Commit all currently active transactions if any when switching auto-commit mode.
  494.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  495.             return;
  496.         }
  498.         $this->commitAll();
  499.     }
  501.     /**
  502.      * Prepares and executes an SQL query and returns the first row of the result
  503.      * as an associative array.
  504.      *
  505.      * @param string                                                               $query  SQL query
  506.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  507.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  508.      *
  509.      * @return array<string, mixed>|false False is returned if no rows are found.
  510.      *
  511.      * @throws Exception
  512.      */
  513.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  514.     {
  515.         return $this->executeQuery($query, $params, $types)->fetchAssociative();
  516.     }
  518.     /**
  519.      * Prepares and executes an SQL query and returns the first row of the result
  520.      * as a numerically indexed array.
  521.      *
  522.      * @param string                                                               $query  SQL query
  523.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  524.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  525.      *
  526.      * @return list< mixed>|false False is returned if no rows are found.
  527.      *
  528.      * @throws Exception
  529.      */
  530.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  531.     {
  532.         return $this->executeQuery($query, $params, $types)->fetchNumeric();
  533.     }
  535.     /**
  536.      * Prepares and executes an SQL query and returns the value of a single column
  537.      * of the first row of the result.
  538.      *
  539.      * @param string                                                               $query  SQL query
  540.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  541.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  542.      *
  543.      * @return mixed|false False is returned if no rows are found.
  544.      *
  545.      * @throws Exception
  546.      */
  547.     public function fetchOne(string $query, array $params = [], array $types = [])
  548.     {
  549.         return $this->executeQuery($query, $params, $types)->fetchOne();
  550.     }
  552.     /**
  553.      * Whether an actual connection to the database is established.
  554.      *
  555.      * @return bool
  556.      */
  557.     public function isConnected()
  558.     {
  559.         return $this->_conn !== null;
  560.     }
  562.     /**
  563.      * Checks whether a transaction is currently active.
  564.      *
  565.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  566.      */
  567.     public function isTransactionActive()
  568.     {
  569.         return $this->transactionNestingLevel > 0;
  570.     }
  572.     /**
  573.      * Adds condition based on the criteria to the query components
  574.      *
  575.      * @param array<string,mixed> $criteria   Map of key columns to their values
  576.      * @param string[]            $columns    Column names
  577.      * @param mixed[]             $values     Column values
  578.      * @param string[]            $conditions Key conditions
  579.      *
  580.      * @throws Exception
  581.      */
  582.     private function addCriteriaCondition(
  583.         array $criteria,
  584.         array &$columns,
  585.         array &$values,
  586.         array &$conditions
  587.     ): void {
  588.         $platform = $this->getDatabasePlatform();
  590.         foreach ($criteria as $columnName => $value) {
  591.             if ($value === null) {
  592.                 $conditions[] = $platform->getIsNullExpression($columnName);
  593.                 continue;
  594.             }
  596.             $columns[]    = $columnName;
  597.             $values[]     = $value;
  598.             $conditions[] = $columnName . ' = ?';
  599.         }
  600.     }
  602.     /**
  603.      * Executes an SQL DELETE statement on a table.
  604.      *
  605.      * Table expression and columns are not escaped and are not safe for user-input.
  606.      *
  607.      * @param string                                                               $table    Table name
  608.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  609.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  610.      *
  611.      * @return int The number of affected rows.
  612.      *
  613.      * @throws Exception
  614.      */
  615.     public function delete($table, array $criteria, array $types = [])
  616.     {
  617.         if (count($criteria) === 0) {
  618.             throw InvalidArgumentException::fromEmptyCriteria();
  619.         }
  621.         $columns = $values = $conditions = [];
  623.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  625.         return $this->executeStatement(
  626.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  627.             $values,
  628.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  629.         );
  630.     }
  632.     /**
  633.      * Closes the connection.
  634.      *
  635.      * @return void
  636.      */
  637.     public function close()
  638.     {
  639.         $this->_conn                   = null;
  640.         $this->transactionNestingLevel = 0;
  641.     }
  643.     /**
  644.      * Sets the transaction isolation level.
  645.      *
  646.      * @param int $level The level to set.
  647.      *
  648.      * @return int
  649.      *
  650.      * @throws Exception
  651.      */
  652.     public function setTransactionIsolation($level)
  653.     {
  654.         $this->transactionIsolationLevel = $level;
  656.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  657.     }
  659.     /**
  660.      * Gets the currently active transaction isolation level.
  661.      *
  662.      * @return int The current transaction isolation level.
  663.      *
  664.      * @throws Exception
  665.      */
  666.     public function getTransactionIsolation()
  667.     {
  668.         if ($this->transactionIsolationLevel === null) {
  669.             $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  670.         }
  672.         return $this->transactionIsolationLevel;
  673.     }
  675.     /**
  676.      * Executes an SQL UPDATE 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>                                                 $data     Column-value pairs
  682.      * @param array<string, mixed>                                                 $criteria Update criteria
  683.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  684.      *
  685.      * @return int The number of affected rows.
  686.      *
  687.      * @throws Exception
  688.      */
  689.     public function update($table, array $data, array $criteria, array $types = [])
  690.     {
  691.         $columns = $values = $conditions = $set = [];
  693.         foreach ($data as $columnName => $value) {
  694.             $columns[] = $columnName;
  695.             $values[]  = $value;
  696.             $set[]     = $columnName . ' = ?';
  697.         }
  699.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  701.         if (is_string(key($types))) {
  702.             $types = $this->extractTypeValues($columns, $types);
  703.         }
  705.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  706.                 . ' WHERE ' . implode(' AND ', $conditions);
  708.         return $this->executeStatement($sql, $values, $types);
  709.     }
  711.     /**
  712.      * Inserts a table row with specified data.
  713.      *
  714.      * Table expression and columns are not escaped and are not safe for user-input.
  715.      *
  716.      * @param string                                                               $table Table name
  717.      * @param array<string, mixed>                                                 $data  Column-value pairs
  718.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  719.      *
  720.      * @return int The number of affected rows.
  721.      *
  722.      * @throws Exception
  723.      */
  724.     public function insert($table, array $data, array $types = [])
  725.     {
  726.         if (count($data) === 0) {
  727.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  728.         }
  730.         $columns = [];
  731.         $values  = [];
  732.         $set     = [];
  734.         foreach ($data as $columnName => $value) {
  735.             $columns[] = $columnName;
  736.             $values[]  = $value;
  737.             $set[]     = '?';
  738.         }
  740.         return $this->executeStatement(
  741.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  742.             ' VALUES (' . implode(', ', $set) . ')',
  743.             $values,
  744.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  745.         );
  746.     }
  748.     /**
  749.      * Extract ordered type list from an ordered column list and type map.
  750.      *
  751.      * @param array<int, string>                                                   $columnList
  752.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  753.      *
  754.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  755.      */
  756.     private function extractTypeValues(array $columnList, array $types): array
  757.     {
  758.         $typeValues = [];
  760.         foreach ($columnList as $columnName) {
  761.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  762.         }
  764.         return $typeValues;
  765.     }
  767.     /**
  768.      * Quotes a string so it can be safely used as a table or column name, even if
  769.      * it is a reserved name.
  770.      *
  771.      * Delimiting style depends on the underlying database platform that is being used.
  772.      *
  773.      * NOTE: Just because you CAN use quoted identifiers does not mean
  774.      * you SHOULD use them. In general, they end up causing way more
  775.      * problems than they solve.
  776.      *
  777.      * @param string $str The name to be quoted.
  778.      *
  779.      * @return string The quoted name.
  780.      */
  781.     public function quoteIdentifier($str)
  782.     {
  783.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  784.     }
  786.     /**
  787.      * The usage of this method is discouraged. Use prepared statements
  788.      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  789.      *
  790.      * @param mixed                $value
  791.      * @param int|string|Type|null $type
  792.      *
  793.      * @return mixed
  794.      */
  795.     public function quote($value, $type = ParameterType::STRING)
  796.     {
  797.         $connection = $this->getWrappedConnection();
  799.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  801.         return $connection->quote($value, $bindingType);
  802.     }
  804.     /**
  805.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  806.      *
  807.      * @param string                                                               $query  SQL query
  808.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  809.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  810.      *
  811.      * @return list<list<mixed>>
  812.      *
  813.      * @throws Exception
  814.      */
  815.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  816.     {
  817.         return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  818.     }
  820.     /**
  821.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  822.      *
  823.      * @param string                                                               $query  SQL query
  824.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  825.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  826.      *
  827.      * @return list<array<string,mixed>>
  828.      *
  829.      * @throws Exception
  830.      */
  831.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  832.     {
  833.         return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  834.     }
  836.     /**
  837.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  838.      * mapped to the first column and the values mapped to the second column.
  839.      *
  840.      * @param string                                                               $query  SQL query
  841.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  842.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  843.      *
  844.      * @return array<mixed,mixed>
  845.      *
  846.      * @throws Exception
  847.      */
  848.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  849.     {
  850.         return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  851.     }
  853.     /**
  854.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  855.      * to the first column and the values being an associative array representing the rest of the columns
  856.      * and their values.
  857.      *
  858.      * @param string                                                               $query  SQL query
  859.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  860.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  861.      *
  862.      * @return array<mixed,array<string,mixed>>
  863.      *
  864.      * @throws Exception
  865.      */
  866.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  867.     {
  868.         return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  869.     }
  871.     /**
  872.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  873.      *
  874.      * @param string                                                               $query  SQL query
  875.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  876.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  877.      *
  878.      * @return list<mixed>
  879.      *
  880.      * @throws Exception
  881.      */
  882.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  883.     {
  884.         return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  885.     }
  887.     /**
  888.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  889.      *
  890.      * @param string                                                               $query  SQL query
  891.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  892.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  893.      *
  894.      * @return Traversable<int,list<mixed>>
  895.      *
  896.      * @throws Exception
  897.      */
  898.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  899.     {
  900.         return $this->executeQuery($query, $params, $types)->iterateNumeric();
  901.     }
  903.     /**
  904.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  905.      * as associative arrays.
  906.      *
  907.      * @param string                                                               $query  SQL query
  908.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  909.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  910.      *
  911.      * @return Traversable<int,array<string,mixed>>
  912.      *
  913.      * @throws Exception
  914.      */
  915.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  916.     {
  917.         return $this->executeQuery($query, $params, $types)->iterateAssociative();
  918.     }
  920.     /**
  921.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  922.      * mapped to the first column and the values mapped to the second column.
  923.      *
  924.      * @param string                                                               $query  SQL query
  925.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  926.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  927.      *
  928.      * @return Traversable<mixed,mixed>
  929.      *
  930.      * @throws Exception
  931.      */
  932.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  933.     {
  934.         return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  935.     }
  937.     /**
  938.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  939.      * to the first column and the values being an associative array representing the rest of the columns
  940.      * and their values.
  941.      *
  942.      * @param string                                           $query  SQL query
  943.      * @param list<mixed>|array<string, mixed>                 $params Query parameters
  944.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  945.      *
  946.      * @return Traversable<mixed,array<string,mixed>>
  947.      *
  948.      * @throws Exception
  949.      */
  950.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  951.     {
  952.         return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  953.     }
  955.     /**
  956.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  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,mixed>
  963.      *
  964.      * @throws Exception
  965.      */
  966.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  967.     {
  968.         return $this->executeQuery($query, $params, $types)->iterateColumn();
  969.     }
  971.     /**
  972.      * Prepares an SQL statement.
  973.      *
  974.      * @param string $sql The SQL statement to prepare.
  975.      *
  976.      * @throws Exception
  977.      */
  978.     public function prepare(string $sql): Statement
  979.     {
  980.         $connection = $this->getWrappedConnection();
  982.         try {
  983.             $statement = $connection->prepare($sql);
  984.         } catch (Driver\Exception $e) {
  985.             throw $this->convertExceptionDuringQuery($e, $sql);
  986.         }
  988.         return new Statement($this, $statement, $sql);
  989.     }
  991.     /**
  992.      * Executes an, optionally parametrized, SQL query.
  993.      *
  994.      * If the query is parametrized, a prepared statement is used.
  995.      * If an SQLLogger is configured, the execution is logged.
  996.      *
  997.      * @param string                                                               $sql    SQL query
  998.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  999.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1000.      *
  1001.      * @throws Exception
  1002.      */
  1003.     public function executeQuery(
  1004.         string $sql,
  1005.         array $params = [],
  1006.         $types = [],
  1007.         ?QueryCacheProfile $qcp = null
  1008.     ): Result {
  1009.         if ($qcp !== null) {
  1010.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1011.         }
  1013.         $connection = $this->getWrappedConnection();
  1015.         $logger = $this->_config->getSQLLogger();
  1016.         if ($logger !== null) {
  1017.             $logger->startQuery($sql, $params, $types);
  1018.         }
  1020.         try {
  1021.             if (count($params) > 0) {
  1022.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1023.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1024.                 }
  1026.                 $stmt = $connection->prepare($sql);
  1027.                 if (count($types) > 0) {
  1028.                     $this->_bindTypedValues($stmt, $params, $types);
  1029.                     $result = $stmt->execute();
  1030.                 } else {
  1031.                     $result = $stmt->execute($params);
  1032.                 }
  1033.             } else {
  1034.                 $result = $connection->query($sql);
  1035.             }
  1037.             return new Result($result, $this);
  1038.         } catch (Driver\Exception $e) {
  1039.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1040.         } finally {
  1041.             if ($logger !== null) {
  1042.                 $logger->stopQuery();
  1043.             }
  1044.         }
  1045.     }
  1047.     /**
  1048.      * Executes a caching query.
  1049.      *
  1050.      * @param string                                                               $sql    SQL query
  1051.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1052.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1053.      *
  1054.      * @throws CacheException
  1055.      * @throws Exception
  1056.      */
  1057.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1058.     {
  1059.         $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1061.         if ($resultCache === null) {
  1062.             throw CacheException::noResultDriverConfigured();
  1063.         }
  1065.         $connectionParams = $this->params;
  1066.         unset($connectionParams['platform']);
  1068.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1070.         $item = $resultCache->getItem($cacheKey);
  1072.         if ($item->isHit()) {
  1073.             $value = $item->get();
  1074.             if (isset($value[$realKey])) {
  1075.                 return new Result(new ArrayResult($value[$realKey]), $this);
  1076.             }
  1077.         } else {
  1078.             $value = [];
  1079.         }
  1081.         $data = $this->fetchAllAssociative($sql, $params, $types);
  1083.         $value[$realKey] = $data;
  1085.         $item->set($value);
  1087.         $lifetime = $qcp->getLifetime();
  1088.         if ($lifetime > 0) {
  1089.             $item->expiresAfter($lifetime);
  1090.         }
  1092.         $resultCache->save($item);
  1094.         return new Result(new ArrayResult($data), $this);
  1095.     }
  1097.     /**
  1098.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1099.      *
  1100.      * Could be used for:
  1101.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1102.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1103.      *  - DCL statements: GRANT, REVOKE, etc.
  1104.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1105.      *  - Other statements that don't yield a row set.
  1106.      *
  1107.      * This method supports PDO binding types as well as DBAL mapping types.
  1108.      *
  1109.      * @param string                                                               $sql    SQL statement
  1110.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1111.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1112.      *
  1113.      * @return int The number of affected rows.
  1114.      *
  1115.      * @throws Exception
  1116.      */
  1117.     public function executeStatement($sql, array $params = [], array $types = [])
  1118.     {
  1119.         $connection = $this->getWrappedConnection();
  1121.         $logger = $this->_config->getSQLLogger();
  1122.         if ($logger !== null) {
  1123.             $logger->startQuery($sql, $params, $types);
  1124.         }
  1126.         try {
  1127.             if (count($params) > 0) {
  1128.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1129.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1130.                 }
  1132.                 $stmt = $connection->prepare($sql);
  1134.                 if (count($types) > 0) {
  1135.                     $this->_bindTypedValues($stmt, $params, $types);
  1137.                     $result = $stmt->execute();
  1138.                 } else {
  1139.                     $result = $stmt->execute($params);
  1140.                 }
  1142.                 return $result->rowCount();
  1143.             }
  1145.             return $connection->exec($sql);
  1146.         } catch (Driver\Exception $e) {
  1147.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1148.         } finally {
  1149.             if ($logger !== null) {
  1150.                 $logger->stopQuery();
  1151.             }
  1152.         }
  1153.     }
  1155.     /**
  1156.      * Returns the current transaction nesting level.
  1157.      *
  1158.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1159.      */
  1160.     public function getTransactionNestingLevel()
  1161.     {
  1162.         return $this->transactionNestingLevel;
  1163.     }
  1165.     /**
  1166.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1167.      * depending on the underlying driver.
  1168.      *
  1169.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1170.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1171.      * columns or sequences.
  1172.      *
  1173.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1174.      *
  1175.      * @return string|int|false A string representation of the last inserted ID.
  1176.      *
  1177.      * @throws Exception
  1178.      */
  1179.     public function lastInsertId($name = null)
  1180.     {
  1181.         if ($name !== null) {
  1182.             Deprecation::trigger(
  1183.                 'doctrine/dbal',
  1184.                 'https://github.com/doctrine/dbal/issues/4687',
  1185.                 'The usage of Connection::lastInsertId() with a sequence name is deprecated.'
  1186.             );
  1187.         }
  1189.         try {
  1190.             return $this->getWrappedConnection()->lastInsertId($name);
  1191.         } catch (Driver\Exception $e) {
  1192.             throw $this->convertException($e);
  1193.         }
  1194.     }
  1196.     /**
  1197.      * Executes a function in a transaction.
  1198.      *
  1199.      * The function gets passed this Connection instance as an (optional) parameter.
  1200.      *
  1201.      * If an exception occurs during execution of the function or transaction commit,
  1202.      * the transaction is rolled back and the exception re-thrown.
  1203.      *
  1204.      * @param Closure $func The function to execute transactionally.
  1205.      *
  1206.      * @return mixed The value returned by $func
  1207.      *
  1208.      * @throws Throwable
  1209.      */
  1210.     public function transactional(Closure $func)
  1211.     {
  1212.         $this->beginTransaction();
  1213.         try {
  1214.             $res = $func($this);
  1215.             $this->commit();
  1217.             return $res;
  1218.         } catch (Throwable $e) {
  1219.             $this->rollBack();
  1221.             throw $e;
  1222.         }
  1223.     }
  1225.     /**
  1226.      * Sets if nested transactions should use savepoints.
  1227.      *
  1228.      * @param bool $nestTransactionsWithSavepoints
  1229.      *
  1230.      * @return void
  1231.      *
  1232.      * @throws Exception
  1233.      */
  1234.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1235.     {
  1236.         if ($this->transactionNestingLevel > 0) {
  1237.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1238.         }
  1240.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1241.             throw ConnectionException::savepointsNotSupported();
  1242.         }
  1244.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1245.     }
  1247.     /**
  1248.      * Gets if nested transactions should use savepoints.
  1249.      *
  1250.      * @return bool
  1251.      */
  1252.     public function getNestTransactionsWithSavepoints()
  1253.     {
  1254.         return $this->nestTransactionsWithSavepoints;
  1255.     }
  1257.     /**
  1258.      * Returns the savepoint name to use for nested transactions.
  1259.      *
  1260.      * @return string
  1261.      */
  1262.     protected function _getNestedTransactionSavePointName()
  1263.     {
  1264.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1265.     }
  1267.     /**
  1268.      * @return bool
  1269.      *
  1270.      * @throws Exception
  1271.      */
  1272.     public function beginTransaction()
  1273.     {
  1274.         $connection = $this->getWrappedConnection();
  1276.         ++$this->transactionNestingLevel;
  1278.         $logger = $this->_config->getSQLLogger();
  1280.         if ($this->transactionNestingLevel === 1) {
  1281.             if ($logger !== null) {
  1282.                 $logger->startQuery('"START TRANSACTION"');
  1283.             }
  1285.             $connection->beginTransaction();
  1287.             if ($logger !== null) {
  1288.                 $logger->stopQuery();
  1289.             }
  1290.         } elseif ($this->nestTransactionsWithSavepoints) {
  1291.             if ($logger !== null) {
  1292.                 $logger->startQuery('"SAVEPOINT"');
  1293.             }
  1295.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1296.             if ($logger !== null) {
  1297.                 $logger->stopQuery();
  1298.             }
  1299.         }
  1301.         $this->getEventManager()->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1303.         return true;
  1304.     }
  1306.     /**
  1307.      * @return bool
  1308.      *
  1309.      * @throws Exception
  1310.      */
  1311.     public function commit()
  1312.     {
  1313.         if ($this->transactionNestingLevel === 0) {
  1314.             throw ConnectionException::noActiveTransaction();
  1315.         }
  1317.         if ($this->isRollbackOnly) {
  1318.             throw ConnectionException::commitFailedRollbackOnly();
  1319.         }
  1321.         $result = true;
  1323.         $connection = $this->getWrappedConnection();
  1325.         $logger = $this->_config->getSQLLogger();
  1327.         if ($this->transactionNestingLevel === 1) {
  1328.             if ($logger !== null) {
  1329.                 $logger->startQuery('"COMMIT"');
  1330.             }
  1332.             $result = $connection->commit();
  1334.             if ($logger !== null) {
  1335.                 $logger->stopQuery();
  1336.             }
  1337.         } elseif ($this->nestTransactionsWithSavepoints) {
  1338.             if ($logger !== null) {
  1339.                 $logger->startQuery('"RELEASE SAVEPOINT"');
  1340.             }
  1342.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1343.             if ($logger !== null) {
  1344.                 $logger->stopQuery();
  1345.             }
  1346.         }
  1348.         --$this->transactionNestingLevel;
  1350.         $this->getEventManager()->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  1352.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1353.             return $result;
  1354.         }
  1356.         $this->beginTransaction();
  1358.         return $result;
  1359.     }
  1361.     /**
  1362.      * Commits all current nesting transactions.
  1363.      *
  1364.      * @throws Exception
  1365.      */
  1366.     private function commitAll(): void
  1367.     {
  1368.         while ($this->transactionNestingLevel !== 0) {
  1369.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1370.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1371.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1372.                 $this->commit();
  1374.                 return;
  1375.             }
  1377.             $this->commit();
  1378.         }
  1379.     }
  1381.     /**
  1382.      * Cancels any database changes done during the current transaction.
  1383.      *
  1384.      * @return bool
  1385.      *
  1386.      * @throws Exception
  1387.      */
  1388.     public function rollBack()
  1389.     {
  1390.         if ($this->transactionNestingLevel === 0) {
  1391.             throw ConnectionException::noActiveTransaction();
  1392.         }
  1394.         $connection = $this->getWrappedConnection();
  1396.         $logger = $this->_config->getSQLLogger();
  1398.         if ($this->transactionNestingLevel === 1) {
  1399.             if ($logger !== null) {
  1400.                 $logger->startQuery('"ROLLBACK"');
  1401.             }
  1403.             $this->transactionNestingLevel = 0;
  1404.             $connection->rollBack();
  1405.             $this->isRollbackOnly = false;
  1406.             if ($logger !== null) {
  1407.                 $logger->stopQuery();
  1408.             }
  1410.             if ($this->autoCommit === false) {
  1411.                 $this->beginTransaction();
  1412.             }
  1413.         } elseif ($this->nestTransactionsWithSavepoints) {
  1414.             if ($logger !== null) {
  1415.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1416.             }
  1418.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1419.             --$this->transactionNestingLevel;
  1420.             if ($logger !== null) {
  1421.                 $logger->stopQuery();
  1422.             }
  1423.         } else {
  1424.             $this->isRollbackOnly = true;
  1425.             --$this->transactionNestingLevel;
  1426.         }
  1428.         $this->getEventManager()->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1430.         return true;
  1431.     }
  1433.     /**
  1434.      * Creates a new savepoint.
  1435.      *
  1436.      * @param string $savepoint The name of the savepoint to create.
  1437.      *
  1438.      * @return void
  1439.      *
  1440.      * @throws Exception
  1441.      */
  1442.     public function createSavepoint($savepoint)
  1443.     {
  1444.         $platform = $this->getDatabasePlatform();
  1446.         if (! $platform->supportsSavepoints()) {
  1447.             throw ConnectionException::savepointsNotSupported();
  1448.         }
  1450.         $this->executeStatement($platform->createSavePoint($savepoint));
  1451.     }
  1453.     /**
  1454.      * Releases the given savepoint.
  1455.      *
  1456.      * @param string $savepoint The name of the savepoint to release.
  1457.      *
  1458.      * @return void
  1459.      *
  1460.      * @throws Exception
  1461.      */
  1462.     public function releaseSavepoint($savepoint)
  1463.     {
  1464.         $platform = $this->getDatabasePlatform();
  1466.         if (! $platform->supportsSavepoints()) {
  1467.             throw ConnectionException::savepointsNotSupported();
  1468.         }
  1470.         if (! $platform->supportsReleaseSavepoints()) {
  1471.             return;
  1472.         }
  1474.         $this->executeStatement($platform->releaseSavePoint($savepoint));
  1475.     }
  1477.     /**
  1478.      * Rolls back to the given savepoint.
  1479.      *
  1480.      * @param string $savepoint The name of the savepoint to rollback to.
  1481.      *
  1482.      * @return void
  1483.      *
  1484.      * @throws Exception
  1485.      */
  1486.     public function rollbackSavepoint($savepoint)
  1487.     {
  1488.         $platform = $this->getDatabasePlatform();
  1490.         if (! $platform->supportsSavepoints()) {
  1491.             throw ConnectionException::savepointsNotSupported();
  1492.         }
  1494.         $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1495.     }
  1497.     /**
  1498.      * Gets the wrapped driver connection.
  1499.      *
  1500.      * @return DriverConnection
  1501.      *
  1502.      * @throws Exception
  1503.      */
  1504.     public function getWrappedConnection()
  1505.     {
  1506.         $this->connect();
  1508.         assert($this->_conn !== null);
  1510.         return $this->_conn;
  1511.     }
  1513.     /**
  1514.      * Creates a SchemaManager that can be used to inspect or change the
  1515.      * database schema through the connection.
  1516.      *
  1517.      * @throws Exception
  1518.      */
  1519.     public function createSchemaManager(): AbstractSchemaManager
  1520.     {
  1521.         return $this->_driver->getSchemaManager(
  1522.             $this,
  1523.             $this->getDatabasePlatform()
  1524.         );
  1525.     }
  1527.     /**
  1528.      * Gets the SchemaManager that can be used to inspect or change the
  1529.      * database schema through the connection.
  1530.      *
  1531.      * @deprecated Use {@see createSchemaManager()} instead.
  1532.      *
  1533.      * @return AbstractSchemaManager
  1534.      *
  1535.      * @throws Exception
  1536.      */
  1537.     public function getSchemaManager()
  1538.     {
  1539.         Deprecation::triggerIfCalledFromOutside(
  1540.             'doctrine/dbal',
  1541.             'https://github.com/doctrine/dbal/issues/4515',
  1542.             'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.'
  1543.         );
  1545.         if ($this->_schemaManager === null) {
  1546.             $this->_schemaManager = $this->createSchemaManager();
  1547.         }
  1549.         return $this->_schemaManager;
  1550.     }
  1552.     /**
  1553.      * Marks the current transaction so that the only possible
  1554.      * outcome for the transaction to be rolled back.
  1555.      *
  1556.      * @return void
  1557.      *
  1558.      * @throws ConnectionException If no transaction is active.
  1559.      */
  1560.     public function setRollbackOnly()
  1561.     {
  1562.         if ($this->transactionNestingLevel === 0) {
  1563.             throw ConnectionException::noActiveTransaction();
  1564.         }
  1566.         $this->isRollbackOnly = true;
  1567.     }
  1569.     /**
  1570.      * Checks whether the current transaction is marked for rollback only.
  1571.      *
  1572.      * @return bool
  1573.      *
  1574.      * @throws ConnectionException If no transaction is active.
  1575.      */
  1576.     public function isRollbackOnly()
  1577.     {
  1578.         if ($this->transactionNestingLevel === 0) {
  1579.             throw ConnectionException::noActiveTransaction();
  1580.         }
  1582.         return $this->isRollbackOnly;
  1583.     }
  1585.     /**
  1586.      * Converts a given value to its database representation according to the conversion
  1587.      * rules of a specific DBAL mapping type.
  1588.      *
  1589.      * @param mixed  $value The value to convert.
  1590.      * @param string $type  The name of the DBAL mapping type.
  1591.      *
  1592.      * @return mixed The converted value.
  1593.      *
  1594.      * @throws Exception
  1595.      */
  1596.     public function convertToDatabaseValue($value, $type)
  1597.     {
  1598.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1599.     }
  1601.     /**
  1602.      * Converts a given value to its PHP representation according to the conversion
  1603.      * rules of a specific DBAL mapping type.
  1604.      *
  1605.      * @param mixed  $value The value to convert.
  1606.      * @param string $type  The name of the DBAL mapping type.
  1607.      *
  1608.      * @return mixed The converted type.
  1609.      *
  1610.      * @throws Exception
  1611.      */
  1612.     public function convertToPHPValue($value, $type)
  1613.     {
  1614.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1615.     }
  1617.     /**
  1618.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1619.      * or DBAL mapping type, to a given statement.
  1620.      *
  1621.      * @param DriverStatement                                                      $stmt   Prepared statement
  1622.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1623.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1624.      *
  1625.      * @throws Exception
  1626.      */
  1627.     private function _bindTypedValues(DriverStatement $stmt, array $params, array $types): void
  1628.     {
  1629.         // Check whether parameters are positional or named. Mixing is not allowed.
  1630.         if (is_int(key($params))) {
  1631.             $bindIndex = 1;
  1633.             foreach ($params as $key => $value) {
  1634.                 if (isset($types[$key])) {
  1635.                     $type                  = $types[$key];
  1636.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1637.                     $stmt->bindValue($bindIndex, $value, $bindingType);
  1638.                 } else {
  1639.                     $stmt->bindValue($bindIndex, $value);
  1640.                 }
  1642.                 ++$bindIndex;
  1643.             }
  1644.         } else {
  1645.             // Named parameters
  1646.             foreach ($params as $name => $value) {
  1647.                 if (isset($types[$name])) {
  1648.                     $type                  = $types[$name];
  1649.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1650.                     $stmt->bindValue($name, $value, $bindingType);
  1651.                 } else {
  1652.                     $stmt->bindValue($name, $value);
  1653.                 }
  1654.             }
  1655.         }
  1656.     }
  1658.     /**
  1659.      * Gets the binding type of a given type.
  1660.      *
  1661.      * @param mixed                $value The value to bind.
  1662.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  1663.      *
  1664.      * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1665.      *
  1666.      * @throws Exception
  1667.      */
  1668.     private function getBindingInfo($value, $type): array
  1669.     {
  1670.         if (is_string($type)) {
  1671.             $type = Type::getType($type);
  1672.         }
  1674.         if ($type instanceof Type) {
  1675.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1676.             $bindingType = $type->getBindingType();
  1677.         } else {
  1678.             $bindingType = $type ?? ParameterType::STRING;
  1679.         }
  1681.         return [$value, $bindingType];
  1682.     }
  1684.     /**
  1685.      * Creates a new instance of a SQL query builder.
  1686.      *
  1687.      * @return QueryBuilder
  1688.      */
  1689.     public function createQueryBuilder()
  1690.     {
  1691.         return new Query\QueryBuilder($this);
  1692.     }
  1694.     /**
  1695.      * @internal
  1696.      *
  1697.      * @param list<mixed>|array<string, mixed>                                     $params
  1698.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1699.      */
  1700.     final public function convertExceptionDuringQuery(
  1701.         Driver\Exception $e,
  1702.         string $sql,
  1703.         array $params = [],
  1704.         array $types = []
  1705.     ): DriverException {
  1706.         return $this->handleDriverException($e, new Query($sql, $params, $types));
  1707.     }
  1709.     /**
  1710.      * @internal
  1711.      */
  1712.     final public function convertException(Driver\Exception $e): DriverException
  1713.     {
  1714.         return $this->handleDriverException($e, null);
  1715.     }
  1717.     /**
  1718.      * @param array<int, mixed>|array<string, mixed>                               $params
  1719.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1720.      *
  1721.      * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1722.      */
  1723.     private function expandArrayParameters(string $sql, array $params, array $types): array
  1724.     {
  1725.         if ($this->parser === null) {
  1726.             $this->parser = $this->getDatabasePlatform()->createSQLParser();
  1727.         }
  1729.         $visitor = new ExpandArrayParameters($params, $types);
  1731.         $this->parser->parse($sql, $visitor);
  1733.         return [
  1734.             $visitor->getSQL(),
  1735.             $visitor->getParameters(),
  1736.             $visitor->getTypes(),
  1737.         ];
  1738.     }
  1740.     /**
  1741.      * @param array<int, mixed>|array<string, mixed>                               $params
  1742.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1743.      */
  1744.     private function needsArrayParameterConversion(array $params, array $types): bool
  1745.     {
  1746.         if (is_string(key($params))) {
  1747.             return true;
  1748.         }
  1750.         foreach ($types as $type) {
  1751.             if ($type === self::PARAM_INT_ARRAY || $type === self::PARAM_STR_ARRAY) {
  1752.                 return true;
  1753.             }
  1754.         }
  1756.         return false;
  1757.     }
  1759.     private function handleDriverException(
  1760.         Driver\Exception $driverException,
  1761.         ?Query $query
  1762.     ): DriverException {
  1763.         if ($this->exceptionConverter === null) {
  1764.             $this->exceptionConverter = $this->_driver->getExceptionConverter();
  1765.         }
  1767.         $exception = $this->exceptionConverter->convert($driverException, $query);
  1769.         if ($exception instanceof ConnectionLost) {
  1770.             $this->close();
  1771.         }
  1773.         return $exception;
  1774.     }
  1776.     /**
  1777.      * BC layer for a wide-spread use-case of old DBAL APIs
  1778.      *
  1779.      * @deprecated This API is deprecated and will be removed after 2022
  1780.      *
  1781.      * @param array<mixed>           $params The query parameters
  1782.      * @param array<int|string|null> $types  The parameter types
  1783.      */
  1784.     public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1785.     {
  1786.         return $this->executeStatement($sql, $params, $types);
  1787.     }
  1789.     /**
  1790.      * BC layer for a wide-spread use-case of old DBAL APIs
  1791.      *
  1792.      * @deprecated This API is deprecated and will be removed after 2022
  1793.      */
  1794.     public function query(string $sql): Result
  1795.     {
  1796.         return $this->executeQuery($sql);
  1797.     }
  1799.     /**
  1800.      * BC layer for a wide-spread use-case of old DBAL APIs
  1801.      *
  1802.      * @deprecated This API is deprecated and will be removed after 2022
  1803.      */
  1804.     public function exec(string $sql): int
  1805.     {
  1806.         return $this->executeStatement($sql);
  1807.     }
  1808. }