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

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