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

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayResult;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Driver\API\ExceptionConverter;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  13. use Doctrine\DBAL\Driver\Statement as DriverStatement;
  14. use Doctrine\DBAL\Event\TransactionBeginEventArgs;
  15. use Doctrine\DBAL\Event\TransactionCommitEventArgs;
  16. use Doctrine\DBAL\Event\TransactionRollBackEventArgs;
  17. use Doctrine\DBAL\Exception\ConnectionLost;
  18. use Doctrine\DBAL\Exception\DriverException;
  19. use Doctrine\DBAL\Exception\InvalidArgumentException;
  20. use Doctrine\DBAL\Platforms\AbstractPlatform;
  21. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  22. use Doctrine\DBAL\Query\QueryBuilder;
  23. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  24. use Doctrine\DBAL\SQL\Parser;
  25. use Doctrine\DBAL\Types\Type;
  26. use Doctrine\Deprecations\Deprecation;
  27. use LogicException;
  28. use Throwable;
  29. use Traversable;
  31. use function assert;
  32. use function count;
  33. use function get_class;
  34. use function implode;
  35. use function is_int;
  36. use function is_string;
  37. use function key;
  38. use function method_exists;
  39. use function sprintf;
  41. /**
  42.  * A database abstraction-level connection that implements features like events, transaction isolation levels,
  43.  * configuration, emulated transaction nesting, lazy connecting and more.
  44.  *
  45.  * @psalm-import-type Params from DriverManager
  46.  * @psalm-consistent-constructor
  47.  */
  48. class Connection
  49. {
  50.     /**
  51.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  52.      */
  53.     public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  55.     /**
  56.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  57.      */
  58.     public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  60.     /**
  61.      * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
  62.      */
  63.     public const PARAM_ASCII_STR_ARRAY = ParameterType::ASCII + self::ARRAY_PARAM_OFFSET;
  65.     /**
  66.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  67.      */
  68.     public const ARRAY_PARAM_OFFSET = 100;
  70.     /**
  71.      * The wrapped driver connection.
  72.      *
  73.      * @var \Doctrine\DBAL\Driver\Connection|null
  74.      */
  75.     protected $_conn;
  77.     /** @var Configuration */
  78.     protected $_config;
  80.     /** @var EventManager */
  81.     protected $_eventManager;
  83.     /**
  84.      * @deprecated Use {@see createExpressionBuilder()} instead.
  85.      *
  86.      * @var ExpressionBuilder
  87.      */
  88.     protected $_expr;
  90.     /**
  91.      * The current auto-commit mode of this connection.
  92.      *
  93.      * @var bool
  94.      */
  95.     private $autoCommit = true;
  97.     /**
  98.      * The transaction nesting level.
  99.      *
  100.      * @var int
  101.      */
  102.     private $transactionNestingLevel = 0;
  104.     /**
  105.      * The currently active transaction isolation level or NULL before it has been determined.
  106.      *
  107.      * @var int|null
  108.      */
  109.     private $transactionIsolationLevel;
  111.     /**
  112.      * If nested transactions should use savepoints.
  113.      *
  114.      * @var bool
  115.      */
  116.     private $nestTransactionsWithSavepoints = false;
  118.     /**
  119.      * The parameters used during creation of the Connection instance.
  120.      *
  121.      * @var array<string,mixed>
  122.      * @psalm-var Params
  123.      */
  124.     private $params;
  126.     /**
  127.      * The database platform object used by the connection or NULL before it's initialized.
  128.      *
  129.      * @var AbstractPlatform|null
  130.      */
  131.     private $platform;
  133.     /** @var ExceptionConverter|null */
  134.     private $exceptionConverter;
  136.     /** @var Parser|null */
  137.     private $parser;
  139.     /**
  140.      * The schema manager.
  141.      *
  142.      * @deprecated Use {@see createSchemaManager()} instead.
  143.      *
  144.      * @var AbstractSchemaManager|null
  145.      */
  146.     protected $_schemaManager;
  148.     /**
  149.      * The used DBAL driver.
  150.      *
  151.      * @var Driver
  152.      */
  153.     protected $_driver;
  155.     /**
  156.      * Flag that indicates whether the current transaction is marked for rollback only.
  157.      *
  158.      * @var bool
  159.      */
  160.     private $isRollbackOnly = false;
  162.     /**
  163.      * Initializes a new instance of the Connection class.
  164.      *
  165.      * @internal The connection can be only instantiated by the driver manager.
  166.      *
  167.      * @param array<string,mixed> $params       The connection parameters.
  168.      * @param Driver              $driver       The driver to use.
  169.      * @param Configuration|null  $config       The configuration, optional.
  170.      * @param EventManager|null   $eventManager The event manager, optional.
  171.      * @psalm-param Params $params
  172.      * @phpstan-param array<string,mixed> $params
  173.      *
  174.      * @throws Exception
  175.      */
  176.     public function __construct(
  177.         array $params,
  178.         Driver $driver,
  179.         ?Configuration $config = null,
  180.         ?EventManager $eventManager = null
  181.     ) {
  182.         $this->_driver = $driver;
  183.         $this->params  = $params;
  185.         if (isset($params['platform'])) {
  186.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  187.                 throw Exception::invalidPlatformType($params['platform']);
  188.             }
  190.             $this->platform = $params['platform'];
  191.         }
  193.         // Create default config and event manager if none given
  194.         if ($config === null) {
  195.             $config = new Configuration();
  196.         }
  198.         if ($eventManager === null) {
  199.             $eventManager = new EventManager();
  200.         }
  202.         $this->_config       = $config;
  203.         $this->_eventManager = $eventManager;
  205.         $this->_expr = $this->createExpressionBuilder();
  207.         $this->autoCommit = $config->getAutoCommit();
  208.     }
  210.     /**
  211.      * Gets the parameters used during instantiation.
  212.      *
  213.      * @internal
  214.      *
  215.      * @return array<string,mixed>
  216.      * @psalm-return Params
  217.      */
  218.     public function getParams()
  219.     {
  220.         return $this->params;
  221.     }
  223.     /**
  224.      * Gets the name of the currently selected database.
  225.      *
  226.      * @return string|null The name of the database or NULL if a database is not selected.
  227.      *                     The platforms which don't support the concept of a database (e.g. embedded databases)
  228.      *                     must always return a string as an indicator of an implicitly selected database.
  229.      *
  230.      * @throws Exception
  231.      */
  232.     public function getDatabase()
  233.     {
  234.         $platform = $this->getDatabasePlatform();
  235.         $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  236.         $database = $this->fetchOne($query);
  238.         assert(is_string($database) || $database === null);
  240.         return $database;
  241.     }
  243.     /**
  244.      * Gets the DBAL driver instance.
  245.      *
  246.      * @return Driver
  247.      */
  248.     public function getDriver()
  249.     {
  250.         return $this->_driver;
  251.     }
  253.     /**
  254.      * Gets the Configuration used by the Connection.
  255.      *
  256.      * @return Configuration
  257.      */
  258.     public function getConfiguration()
  259.     {
  260.         return $this->_config;
  261.     }
  263.     /**
  264.      * Gets the EventManager used by the Connection.
  265.      *
  266.      * @return EventManager
  267.      */
  268.     public function getEventManager()
  269.     {
  270.         return $this->_eventManager;
  271.     }
  273.     /**
  274.      * Gets the DatabasePlatform for the connection.
  275.      *
  276.      * @return AbstractPlatform
  277.      *
  278.      * @throws Exception
  279.      */
  280.     public function getDatabasePlatform()
  281.     {
  282.         if ($this->platform === null) {
  283.             $this->platform = $this->detectDatabasePlatform();
  284.             $this->platform->setEventManager($this->_eventManager);
  285.         }
  287.         return $this->platform;
  288.     }
  290.     /**
  291.      * Creates an expression builder for the connection.
  292.      */
  293.     public function createExpressionBuilder(): ExpressionBuilder
  294.     {
  295.         return new ExpressionBuilder($this);
  296.     }
  298.     /**
  299.      * Gets the ExpressionBuilder for the connection.
  300.      *
  301.      * @deprecated Use {@see createExpressionBuilder()} instead.
  302.      *
  303.      * @return ExpressionBuilder
  304.      */
  305.     public function getExpressionBuilder()
  306.     {
  307.         Deprecation::triggerIfCalledFromOutside(
  308.             'doctrine/dbal',
  309.             'https://github.com/doctrine/dbal/issues/4515',
  310.             'Connection::getExpressionBuilder() is deprecated,'
  311.                 . ' use Connection::createExpressionBuilder() instead.'
  312.         );
  314.         return $this->_expr;
  315.     }
  317.     /**
  318.      * Establishes the connection with the database.
  319.      *
  320.      * @internal This method will be made protected in DBAL 4.0.
  321.      *
  322.      * @return bool TRUE if the connection was successfully established, FALSE if
  323.      *              the connection is already open.
  324.      *
  325.      * @throws Exception
  326.      */
  327.     public function connect()
  328.     {
  329.         Deprecation::triggerIfCalledFromOutside(
  330.             'doctrine/dbal',
  331.             'https://github.com/doctrine/dbal/issues/4966',
  332.             'Public access to Connection::connect() is deprecated.'
  333.         );
  335.         if ($this->_conn !== null) {
  336.             return false;
  337.         }
  339.         try {
  340.             $this->_conn = $this->_driver->connect($this->params);
  341.         } catch (Driver\Exception $e) {
  342.             throw $this->convertException($e);
  343.         }
  345.         if ($this->autoCommit === false) {
  346.             $this->beginTransaction();
  347.         }
  349.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  350.             $eventArgs = new Event\ConnectionEventArgs($this);
  351.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  352.         }
  354.         return true;
  355.     }
  357.     /**
  358.      * Detects and sets the database platform.
  359.      *
  360.      * Evaluates custom platform class and version in order to set the correct platform.
  361.      *
  362.      * @throws Exception If an invalid platform was specified for this connection.
  363.      */
  364.     private function detectDatabasePlatform(): AbstractPlatform
  365.     {
  366.         $version = $this->getDatabasePlatformVersion();
  368.         if ($version !== null) {
  369.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  371.             return $this->_driver->createDatabasePlatformForVersion($version);
  372.         }
  374.         return $this->_driver->getDatabasePlatform();
  375.     }
  377.     /**
  378.      * Returns the version of the related platform if applicable.
  379.      *
  380.      * Returns null if either the driver is not capable to create version
  381.      * specific platform instances, no explicit server version was specified
  382.      * or the underlying driver connection cannot determine the platform
  383.      * version without having to query it (performance reasons).
  384.      *
  385.      * @return string|null
  386.      *
  387.      * @throws Throwable
  388.      */
  389.     private function getDatabasePlatformVersion()
  390.     {
  391.         // Driver does not support version specific platforms.
  392.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  393.             return null;
  394.         }
  396.         // Explicit platform version requested (supersedes auto-detection).
  397.         if (isset($this->params['serverVersion'])) {
  398.             return $this->params['serverVersion'];
  399.         }
  401.         // If not connected, we need to connect now to determine the platform version.
  402.         if ($this->_conn === null) {
  403.             try {
  404.                 $this->connect();
  405.             } catch (Exception $originalException) {
  406.                 if (! isset($this->params['dbname'])) {
  407.                     throw $originalException;
  408.                 }
  410.                 // The database to connect to might not yet exist.
  411.                 // Retry detection without database name connection parameter.
  412.                 $params = $this->params;
  414.                 unset($this->params['dbname']);
  416.                 try {
  417.                     $this->connect();
  418.                 } catch (Exception $fallbackException) {
  419.                     // Either the platform does not support database-less connections
  420.                     // or something else went wrong.
  421.                     throw $originalException;
  422.                 } finally {
  423.                     $this->params = $params;
  424.                 }
  426.                 $serverVersion = $this->getServerVersion();
  428.                 // Close "temporary" connection to allow connecting to the real database again.
  429.                 $this->close();
  431.                 return $serverVersion;
  432.             }
  433.         }
  435.         return $this->getServerVersion();
  436.     }
  438.     /**
  439.      * Returns the database server version if the underlying driver supports it.
  440.      *
  441.      * @return string|null
  442.      *
  443.      * @throws Exception
  444.      */
  445.     private function getServerVersion()
  446.     {
  447.         $connection = $this->getWrappedConnection();
  449.         // Automatic platform version detection.
  450.         if ($connection instanceof ServerInfoAwareConnection) {
  451.             try {
  452.                 return $connection->getServerVersion();
  453.             } catch (Driver\Exception $e) {
  454.                 throw $this->convertException($e);
  455.             }
  456.         }
  458.         Deprecation::trigger(
  459.             'doctrine/dbal',
  460.             'https://github.com/doctrine/dbal/pulls/4750',
  461.             'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  462.             get_class($connection)
  463.         );
  465.         // Unable to detect platform version.
  466.         return null;
  467.     }
  469.     /**
  470.      * Returns the current auto-commit mode for this connection.
  471.      *
  472.      * @see    setAutoCommit
  473.      *
  474.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  475.      */
  476.     public function isAutoCommit()
  477.     {
  478.         return $this->autoCommit === true;
  479.     }
  481.     /**
  482.      * Sets auto-commit mode for this connection.
  483.      *
  484.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  485.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  486.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  487.      *
  488.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  489.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  490.      *
  491.      * @see   isAutoCommit
  492.      *
  493.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  494.      *
  495.      * @return void
  496.      */
  497.     public function setAutoCommit($autoCommit)
  498.     {
  499.         $autoCommit = (bool) $autoCommit;
  501.         // Mode not changed, no-op.
  502.         if ($autoCommit === $this->autoCommit) {
  503.             return;
  504.         }
  506.         $this->autoCommit = $autoCommit;
  508.         // Commit all currently active transactions if any when switching auto-commit mode.
  509.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  510.             return;
  511.         }
  513.         $this->commitAll();
  514.     }
  516.     /**
  517.      * Prepares and executes an SQL query and returns the first row of the result
  518.      * as an associative array.
  519.      *
  520.      * @param string                                                               $query  SQL query
  521.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  522.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  523.      *
  524.      * @return array<string, mixed>|false False is returned if no rows are found.
  525.      *
  526.      * @throws Exception
  527.      */
  528.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  529.     {
  530.         return $this->executeQuery($query, $params, $types)->fetchAssociative();
  531.     }
  533.     /**
  534.      * Prepares and executes an SQL query and returns the first row of the result
  535.      * as a numerically indexed array.
  536.      *
  537.      * @param string                                                               $query  SQL query
  538.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  539.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  540.      *
  541.      * @return list<mixed>|false False is returned if no rows are found.
  542.      *
  543.      * @throws Exception
  544.      */
  545.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  546.     {
  547.         return $this->executeQuery($query, $params, $types)->fetchNumeric();
  548.     }
  550.     /**
  551.      * Prepares and executes an SQL query and returns the value of a single column
  552.      * of the first row of the result.
  553.      *
  554.      * @param string                                                               $query  SQL query
  555.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  556.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  557.      *
  558.      * @return mixed|false False is returned if no rows are found.
  559.      *
  560.      * @throws Exception
  561.      */
  562.     public function fetchOne(string $query, array $params = [], array $types = [])
  563.     {
  564.         return $this->executeQuery($query, $params, $types)->fetchOne();
  565.     }
  567.     /**
  568.      * Whether an actual connection to the database is established.
  569.      *
  570.      * @return bool
  571.      */
  572.     public function isConnected()
  573.     {
  574.         return $this->_conn !== null;
  575.     }
  577.     /**
  578.      * Checks whether a transaction is currently active.
  579.      *
  580.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  581.      */
  582.     public function isTransactionActive()
  583.     {
  584.         return $this->transactionNestingLevel > 0;
  585.     }
  587.     /**
  588.      * Adds condition based on the criteria to the query components
  589.      *
  590.      * @param array<string,mixed> $criteria   Map of key columns to their values
  591.      * @param string[]            $columns    Column names
  592.      * @param mixed[]             $values     Column values
  593.      * @param string[]            $conditions Key conditions
  594.      *
  595.      * @throws Exception
  596.      */
  597.     private function addCriteriaCondition(
  598.         array $criteria,
  599.         array &$columns,
  600.         array &$values,
  601.         array &$conditions
  602.     ): void {
  603.         $platform = $this->getDatabasePlatform();
  605.         foreach ($criteria as $columnName => $value) {
  606.             if ($value === null) {
  607.                 $conditions[] = $platform->getIsNullExpression($columnName);
  608.                 continue;
  609.             }
  611.             $columns[]    = $columnName;
  612.             $values[]     = $value;
  613.             $conditions[] = $columnName . ' = ?';
  614.         }
  615.     }
  617.     /**
  618.      * Executes an SQL DELETE statement on a table.
  619.      *
  620.      * Table expression and columns are not escaped and are not safe for user-input.
  621.      *
  622.      * @param string                                                               $table    Table name
  623.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  624.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  625.      *
  626.      * @return int|string The number of affected rows.
  627.      *
  628.      * @throws Exception
  629.      */
  630.     public function delete($table, array $criteria, array $types = [])
  631.     {
  632.         if (count($criteria) === 0) {
  633.             throw InvalidArgumentException::fromEmptyCriteria();
  634.         }
  636.         $columns = $values = $conditions = [];
  638.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  640.         return $this->executeStatement(
  641.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  642.             $values,
  643.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  644.         );
  645.     }
  647.     /**
  648.      * Closes the connection.
  649.      *
  650.      * @return void
  651.      */
  652.     public function close()
  653.     {
  654.         $this->_conn                   = null;
  655.         $this->transactionNestingLevel = 0;
  656.     }
  658.     /**
  659.      * Sets the transaction isolation level.
  660.      *
  661.      * @param int $level The level to set.
  662.      *
  663.      * @return int|string
  664.      *
  665.      * @throws Exception
  666.      */
  667.     public function setTransactionIsolation($level)
  668.     {
  669.         $this->transactionIsolationLevel = $level;
  671.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  672.     }
  674.     /**
  675.      * Gets the currently active transaction isolation level.
  676.      *
  677.      * @return int The current transaction isolation level.
  678.      *
  679.      * @throws Exception
  680.      */
  681.     public function getTransactionIsolation()
  682.     {
  683.         if ($this->transactionIsolationLevel === null) {
  684.             $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  685.         }
  687.         return $this->transactionIsolationLevel;
  688.     }
  690.     /**
  691.      * Executes an SQL UPDATE statement on a table.
  692.      *
  693.      * Table expression and columns are not escaped and are not safe for user-input.
  694.      *
  695.      * @param string                                                               $table    Table name
  696.      * @param array<string, mixed>                                                 $data     Column-value pairs
  697.      * @param array<string, mixed>                                                 $criteria Update criteria
  698.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  699.      *
  700.      * @return int|string The number of affected rows.
  701.      *
  702.      * @throws Exception
  703.      */
  704.     public function update($table, array $data, array $criteria, array $types = [])
  705.     {
  706.         $columns = $values = $conditions = $set = [];
  708.         foreach ($data as $columnName => $value) {
  709.             $columns[] = $columnName;
  710.             $values[]  = $value;
  711.             $set[]     = $columnName . ' = ?';
  712.         }
  714.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  716.         if (is_string(key($types))) {
  717.             $types = $this->extractTypeValues($columns, $types);
  718.         }
  720.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  721.                 . ' WHERE ' . implode(' AND ', $conditions);
  723.         return $this->executeStatement($sql, $values, $types);
  724.     }
  726.     /**
  727.      * Inserts a table row with specified data.
  728.      *
  729.      * Table expression and columns are not escaped and are not safe for user-input.
  730.      *
  731.      * @param string                                                               $table Table name
  732.      * @param array<string, mixed>                                                 $data  Column-value pairs
  733.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  734.      *
  735.      * @return int|string The number of affected rows.
  736.      *
  737.      * @throws Exception
  738.      */
  739.     public function insert($table, array $data, array $types = [])
  740.     {
  741.         if (count($data) === 0) {
  742.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  743.         }
  745.         $columns = [];
  746.         $values  = [];
  747.         $set     = [];
  749.         foreach ($data as $columnName => $value) {
  750.             $columns[] = $columnName;
  751.             $values[]  = $value;
  752.             $set[]     = '?';
  753.         }
  755.         return $this->executeStatement(
  756.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  757.             ' VALUES (' . implode(', ', $set) . ')',
  758.             $values,
  759.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  760.         );
  761.     }
  763.     /**
  764.      * Extract ordered type list from an ordered column list and type map.
  765.      *
  766.      * @param array<int, string>                                                   $columnList
  767.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  768.      *
  769.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  770.      */
  771.     private function extractTypeValues(array $columnList, array $types): array
  772.     {
  773.         $typeValues = [];
  775.         foreach ($columnList as $columnName) {
  776.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  777.         }
  779.         return $typeValues;
  780.     }
  782.     /**
  783.      * Quotes a string so it can be safely used as a table or column name, even if
  784.      * it is a reserved name.
  785.      *
  786.      * Delimiting style depends on the underlying database platform that is being used.
  787.      *
  788.      * NOTE: Just because you CAN use quoted identifiers does not mean
  789.      * you SHOULD use them. In general, they end up causing way more
  790.      * problems than they solve.
  791.      *
  792.      * @param string $str The name to be quoted.
  793.      *
  794.      * @return string The quoted name.
  795.      */
  796.     public function quoteIdentifier($str)
  797.     {
  798.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  799.     }
  801.     /**
  802.      * The usage of this method is discouraged. Use prepared statements
  803.      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  804.      *
  805.      * @param mixed                $value
  806.      * @param int|string|Type|null $type
  807.      *
  808.      * @return mixed
  809.      */
  810.     public function quote($value, $type = ParameterType::STRING)
  811.     {
  812.         $connection = $this->getWrappedConnection();
  814.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  816.         return $connection->quote($value, $bindingType);
  817.     }
  819.     /**
  820.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  821.      *
  822.      * @param string                                                               $query  SQL query
  823.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  824.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  825.      *
  826.      * @return list<list<mixed>>
  827.      *
  828.      * @throws Exception
  829.      */
  830.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  831.     {
  832.         return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  833.     }
  835.     /**
  836.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  837.      *
  838.      * @param string                                                               $query  SQL query
  839.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  840.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  841.      *
  842.      * @return list<array<string,mixed>>
  843.      *
  844.      * @throws Exception
  845.      */
  846.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  847.     {
  848.         return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  849.     }
  851.     /**
  852.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  853.      * mapped to the first column and the values mapped to the second column.
  854.      *
  855.      * @param string                                                               $query  SQL query
  856.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  857.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  858.      *
  859.      * @return array<mixed,mixed>
  860.      *
  861.      * @throws Exception
  862.      */
  863.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  864.     {
  865.         return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  866.     }
  868.     /**
  869.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  870.      * to the first column and the values being an associative array representing the rest of the columns
  871.      * and their values.
  872.      *
  873.      * @param string                                                               $query  SQL query
  874.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  875.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  876.      *
  877.      * @return array<mixed,array<string,mixed>>
  878.      *
  879.      * @throws Exception
  880.      */
  881.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  882.     {
  883.         return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  884.     }
  886.     /**
  887.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  888.      *
  889.      * @param string                                                               $query  SQL query
  890.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  891.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  892.      *
  893.      * @return list<mixed>
  894.      *
  895.      * @throws Exception
  896.      */
  897.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  898.     {
  899.         return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  900.     }
  902.     /**
  903.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  904.      *
  905.      * @param string                                                               $query  SQL query
  906.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  907.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  908.      *
  909.      * @return Traversable<int,list<mixed>>
  910.      *
  911.      * @throws Exception
  912.      */
  913.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  914.     {
  915.         return $this->executeQuery($query, $params, $types)->iterateNumeric();
  916.     }
  918.     /**
  919.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  920.      * as associative arrays.
  921.      *
  922.      * @param string                                                               $query  SQL query
  923.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  924.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  925.      *
  926.      * @return Traversable<int,array<string,mixed>>
  927.      *
  928.      * @throws Exception
  929.      */
  930.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  931.     {
  932.         return $this->executeQuery($query, $params, $types)->iterateAssociative();
  933.     }
  935.     /**
  936.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  937.      * mapped to the first column and the values mapped to the second column.
  938.      *
  939.      * @param string                                                               $query  SQL query
  940.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  941.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  942.      *
  943.      * @return Traversable<mixed,mixed>
  944.      *
  945.      * @throws Exception
  946.      */
  947.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  948.     {
  949.         return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  950.     }
  952.     /**
  953.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  954.      * to the first column and the values being an associative array representing the rest of the columns
  955.      * and their values.
  956.      *
  957.      * @param string                                           $query  SQL query
  958.      * @param list<mixed>|array<string, mixed>                 $params Query parameters
  959.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  960.      *
  961.      * @return Traversable<mixed,array<string,mixed>>
  962.      *
  963.      * @throws Exception
  964.      */
  965.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  966.     {
  967.         return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  968.     }
  970.     /**
  971.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  972.      *
  973.      * @param string                                                               $query  SQL query
  974.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  975.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  976.      *
  977.      * @return Traversable<int,mixed>
  978.      *
  979.      * @throws Exception
  980.      */
  981.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  982.     {
  983.         return $this->executeQuery($query, $params, $types)->iterateColumn();
  984.     }
  986.     /**
  987.      * Prepares an SQL statement.
  988.      *
  989.      * @param string $sql The SQL statement to prepare.
  990.      *
  991.      * @throws Exception
  992.      */
  993.     public function prepare(string $sql): Statement
  994.     {
  995.         $connection = $this->getWrappedConnection();
  997.         try {
  998.             $statement = $connection->prepare($sql);
  999.         } catch (Driver\Exception $e) {
  1000.             throw $this->convertExceptionDuringQuery($e, $sql);
  1001.         }
  1003.         return new Statement($this, $statement, $sql);
  1004.     }
  1006.     /**
  1007.      * Executes an, optionally parametrized, SQL query.
  1008.      *
  1009.      * If the query is parametrized, a prepared statement is used.
  1010.      * If an SQLLogger is configured, the execution is logged.
  1011.      *
  1012.      * @param string                                                               $sql    SQL query
  1013.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1014.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1015.      *
  1016.      * @throws Exception
  1017.      */
  1018.     public function executeQuery(
  1019.         string $sql,
  1020.         array $params = [],
  1021.         $types = [],
  1022.         ?QueryCacheProfile $qcp = null
  1023.     ): Result {
  1024.         if ($qcp !== null) {
  1025.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1026.         }
  1028.         $connection = $this->getWrappedConnection();
  1030.         $logger = $this->_config->getSQLLogger();
  1031.         if ($logger !== null) {
  1032.             $logger->startQuery($sql, $params, $types);
  1033.         }
  1035.         try {
  1036.             if (count($params) > 0) {
  1037.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1038.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1039.                 }
  1041.                 $stmt = $connection->prepare($sql);
  1042.                 if (count($types) > 0) {
  1043.                     $this->_bindTypedValues($stmt, $params, $types);
  1044.                     $result = $stmt->execute();
  1045.                 } else {
  1046.                     $result = $stmt->execute($params);
  1047.                 }
  1048.             } else {
  1049.                 $result = $connection->query($sql);
  1050.             }
  1052.             return new Result($result, $this);
  1053.         } catch (Driver\Exception $e) {
  1054.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1055.         } finally {
  1056.             if ($logger !== null) {
  1057.                 $logger->stopQuery();
  1058.             }
  1059.         }
  1060.     }
  1062.     /**
  1063.      * Executes a caching query.
  1064.      *
  1065.      * @param string                                                               $sql    SQL query
  1066.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1067.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1068.      *
  1069.      * @throws CacheException
  1070.      * @throws Exception
  1071.      */
  1072.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1073.     {
  1074.         $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1076.         if ($resultCache === null) {
  1077.             throw CacheException::noResultDriverConfigured();
  1078.         }
  1080.         $connectionParams = $this->params;
  1081.         unset($connectionParams['platform']);
  1083.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1085.         $item = $resultCache->getItem($cacheKey);
  1087.         if ($item->isHit()) {
  1088.             $value = $item->get();
  1089.             if (isset($value[$realKey])) {
  1090.                 return new Result(new ArrayResult($value[$realKey]), $this);
  1091.             }
  1092.         } else {
  1093.             $value = [];
  1094.         }
  1096.         $data = $this->fetchAllAssociative($sql, $params, $types);
  1098.         $value[$realKey] = $data;
  1100.         $item->set($value);
  1102.         $lifetime = $qcp->getLifetime();
  1103.         if ($lifetime > 0) {
  1104.             $item->expiresAfter($lifetime);
  1105.         }
  1107.         $resultCache->save($item);
  1109.         return new Result(new ArrayResult($data), $this);
  1110.     }
  1112.     /**
  1113.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1114.      *
  1115.      * Could be used for:
  1116.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1117.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1118.      *  - DCL statements: GRANT, REVOKE, etc.
  1119.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1120.      *  - Other statements that don't yield a row set.
  1121.      *
  1122.      * This method supports PDO binding types as well as DBAL mapping types.
  1123.      *
  1124.      * @param string                                                               $sql    SQL statement
  1125.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1126.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1127.      *
  1128.      * @return int|string The number of affected rows.
  1129.      *
  1130.      * @throws Exception
  1131.      */
  1132.     public function executeStatement($sql, array $params = [], array $types = [])
  1133.     {
  1134.         $connection = $this->getWrappedConnection();
  1136.         $logger = $this->_config->getSQLLogger();
  1137.         if ($logger !== null) {
  1138.             $logger->startQuery($sql, $params, $types);
  1139.         }
  1141.         try {
  1142.             if (count($params) > 0) {
  1143.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1144.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1145.                 }
  1147.                 $stmt = $connection->prepare($sql);
  1149.                 if (count($types) > 0) {
  1150.                     $this->_bindTypedValues($stmt, $params, $types);
  1152.                     $result = $stmt->execute();
  1153.                 } else {
  1154.                     $result = $stmt->execute($params);
  1155.                 }
  1157.                 return $result->rowCount();
  1158.             }
  1160.             return $connection->exec($sql);
  1161.         } catch (Driver\Exception $e) {
  1162.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1163.         } finally {
  1164.             if ($logger !== null) {
  1165.                 $logger->stopQuery();
  1166.             }
  1167.         }
  1168.     }
  1170.     /**
  1171.      * Returns the current transaction nesting level.
  1172.      *
  1173.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1174.      */
  1175.     public function getTransactionNestingLevel()
  1176.     {
  1177.         return $this->transactionNestingLevel;
  1178.     }
  1180.     /**
  1181.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1182.      * depending on the underlying driver.
  1183.      *
  1184.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1185.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1186.      * columns or sequences.
  1187.      *
  1188.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1189.      *
  1190.      * @return string|int|false A string representation of the last inserted ID.
  1191.      *
  1192.      * @throws Exception
  1193.      */
  1194.     public function lastInsertId($name = null)
  1195.     {
  1196.         if ($name !== null) {
  1197.             Deprecation::trigger(
  1198.                 'doctrine/dbal',
  1199.                 'https://github.com/doctrine/dbal/issues/4687',
  1200.                 'The usage of Connection::lastInsertId() with a sequence name is deprecated.'
  1201.             );
  1202.         }
  1204.         try {
  1205.             return $this->getWrappedConnection()->lastInsertId($name);
  1206.         } catch (Driver\Exception $e) {
  1207.             throw $this->convertException($e);
  1208.         }
  1209.     }
  1211.     /**
  1212.      * Executes a function in a transaction.
  1213.      *
  1214.      * The function gets passed this Connection instance as an (optional) parameter.
  1215.      *
  1216.      * If an exception occurs during execution of the function or transaction commit,
  1217.      * the transaction is rolled back and the exception re-thrown.
  1218.      *
  1219.      * @param Closure $func The function to execute transactionally.
  1220.      *
  1221.      * @return mixed The value returned by $func
  1222.      *
  1223.      * @throws Throwable
  1224.      */
  1225.     public function transactional(Closure $func)
  1226.     {
  1227.         $this->beginTransaction();
  1228.         try {
  1229.             $res = $func($this);
  1230.             $this->commit();
  1232.             return $res;
  1233.         } catch (Throwable $e) {
  1234.             $this->rollBack();
  1236.             throw $e;
  1237.         }
  1238.     }
  1240.     /**
  1241.      * Sets if nested transactions should use savepoints.
  1242.      *
  1243.      * @param bool $nestTransactionsWithSavepoints
  1244.      *
  1245.      * @return void
  1246.      *
  1247.      * @throws Exception
  1248.      */
  1249.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1250.     {
  1251.         if ($this->transactionNestingLevel > 0) {
  1252.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1253.         }
  1255.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1256.             throw ConnectionException::savepointsNotSupported();
  1257.         }
  1259.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1260.     }
  1262.     /**
  1263.      * Gets if nested transactions should use savepoints.
  1264.      *
  1265.      * @return bool
  1266.      */
  1267.     public function getNestTransactionsWithSavepoints()
  1268.     {
  1269.         return $this->nestTransactionsWithSavepoints;
  1270.     }
  1272.     /**
  1273.      * Returns the savepoint name to use for nested transactions.
  1274.      *
  1275.      * @return string
  1276.      */
  1277.     protected function _getNestedTransactionSavePointName()
  1278.     {
  1279.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1280.     }
  1282.     /**
  1283.      * @return bool
  1284.      *
  1285.      * @throws Exception
  1286.      */
  1287.     public function beginTransaction()
  1288.     {
  1289.         $connection = $this->getWrappedConnection();
  1291.         ++$this->transactionNestingLevel;
  1293.         $logger = $this->_config->getSQLLogger();
  1295.         if ($this->transactionNestingLevel === 1) {
  1296.             if ($logger !== null) {
  1297.                 $logger->startQuery('"START TRANSACTION"');
  1298.             }
  1300.             $connection->beginTransaction();
  1302.             if ($logger !== null) {
  1303.                 $logger->stopQuery();
  1304.             }
  1305.         } elseif ($this->nestTransactionsWithSavepoints) {
  1306.             if ($logger !== null) {
  1307.                 $logger->startQuery('"SAVEPOINT"');
  1308.             }
  1310.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1311.             if ($logger !== null) {
  1312.                 $logger->stopQuery();
  1313.             }
  1314.         }
  1316.         $this->getEventManager()->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1318.         return true;
  1319.     }
  1321.     /**
  1322.      * @return bool
  1323.      *
  1324.      * @throws Exception
  1325.      */
  1326.     public function commit()
  1327.     {
  1328.         if ($this->transactionNestingLevel === 0) {
  1329.             throw ConnectionException::noActiveTransaction();
  1330.         }
  1332.         if ($this->isRollbackOnly) {
  1333.             throw ConnectionException::commitFailedRollbackOnly();
  1334.         }
  1336.         $result = true;
  1338.         $connection = $this->getWrappedConnection();
  1340.         $logger = $this->_config->getSQLLogger();
  1342.         if ($this->transactionNestingLevel === 1) {
  1343.             if ($logger !== null) {
  1344.                 $logger->startQuery('"COMMIT"');
  1345.             }
  1347.             $result = $connection->commit();
  1349.             if ($logger !== null) {
  1350.                 $logger->stopQuery();
  1351.             }
  1352.         } elseif ($this->nestTransactionsWithSavepoints) {
  1353.             if ($logger !== null) {
  1354.                 $logger->startQuery('"RELEASE SAVEPOINT"');
  1355.             }
  1357.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1358.             if ($logger !== null) {
  1359.                 $logger->stopQuery();
  1360.             }
  1361.         }
  1363.         --$this->transactionNestingLevel;
  1365.         $this->getEventManager()->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  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.         $this->getEventManager()->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1445.         return true;
  1446.     }
  1448.     /**
  1449.      * Creates a new savepoint.
  1450.      *
  1451.      * @param string $savepoint The name of the savepoint to create.
  1452.      *
  1453.      * @return void
  1454.      *
  1455.      * @throws Exception
  1456.      */
  1457.     public function createSavepoint($savepoint)
  1458.     {
  1459.         $platform = $this->getDatabasePlatform();
  1461.         if (! $platform->supportsSavepoints()) {
  1462.             throw ConnectionException::savepointsNotSupported();
  1463.         }
  1465.         $this->executeStatement($platform->createSavePoint($savepoint));
  1466.     }
  1468.     /**
  1469.      * Releases the given savepoint.
  1470.      *
  1471.      * @param string $savepoint The name of the savepoint to release.
  1472.      *
  1473.      * @return void
  1474.      *
  1475.      * @throws Exception
  1476.      */
  1477.     public function releaseSavepoint($savepoint)
  1478.     {
  1479.         $platform = $this->getDatabasePlatform();
  1481.         if (! $platform->supportsSavepoints()) {
  1482.             throw ConnectionException::savepointsNotSupported();
  1483.         }
  1485.         if (! $platform->supportsReleaseSavepoints()) {
  1486.             return;
  1487.         }
  1489.         $this->executeStatement($platform->releaseSavePoint($savepoint));
  1490.     }
  1492.     /**
  1493.      * Rolls back to the given savepoint.
  1494.      *
  1495.      * @param string $savepoint The name of the savepoint to rollback to.
  1496.      *
  1497.      * @return void
  1498.      *
  1499.      * @throws Exception
  1500.      */
  1501.     public function rollbackSavepoint($savepoint)
  1502.     {
  1503.         $platform = $this->getDatabasePlatform();
  1505.         if (! $platform->supportsSavepoints()) {
  1506.             throw ConnectionException::savepointsNotSupported();
  1507.         }
  1509.         $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1510.     }
  1512.     /**
  1513.      * Gets the wrapped driver connection.
  1514.      *
  1515.      * @deprecated Use {@link getNativeConnection()} to access the native connection.
  1516.      *
  1517.      * @return DriverConnection
  1518.      *
  1519.      * @throws Exception
  1520.      */
  1521.     public function getWrappedConnection()
  1522.     {
  1523.         Deprecation::triggerIfCalledFromOutside(
  1524.             'doctrine/dbal',
  1525.             'https://github.com/doctrine/dbal/issues/4966',
  1526.             'Connection::getWrappedConnection() is deprecated.'
  1527.                 . ' Use Connection::getNativeConnection() to access the native connection.'
  1528.         );
  1530.         $this->connect();
  1532.         assert($this->_conn !== null);
  1534.         return $this->_conn;
  1535.     }
  1537.     /**
  1538.      * @return resource|object
  1539.      */
  1540.     public function getNativeConnection()
  1541.     {
  1542.         $this->connect();
  1544.         assert($this->_conn !== null);
  1545.         if (! method_exists($this->_conn, 'getNativeConnection')) {
  1546.             throw new LogicException(sprintf(
  1547.                 'The driver connection %s does not support accessing the native connection.',
  1548.                 get_class($this->_conn)
  1549.             ));
  1550.         }
  1552.         return $this->_conn->getNativeConnection();
  1553.     }
  1555.     /**
  1556.      * Creates a SchemaManager that can be used to inspect or change the
  1557.      * database schema through the connection.
  1558.      *
  1559.      * @throws Exception
  1560.      */
  1561.     public function createSchemaManager(): AbstractSchemaManager
  1562.     {
  1563.         return $this->_driver->getSchemaManager(
  1564.             $this,
  1565.             $this->getDatabasePlatform()
  1566.         );
  1567.     }
  1569.     /**
  1570.      * Gets the SchemaManager that can be used to inspect or change the
  1571.      * database schema through the connection.
  1572.      *
  1573.      * @deprecated Use {@see createSchemaManager()} instead.
  1574.      *
  1575.      * @return AbstractSchemaManager
  1576.      *
  1577.      * @throws Exception
  1578.      */
  1579.     public function getSchemaManager()
  1580.     {
  1581.         Deprecation::triggerIfCalledFromOutside(
  1582.             'doctrine/dbal',
  1583.             'https://github.com/doctrine/dbal/issues/4515',
  1584.             'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.'
  1585.         );
  1587.         if ($this->_schemaManager === null) {
  1588.             $this->_schemaManager = $this->createSchemaManager();
  1589.         }
  1591.         return $this->_schemaManager;
  1592.     }
  1594.     /**
  1595.      * Marks the current transaction so that the only possible
  1596.      * outcome for the transaction to be rolled back.
  1597.      *
  1598.      * @return void
  1599.      *
  1600.      * @throws ConnectionException If no transaction is active.
  1601.      */
  1602.     public function setRollbackOnly()
  1603.     {
  1604.         if ($this->transactionNestingLevel === 0) {
  1605.             throw ConnectionException::noActiveTransaction();
  1606.         }
  1608.         $this->isRollbackOnly = true;
  1609.     }
  1611.     /**
  1612.      * Checks whether the current transaction is marked for rollback only.
  1613.      *
  1614.      * @return bool
  1615.      *
  1616.      * @throws ConnectionException If no transaction is active.
  1617.      */
  1618.     public function isRollbackOnly()
  1619.     {
  1620.         if ($this->transactionNestingLevel === 0) {
  1621.             throw ConnectionException::noActiveTransaction();
  1622.         }
  1624.         return $this->isRollbackOnly;
  1625.     }
  1627.     /**
  1628.      * Converts a given value to its database representation according to the conversion
  1629.      * rules of a specific DBAL mapping type.
  1630.      *
  1631.      * @param mixed  $value The value to convert.
  1632.      * @param string $type  The name of the DBAL mapping type.
  1633.      *
  1634.      * @return mixed The converted value.
  1635.      *
  1636.      * @throws Exception
  1637.      */
  1638.     public function convertToDatabaseValue($value, $type)
  1639.     {
  1640.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1641.     }
  1643.     /**
  1644.      * Converts a given value to its PHP representation according to the conversion
  1645.      * rules of a specific DBAL mapping type.
  1646.      *
  1647.      * @param mixed  $value The value to convert.
  1648.      * @param string $type  The name of the DBAL mapping type.
  1649.      *
  1650.      * @return mixed The converted type.
  1651.      *
  1652.      * @throws Exception
  1653.      */
  1654.     public function convertToPHPValue($value, $type)
  1655.     {
  1656.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1657.     }
  1659.     /**
  1660.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1661.      * or DBAL mapping type, to a given statement.
  1662.      *
  1663.      * @param DriverStatement                                                      $stmt   Prepared statement
  1664.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1665.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1666.      *
  1667.      * @throws Exception
  1668.      */
  1669.     private function _bindTypedValues(DriverStatement $stmt, array $params, array $types): void
  1670.     {
  1671.         // Check whether parameters are positional or named. Mixing is not allowed.
  1672.         if (is_int(key($params))) {
  1673.             $bindIndex = 1;
  1675.             foreach ($params as $key => $value) {
  1676.                 if (isset($types[$key])) {
  1677.                     $type                  = $types[$key];
  1678.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1679.                     $stmt->bindValue($bindIndex, $value, $bindingType);
  1680.                 } else {
  1681.                     $stmt->bindValue($bindIndex, $value);
  1682.                 }
  1684.                 ++$bindIndex;
  1685.             }
  1686.         } else {
  1687.             // Named parameters
  1688.             foreach ($params as $name => $value) {
  1689.                 if (isset($types[$name])) {
  1690.                     $type                  = $types[$name];
  1691.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1692.                     $stmt->bindValue($name, $value, $bindingType);
  1693.                 } else {
  1694.                     $stmt->bindValue($name, $value);
  1695.                 }
  1696.             }
  1697.         }
  1698.     }
  1700.     /**
  1701.      * Gets the binding type of a given type.
  1702.      *
  1703.      * @param mixed                $value The value to bind.
  1704.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  1705.      *
  1706.      * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1707.      *
  1708.      * @throws Exception
  1709.      */
  1710.     private function getBindingInfo($value, $type): array
  1711.     {
  1712.         if (is_string($type)) {
  1713.             $type = Type::getType($type);
  1714.         }
  1716.         if ($type instanceof Type) {
  1717.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1718.             $bindingType = $type->getBindingType();
  1719.         } else {
  1720.             $bindingType = $type ?? ParameterType::STRING;
  1721.         }
  1723.         return [$value, $bindingType];
  1724.     }
  1726.     /**
  1727.      * Creates a new instance of a SQL query builder.
  1728.      *
  1729.      * @return QueryBuilder
  1730.      */
  1731.     public function createQueryBuilder()
  1732.     {
  1733.         return new Query\QueryBuilder($this);
  1734.     }
  1736.     /**
  1737.      * @internal
  1738.      *
  1739.      * @param list<mixed>|array<string, mixed>                                     $params
  1740.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1741.      */
  1742.     final public function convertExceptionDuringQuery(
  1743.         Driver\Exception $e,
  1744.         string $sql,
  1745.         array $params = [],
  1746.         array $types = []
  1747.     ): DriverException {
  1748.         return $this->handleDriverException($e, new Query($sql, $params, $types));
  1749.     }
  1751.     /**
  1752.      * @internal
  1753.      */
  1754.     final public function convertException(Driver\Exception $e): DriverException
  1755.     {
  1756.         return $this->handleDriverException($e, null);
  1757.     }
  1759.     /**
  1760.      * @param array<int, mixed>|array<string, mixed>                               $params
  1761.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1762.      *
  1763.      * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1764.      */
  1765.     private function expandArrayParameters(string $sql, array $params, array $types): array
  1766.     {
  1767.         if ($this->parser === null) {
  1768.             $this->parser = $this->getDatabasePlatform()->createSQLParser();
  1769.         }
  1771.         $visitor = new ExpandArrayParameters($params, $types);
  1773.         $this->parser->parse($sql, $visitor);
  1775.         return [
  1776.             $visitor->getSQL(),
  1777.             $visitor->getParameters(),
  1778.             $visitor->getTypes(),
  1779.         ];
  1780.     }
  1782.     /**
  1783.      * @param array<int, mixed>|array<string, mixed>                               $params
  1784.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1785.      */
  1786.     private function needsArrayParameterConversion(array $params, array $types): bool
  1787.     {
  1788.         if (is_string(key($params))) {
  1789.             return true;
  1790.         }
  1792.         foreach ($types as $type) {
  1793.             if (
  1794.                 $type === self::PARAM_INT_ARRAY
  1795.                 || $type === self::PARAM_STR_ARRAY
  1796.                 || $type === self::PARAM_ASCII_STR_ARRAY
  1797.             ) {
  1798.                 return true;
  1799.             }
  1800.         }
  1802.         return false;
  1803.     }
  1805.     private function handleDriverException(
  1806.         Driver\Exception $driverException,
  1807.         ?Query $query
  1808.     ): DriverException {
  1809.         if ($this->exceptionConverter === null) {
  1810.             $this->exceptionConverter = $this->_driver->getExceptionConverter();
  1811.         }
  1813.         $exception = $this->exceptionConverter->convert($driverException, $query);
  1815.         if ($exception instanceof ConnectionLost) {
  1816.             $this->close();
  1817.         }
  1819.         return $exception;
  1820.     }
  1822.     /**
  1823.      * BC layer for a wide-spread use-case of old DBAL APIs
  1824.      *
  1825.      * @deprecated This API is deprecated and will be removed after 2022
  1826.      *
  1827.      * @param array<mixed>           $params The query parameters
  1828.      * @param array<int|string|null> $types  The parameter types
  1829.      */
  1830.     public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1831.     {
  1832.         return $this->executeStatement($sql, $params, $types);
  1833.     }
  1835.     /**
  1836.      * BC layer for a wide-spread use-case of old DBAL APIs
  1837.      *
  1838.      * @deprecated This API is deprecated and will be removed after 2022
  1839.      */
  1840.     public function query(string $sql): Result
  1841.     {
  1842.         return $this->executeQuery($sql);
  1843.     }
  1845.     /**
  1846.      * BC layer for a wide-spread use-case of old DBAL APIs
  1847.      *
  1848.      * @deprecated This API is deprecated and will be removed after 2022
  1849.      */
  1850.     public function exec(string $sql): int
  1851.     {
  1852.         return $this->executeStatement($sql);
  1853.     }
  1854. }