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

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.         // Create default config and event manager if none given
  186.         if ($config === null) {
  187.             $config = new Configuration();
  188.         }
  190.         if ($eventManager === null) {
  191.             $eventManager = new EventManager();
  192.         }
  194.         $this->_config       = $config;
  195.         $this->_eventManager = $eventManager;
  197.         if (isset($params['platform'])) {
  198.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  199.                 throw Exception::invalidPlatformType($params['platform']);
  200.             }
  202.             $this->platform = $params['platform'];
  203.             $this->platform->setEventManager($this->_eventManager);
  204.         }
  206.         $this->_expr = $this->createExpressionBuilder();
  208.         $this->autoCommit = $config->getAutoCommit();
  209.     }
  211.     /**
  212.      * Gets the parameters used during instantiation.
  213.      *
  214.      * @internal
  215.      *
  216.      * @return array<string,mixed>
  217.      * @psalm-return Params
  218.      */
  219.     public function getParams()
  220.     {
  221.         return $this->params;
  222.     }
  224.     /**
  225.      * Gets the name of the currently selected database.
  226.      *
  227.      * @return string|null The name of the database or NULL if a database is not selected.
  228.      *                     The platforms which don't support the concept of a database (e.g. embedded databases)
  229.      *                     must always return a string as an indicator of an implicitly selected database.
  230.      *
  231.      * @throws Exception
  232.      */
  233.     public function getDatabase()
  234.     {
  235.         $platform = $this->getDatabasePlatform();
  236.         $query    = $platform->getDummySelectSQL($platform->getCurrentDatabaseExpression());
  237.         $database = $this->fetchOne($query);
  239.         assert(is_string($database) || $database === null);
  241.         return $database;
  242.     }
  244.     /**
  245.      * Gets the DBAL driver instance.
  246.      *
  247.      * @return Driver
  248.      */
  249.     public function getDriver()
  250.     {
  251.         return $this->_driver;
  252.     }
  254.     /**
  255.      * Gets the Configuration used by the Connection.
  256.      *
  257.      * @return Configuration
  258.      */
  259.     public function getConfiguration()
  260.     {
  261.         return $this->_config;
  262.     }
  264.     /**
  265.      * Gets the EventManager used by the Connection.
  266.      *
  267.      * @return EventManager
  268.      */
  269.     public function getEventManager()
  270.     {
  271.         return $this->_eventManager;
  272.     }
  274.     /**
  275.      * Gets the DatabasePlatform for the connection.
  276.      *
  277.      * @return AbstractPlatform
  278.      *
  279.      * @throws Exception
  280.      */
  281.     public function getDatabasePlatform()
  282.     {
  283.         if ($this->platform === null) {
  284.             $this->platform = $this->detectDatabasePlatform();
  285.             $this->platform->setEventManager($this->_eventManager);
  286.         }
  288.         return $this->platform;
  289.     }
  291.     /**
  292.      * Creates an expression builder for the connection.
  293.      */
  294.     public function createExpressionBuilder(): ExpressionBuilder
  295.     {
  296.         return new ExpressionBuilder($this);
  297.     }
  299.     /**
  300.      * Gets the ExpressionBuilder for the connection.
  301.      *
  302.      * @deprecated Use {@see createExpressionBuilder()} instead.
  303.      *
  304.      * @return ExpressionBuilder
  305.      */
  306.     public function getExpressionBuilder()
  307.     {
  308.         Deprecation::triggerIfCalledFromOutside(
  309.             'doctrine/dbal',
  310.             'https://github.com/doctrine/dbal/issues/4515',
  311.             'Connection::getExpressionBuilder() is deprecated,'
  312.                 . ' use Connection::createExpressionBuilder() instead.'
  313.         );
  315.         return $this->_expr;
  316.     }
  318.     /**
  319.      * Establishes the connection with the database.
  320.      *
  321.      * @internal This method will be made protected in DBAL 4.0.
  322.      *
  323.      * @return bool TRUE if the connection was successfully established, FALSE if
  324.      *              the connection is already open.
  325.      *
  326.      * @throws Exception
  327.      */
  328.     public function connect()
  329.     {
  330.         Deprecation::triggerIfCalledFromOutside(
  331.             'doctrine/dbal',
  332.             'https://github.com/doctrine/dbal/issues/4966',
  333.             'Public access to Connection::connect() is deprecated.'
  334.         );
  336.         if ($this->_conn !== null) {
  337.             return false;
  338.         }
  340.         try {
  341.             $this->_conn = $this->_driver->connect($this->params);
  342.         } catch (Driver\Exception $e) {
  343.             throw $this->convertException($e);
  344.         }
  346.         if ($this->autoCommit === false) {
  347.             $this->beginTransaction();
  348.         }
  350.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  351.             $eventArgs = new Event\ConnectionEventArgs($this);
  352.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  353.         }
  355.         return true;
  356.     }
  358.     /**
  359.      * Detects and sets the database platform.
  360.      *
  361.      * Evaluates custom platform class and version in order to set the correct platform.
  362.      *
  363.      * @throws Exception If an invalid platform was specified for this connection.
  364.      */
  365.     private function detectDatabasePlatform(): AbstractPlatform
  366.     {
  367.         $version = $this->getDatabasePlatformVersion();
  369.         if ($version !== null) {
  370.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  372.             return $this->_driver->createDatabasePlatformForVersion($version);
  373.         }
  375.         return $this->_driver->getDatabasePlatform();
  376.     }
  378.     /**
  379.      * Returns the version of the related platform if applicable.
  380.      *
  381.      * Returns null if either the driver is not capable to create version
  382.      * specific platform instances, no explicit server version was specified
  383.      * or the underlying driver connection cannot determine the platform
  384.      * version without having to query it (performance reasons).
  385.      *
  386.      * @return string|null
  387.      *
  388.      * @throws Throwable
  389.      */
  390.     private function getDatabasePlatformVersion()
  391.     {
  392.         // Driver does not support version specific platforms.
  393.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  394.             return null;
  395.         }
  397.         // Explicit platform version requested (supersedes auto-detection).
  398.         if (isset($this->params['serverVersion'])) {
  399.             return $this->params['serverVersion'];
  400.         }
  402.         // If not connected, we need to connect now to determine the platform version.
  403.         if ($this->_conn === null) {
  404.             try {
  405.                 $this->connect();
  406.             } catch (Exception $originalException) {
  407.                 if (! isset($this->params['dbname'])) {
  408.                     throw $originalException;
  409.                 }
  411.                 // The database to connect to might not yet exist.
  412.                 // Retry detection without database name connection parameter.
  413.                 $params = $this->params;
  415.                 unset($this->params['dbname']);
  417.                 try {
  418.                     $this->connect();
  419.                 } catch (Exception $fallbackException) {
  420.                     // Either the platform does not support database-less connections
  421.                     // or something else went wrong.
  422.                     throw $originalException;
  423.                 } finally {
  424.                     $this->params = $params;
  425.                 }
  427.                 $serverVersion = $this->getServerVersion();
  429.                 // Close "temporary" connection to allow connecting to the real database again.
  430.                 $this->close();
  432.                 return $serverVersion;
  433.             }
  434.         }
  436.         return $this->getServerVersion();
  437.     }
  439.     /**
  440.      * Returns the database server version if the underlying driver supports it.
  441.      *
  442.      * @return string|null
  443.      *
  444.      * @throws Exception
  445.      */
  446.     private function getServerVersion()
  447.     {
  448.         $connection = $this->getWrappedConnection();
  450.         // Automatic platform version detection.
  451.         if ($connection instanceof ServerInfoAwareConnection) {
  452.             try {
  453.                 return $connection->getServerVersion();
  454.             } catch (Driver\Exception $e) {
  455.                 throw $this->convertException($e);
  456.             }
  457.         }
  459.         Deprecation::trigger(
  460.             'doctrine/dbal',
  461.             'https://github.com/doctrine/dbal/pulls/4750',
  462.             'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
  463.             get_class($connection)
  464.         );
  466.         // Unable to detect platform version.
  467.         return null;
  468.     }
  470.     /**
  471.      * Returns the current auto-commit mode for this connection.
  472.      *
  473.      * @see    setAutoCommit
  474.      *
  475.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  476.      */
  477.     public function isAutoCommit()
  478.     {
  479.         return $this->autoCommit === true;
  480.     }
  482.     /**
  483.      * Sets auto-commit mode for this connection.
  484.      *
  485.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  486.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  487.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  488.      *
  489.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  490.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  491.      *
  492.      * @see   isAutoCommit
  493.      *
  494.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  495.      *
  496.      * @return void
  497.      */
  498.     public function setAutoCommit($autoCommit)
  499.     {
  500.         $autoCommit = (bool) $autoCommit;
  502.         // Mode not changed, no-op.
  503.         if ($autoCommit === $this->autoCommit) {
  504.             return;
  505.         }
  507.         $this->autoCommit = $autoCommit;
  509.         // Commit all currently active transactions if any when switching auto-commit mode.
  510.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  511.             return;
  512.         }
  514.         $this->commitAll();
  515.     }
  517.     /**
  518.      * Prepares and executes an SQL query and returns the first row of the result
  519.      * as an associative array.
  520.      *
  521.      * @param string                                                               $query  SQL query
  522.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  523.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  524.      *
  525.      * @return array<string, mixed>|false False is returned if no rows are found.
  526.      *
  527.      * @throws Exception
  528.      */
  529.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  530.     {
  531.         return $this->executeQuery($query, $params, $types)->fetchAssociative();
  532.     }
  534.     /**
  535.      * Prepares and executes an SQL query and returns the first row of the result
  536.      * as a numerically indexed array.
  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 list<mixed>|false False is returned if no rows are found.
  543.      *
  544.      * @throws Exception
  545.      */
  546.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  547.     {
  548.         return $this->executeQuery($query, $params, $types)->fetchNumeric();
  549.     }
  551.     /**
  552.      * Prepares and executes an SQL query and returns the value of a single column
  553.      * of the first row of the result.
  554.      *
  555.      * @param string                                                               $query  SQL query
  556.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  557.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  558.      *
  559.      * @return mixed|false False is returned if no rows are found.
  560.      *
  561.      * @throws Exception
  562.      */
  563.     public function fetchOne(string $query, array $params = [], array $types = [])
  564.     {
  565.         return $this->executeQuery($query, $params, $types)->fetchOne();
  566.     }
  568.     /**
  569.      * Whether an actual connection to the database is established.
  570.      *
  571.      * @return bool
  572.      */
  573.     public function isConnected()
  574.     {
  575.         return $this->_conn !== null;
  576.     }
  578.     /**
  579.      * Checks whether a transaction is currently active.
  580.      *
  581.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  582.      */
  583.     public function isTransactionActive()
  584.     {
  585.         return $this->transactionNestingLevel > 0;
  586.     }
  588.     /**
  589.      * Adds condition based on the criteria to the query components
  590.      *
  591.      * @param array<string,mixed> $criteria   Map of key columns to their values
  592.      * @param string[]            $columns    Column names
  593.      * @param mixed[]             $values     Column values
  594.      * @param string[]            $conditions Key conditions
  595.      *
  596.      * @throws Exception
  597.      */
  598.     private function addCriteriaCondition(
  599.         array $criteria,
  600.         array &$columns,
  601.         array &$values,
  602.         array &$conditions
  603.     ): void {
  604.         $platform = $this->getDatabasePlatform();
  606.         foreach ($criteria as $columnName => $value) {
  607.             if ($value === null) {
  608.                 $conditions[] = $platform->getIsNullExpression($columnName);
  609.                 continue;
  610.             }
  612.             $columns[]    = $columnName;
  613.             $values[]     = $value;
  614.             $conditions[] = $columnName . ' = ?';
  615.         }
  616.     }
  618.     /**
  619.      * Executes an SQL DELETE statement on a table.
  620.      *
  621.      * Table expression and columns are not escaped and are not safe for user-input.
  622.      *
  623.      * @param string                                                               $table    Table name
  624.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  625.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  626.      *
  627.      * @return int|string The number of affected rows.
  628.      *
  629.      * @throws Exception
  630.      */
  631.     public function delete($table, array $criteria, array $types = [])
  632.     {
  633.         if (count($criteria) === 0) {
  634.             throw InvalidArgumentException::fromEmptyCriteria();
  635.         }
  637.         $columns = $values = $conditions = [];
  639.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  641.         return $this->executeStatement(
  642.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  643.             $values,
  644.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  645.         );
  646.     }
  648.     /**
  649.      * Closes the connection.
  650.      *
  651.      * @return void
  652.      */
  653.     public function close()
  654.     {
  655.         $this->_conn                   = null;
  656.         $this->transactionNestingLevel = 0;
  657.     }
  659.     /**
  660.      * Sets the transaction isolation level.
  661.      *
  662.      * @param int $level The level to set.
  663.      *
  664.      * @return int|string
  665.      *
  666.      * @throws Exception
  667.      */
  668.     public function setTransactionIsolation($level)
  669.     {
  670.         $this->transactionIsolationLevel = $level;
  672.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  673.     }
  675.     /**
  676.      * Gets the currently active transaction isolation level.
  677.      *
  678.      * @return int The current transaction isolation level.
  679.      *
  680.      * @throws Exception
  681.      */
  682.     public function getTransactionIsolation()
  683.     {
  684.         if ($this->transactionIsolationLevel === null) {
  685.             $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  686.         }
  688.         return $this->transactionIsolationLevel;
  689.     }
  691.     /**
  692.      * Executes an SQL UPDATE statement on a table.
  693.      *
  694.      * Table expression and columns are not escaped and are not safe for user-input.
  695.      *
  696.      * @param string                                                               $table    Table name
  697.      * @param array<string, mixed>                                                 $data     Column-value pairs
  698.      * @param array<string, mixed>                                                 $criteria Update criteria
  699.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  700.      *
  701.      * @return int|string The number of affected rows.
  702.      *
  703.      * @throws Exception
  704.      */
  705.     public function update($table, array $data, array $criteria, array $types = [])
  706.     {
  707.         $columns = $values = $conditions = $set = [];
  709.         foreach ($data as $columnName => $value) {
  710.             $columns[] = $columnName;
  711.             $values[]  = $value;
  712.             $set[]     = $columnName . ' = ?';
  713.         }
  715.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  717.         if (is_string(key($types))) {
  718.             $types = $this->extractTypeValues($columns, $types);
  719.         }
  721.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  722.                 . ' WHERE ' . implode(' AND ', $conditions);
  724.         return $this->executeStatement($sql, $values, $types);
  725.     }
  727.     /**
  728.      * Inserts a table row with specified data.
  729.      *
  730.      * Table expression and columns are not escaped and are not safe for user-input.
  731.      *
  732.      * @param string                                                               $table Table name
  733.      * @param array<string, mixed>                                                 $data  Column-value pairs
  734.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  735.      *
  736.      * @return int|string The number of affected rows.
  737.      *
  738.      * @throws Exception
  739.      */
  740.     public function insert($table, array $data, array $types = [])
  741.     {
  742.         if (count($data) === 0) {
  743.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  744.         }
  746.         $columns = [];
  747.         $values  = [];
  748.         $set     = [];
  750.         foreach ($data as $columnName => $value) {
  751.             $columns[] = $columnName;
  752.             $values[]  = $value;
  753.             $set[]     = '?';
  754.         }
  756.         return $this->executeStatement(
  757.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  758.             ' VALUES (' . implode(', ', $set) . ')',
  759.             $values,
  760.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  761.         );
  762.     }
  764.     /**
  765.      * Extract ordered type list from an ordered column list and type map.
  766.      *
  767.      * @param array<int, string>                                                   $columnList
  768.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  769.      *
  770.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  771.      */
  772.     private function extractTypeValues(array $columnList, array $types): array
  773.     {
  774.         $typeValues = [];
  776.         foreach ($columnList as $columnName) {
  777.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  778.         }
  780.         return $typeValues;
  781.     }
  783.     /**
  784.      * Quotes a string so it can be safely used as a table or column name, even if
  785.      * it is a reserved name.
  786.      *
  787.      * Delimiting style depends on the underlying database platform that is being used.
  788.      *
  789.      * NOTE: Just because you CAN use quoted identifiers does not mean
  790.      * you SHOULD use them. In general, they end up causing way more
  791.      * problems than they solve.
  792.      *
  793.      * @param string $str The name to be quoted.
  794.      *
  795.      * @return string The quoted name.
  796.      */
  797.     public function quoteIdentifier($str)
  798.     {
  799.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  800.     }
  802.     /**
  803.      * The usage of this method is discouraged. Use prepared statements
  804.      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
  805.      *
  806.      * @param mixed                $value
  807.      * @param int|string|Type|null $type
  808.      *
  809.      * @return mixed
  810.      */
  811.     public function quote($value, $type = ParameterType::STRING)
  812.     {
  813.         $connection = $this->getWrappedConnection();
  815.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  817.         return $connection->quote($value, $bindingType);
  818.     }
  820.     /**
  821.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  822.      *
  823.      * @param string                                                               $query  SQL query
  824.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  825.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  826.      *
  827.      * @return list<list<mixed>>
  828.      *
  829.      * @throws Exception
  830.      */
  831.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  832.     {
  833.         return $this->executeQuery($query, $params, $types)->fetchAllNumeric();
  834.     }
  836.     /**
  837.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  838.      *
  839.      * @param string                                                               $query  SQL query
  840.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  841.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  842.      *
  843.      * @return list<array<string,mixed>>
  844.      *
  845.      * @throws Exception
  846.      */
  847.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  848.     {
  849.         return $this->executeQuery($query, $params, $types)->fetchAllAssociative();
  850.     }
  852.     /**
  853.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  854.      * mapped to the first column and the values mapped to the second column.
  855.      *
  856.      * @param string                                                               $query  SQL query
  857.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  858.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  859.      *
  860.      * @return array<mixed,mixed>
  861.      *
  862.      * @throws Exception
  863.      */
  864.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  865.     {
  866.         return $this->executeQuery($query, $params, $types)->fetchAllKeyValue();
  867.     }
  869.     /**
  870.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  871.      * to the first column and the values being an associative array representing the rest of the columns
  872.      * and their values.
  873.      *
  874.      * @param string                                                               $query  SQL query
  875.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  876.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  877.      *
  878.      * @return array<mixed,array<string,mixed>>
  879.      *
  880.      * @throws Exception
  881.      */
  882.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  883.     {
  884.         return $this->executeQuery($query, $params, $types)->fetchAllAssociativeIndexed();
  885.     }
  887.     /**
  888.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  889.      *
  890.      * @param string                                                               $query  SQL query
  891.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  892.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  893.      *
  894.      * @return list<mixed>
  895.      *
  896.      * @throws Exception
  897.      */
  898.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  899.     {
  900.         return $this->executeQuery($query, $params, $types)->fetchFirstColumn();
  901.     }
  903.     /**
  904.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  905.      *
  906.      * @param string                                                               $query  SQL query
  907.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  908.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  909.      *
  910.      * @return Traversable<int,list<mixed>>
  911.      *
  912.      * @throws Exception
  913.      */
  914.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  915.     {
  916.         return $this->executeQuery($query, $params, $types)->iterateNumeric();
  917.     }
  919.     /**
  920.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  921.      * as associative arrays.
  922.      *
  923.      * @param string                                                               $query  SQL query
  924.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  925.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  926.      *
  927.      * @return Traversable<int,array<string,mixed>>
  928.      *
  929.      * @throws Exception
  930.      */
  931.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  932.     {
  933.         return $this->executeQuery($query, $params, $types)->iterateAssociative();
  934.     }
  936.     /**
  937.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  938.      * mapped to the first column and the values mapped to the second column.
  939.      *
  940.      * @param string                                                               $query  SQL query
  941.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  942.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  943.      *
  944.      * @return Traversable<mixed,mixed>
  945.      *
  946.      * @throws Exception
  947.      */
  948.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  949.     {
  950.         return $this->executeQuery($query, $params, $types)->iterateKeyValue();
  951.     }
  953.     /**
  954.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  955.      * to the first column and the values being an associative array representing the rest of the columns
  956.      * and their values.
  957.      *
  958.      * @param string                                           $query  SQL query
  959.      * @param list<mixed>|array<string, mixed>                 $params Query parameters
  960.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  961.      *
  962.      * @return Traversable<mixed,array<string,mixed>>
  963.      *
  964.      * @throws Exception
  965.      */
  966.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  967.     {
  968.         return $this->executeQuery($query, $params, $types)->iterateAssociativeIndexed();
  969.     }
  971.     /**
  972.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  973.      *
  974.      * @param string                                                               $query  SQL query
  975.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  976.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  977.      *
  978.      * @return Traversable<int,mixed>
  979.      *
  980.      * @throws Exception
  981.      */
  982.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  983.     {
  984.         return $this->executeQuery($query, $params, $types)->iterateColumn();
  985.     }
  987.     /**
  988.      * Prepares an SQL statement.
  989.      *
  990.      * @param string $sql The SQL statement to prepare.
  991.      *
  992.      * @throws Exception
  993.      */
  994.     public function prepare(string $sql): Statement
  995.     {
  996.         $connection = $this->getWrappedConnection();
  998.         try {
  999.             $statement = $connection->prepare($sql);
  1000.         } catch (Driver\Exception $e) {
  1001.             throw $this->convertExceptionDuringQuery($e, $sql);
  1002.         }
  1004.         return new Statement($this, $statement, $sql);
  1005.     }
  1007.     /**
  1008.      * Executes an, optionally parametrized, SQL query.
  1009.      *
  1010.      * If the query is parametrized, a prepared statement is used.
  1011.      * If an SQLLogger is configured, the execution is logged.
  1012.      *
  1013.      * @param string                                                               $sql    SQL query
  1014.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1015.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1016.      *
  1017.      * @throws Exception
  1018.      */
  1019.     public function executeQuery(
  1020.         string $sql,
  1021.         array $params = [],
  1022.         $types = [],
  1023.         ?QueryCacheProfile $qcp = null
  1024.     ): Result {
  1025.         if ($qcp !== null) {
  1026.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1027.         }
  1029.         $connection = $this->getWrappedConnection();
  1031.         $logger = $this->_config->getSQLLogger();
  1032.         if ($logger !== null) {
  1033.             $logger->startQuery($sql, $params, $types);
  1034.         }
  1036.         try {
  1037.             if (count($params) > 0) {
  1038.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1039.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1040.                 }
  1042.                 $stmt = $connection->prepare($sql);
  1043.                 if (count($types) > 0) {
  1044.                     $this->_bindTypedValues($stmt, $params, $types);
  1045.                     $result = $stmt->execute();
  1046.                 } else {
  1047.                     $result = $stmt->execute($params);
  1048.                 }
  1049.             } else {
  1050.                 $result = $connection->query($sql);
  1051.             }
  1053.             return new Result($result, $this);
  1054.         } catch (Driver\Exception $e) {
  1055.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1056.         } finally {
  1057.             if ($logger !== null) {
  1058.                 $logger->stopQuery();
  1059.             }
  1060.         }
  1061.     }
  1063.     /**
  1064.      * Executes a caching query.
  1065.      *
  1066.      * @param string                                                               $sql    SQL query
  1067.      * @param list<mixed>|array<string, mixed>                                     $params Query parameters
  1068.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1069.      *
  1070.      * @throws CacheException
  1071.      * @throws Exception
  1072.      */
  1073.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp): Result
  1074.     {
  1075.         $resultCache = $qcp->getResultCache() ?? $this->_config->getResultCache();
  1077.         if ($resultCache === null) {
  1078.             throw CacheException::noResultDriverConfigured();
  1079.         }
  1081.         $connectionParams = $this->params;
  1082.         unset($connectionParams['platform']);
  1084.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1086.         $item = $resultCache->getItem($cacheKey);
  1088.         if ($item->isHit()) {
  1089.             $value = $item->get();
  1090.             if (isset($value[$realKey])) {
  1091.                 return new Result(new ArrayResult($value[$realKey]), $this);
  1092.             }
  1093.         } else {
  1094.             $value = [];
  1095.         }
  1097.         $data = $this->fetchAllAssociative($sql, $params, $types);
  1099.         $value[$realKey] = $data;
  1101.         $item->set($value);
  1103.         $lifetime = $qcp->getLifetime();
  1104.         if ($lifetime > 0) {
  1105.             $item->expiresAfter($lifetime);
  1106.         }
  1108.         $resultCache->save($item);
  1110.         return new Result(new ArrayResult($data), $this);
  1111.     }
  1113.     /**
  1114.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1115.      *
  1116.      * Could be used for:
  1117.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1118.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1119.      *  - DCL statements: GRANT, REVOKE, etc.
  1120.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1121.      *  - Other statements that don't yield a row set.
  1122.      *
  1123.      * This method supports PDO binding types as well as DBAL mapping types.
  1124.      *
  1125.      * @param string                                                               $sql    SQL statement
  1126.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1127.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1128.      *
  1129.      * @return int|string The number of affected rows.
  1130.      *
  1131.      * @throws Exception
  1132.      */
  1133.     public function executeStatement($sql, array $params = [], array $types = [])
  1134.     {
  1135.         $connection = $this->getWrappedConnection();
  1137.         $logger = $this->_config->getSQLLogger();
  1138.         if ($logger !== null) {
  1139.             $logger->startQuery($sql, $params, $types);
  1140.         }
  1142.         try {
  1143.             if (count($params) > 0) {
  1144.                 if ($this->needsArrayParameterConversion($params, $types)) {
  1145.                     [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
  1146.                 }
  1148.                 $stmt = $connection->prepare($sql);
  1150.                 if (count($types) > 0) {
  1151.                     $this->_bindTypedValues($stmt, $params, $types);
  1153.                     $result = $stmt->execute();
  1154.                 } else {
  1155.                     $result = $stmt->execute($params);
  1156.                 }
  1158.                 return $result->rowCount();
  1159.             }
  1161.             return $connection->exec($sql);
  1162.         } catch (Driver\Exception $e) {
  1163.             throw $this->convertExceptionDuringQuery($e, $sql, $params, $types);
  1164.         } finally {
  1165.             if ($logger !== null) {
  1166.                 $logger->stopQuery();
  1167.             }
  1168.         }
  1169.     }
  1171.     /**
  1172.      * Returns the current transaction nesting level.
  1173.      *
  1174.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1175.      */
  1176.     public function getTransactionNestingLevel()
  1177.     {
  1178.         return $this->transactionNestingLevel;
  1179.     }
  1181.     /**
  1182.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1183.      * depending on the underlying driver.
  1184.      *
  1185.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1186.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1187.      * columns or sequences.
  1188.      *
  1189.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1190.      *
  1191.      * @return string|int|false A string representation of the last inserted ID.
  1192.      *
  1193.      * @throws Exception
  1194.      */
  1195.     public function lastInsertId($name = null)
  1196.     {
  1197.         if ($name !== null) {
  1198.             Deprecation::trigger(
  1199.                 'doctrine/dbal',
  1200.                 'https://github.com/doctrine/dbal/issues/4687',
  1201.                 'The usage of Connection::lastInsertId() with a sequence name is deprecated.'
  1202.             );
  1203.         }
  1205.         try {
  1206.             return $this->getWrappedConnection()->lastInsertId($name);
  1207.         } catch (Driver\Exception $e) {
  1208.             throw $this->convertException($e);
  1209.         }
  1210.     }
  1212.     /**
  1213.      * Executes a function in a transaction.
  1214.      *
  1215.      * The function gets passed this Connection instance as an (optional) parameter.
  1216.      *
  1217.      * If an exception occurs during execution of the function or transaction commit,
  1218.      * the transaction is rolled back and the exception re-thrown.
  1219.      *
  1220.      * @param Closure $func The function to execute transactionally.
  1221.      *
  1222.      * @return mixed The value returned by $func
  1223.      *
  1224.      * @throws Throwable
  1225.      */
  1226.     public function transactional(Closure $func)
  1227.     {
  1228.         $this->beginTransaction();
  1229.         try {
  1230.             $res = $func($this);
  1231.             $this->commit();
  1233.             return $res;
  1234.         } catch (Throwable $e) {
  1235.             $this->rollBack();
  1237.             throw $e;
  1238.         }
  1239.     }
  1241.     /**
  1242.      * Sets if nested transactions should use savepoints.
  1243.      *
  1244.      * @param bool $nestTransactionsWithSavepoints
  1245.      *
  1246.      * @return void
  1247.      *
  1248.      * @throws Exception
  1249.      */
  1250.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1251.     {
  1252.         if ($this->transactionNestingLevel > 0) {
  1253.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1254.         }
  1256.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1257.             throw ConnectionException::savepointsNotSupported();
  1258.         }
  1260.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1261.     }
  1263.     /**
  1264.      * Gets if nested transactions should use savepoints.
  1265.      *
  1266.      * @return bool
  1267.      */
  1268.     public function getNestTransactionsWithSavepoints()
  1269.     {
  1270.         return $this->nestTransactionsWithSavepoints;
  1271.     }
  1273.     /**
  1274.      * Returns the savepoint name to use for nested transactions.
  1275.      *
  1276.      * @return string
  1277.      */
  1278.     protected function _getNestedTransactionSavePointName()
  1279.     {
  1280.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1281.     }
  1283.     /**
  1284.      * @return bool
  1285.      *
  1286.      * @throws Exception
  1287.      */
  1288.     public function beginTransaction()
  1289.     {
  1290.         $connection = $this->getWrappedConnection();
  1292.         ++$this->transactionNestingLevel;
  1294.         $logger = $this->_config->getSQLLogger();
  1296.         if ($this->transactionNestingLevel === 1) {
  1297.             if ($logger !== null) {
  1298.                 $logger->startQuery('"START TRANSACTION"');
  1299.             }
  1301.             $connection->beginTransaction();
  1303.             if ($logger !== null) {
  1304.                 $logger->stopQuery();
  1305.             }
  1306.         } elseif ($this->nestTransactionsWithSavepoints) {
  1307.             if ($logger !== null) {
  1308.                 $logger->startQuery('"SAVEPOINT"');
  1309.             }
  1311.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1312.             if ($logger !== null) {
  1313.                 $logger->stopQuery();
  1314.             }
  1315.         }
  1317.         $this->getEventManager()->dispatchEvent(Events::onTransactionBegin, new TransactionBeginEventArgs($this));
  1319.         return true;
  1320.     }
  1322.     /**
  1323.      * @return bool
  1324.      *
  1325.      * @throws Exception
  1326.      */
  1327.     public function commit()
  1328.     {
  1329.         if ($this->transactionNestingLevel === 0) {
  1330.             throw ConnectionException::noActiveTransaction();
  1331.         }
  1333.         if ($this->isRollbackOnly) {
  1334.             throw ConnectionException::commitFailedRollbackOnly();
  1335.         }
  1337.         $result = true;
  1339.         $connection = $this->getWrappedConnection();
  1341.         $logger = $this->_config->getSQLLogger();
  1343.         if ($this->transactionNestingLevel === 1) {
  1344.             if ($logger !== null) {
  1345.                 $logger->startQuery('"COMMIT"');
  1346.             }
  1348.             $result = $connection->commit();
  1350.             if ($logger !== null) {
  1351.                 $logger->stopQuery();
  1352.             }
  1353.         } elseif ($this->nestTransactionsWithSavepoints) {
  1354.             if ($logger !== null) {
  1355.                 $logger->startQuery('"RELEASE SAVEPOINT"');
  1356.             }
  1358.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1359.             if ($logger !== null) {
  1360.                 $logger->stopQuery();
  1361.             }
  1362.         }
  1364.         --$this->transactionNestingLevel;
  1366.         $this->getEventManager()->dispatchEvent(Events::onTransactionCommit, new TransactionCommitEventArgs($this));
  1368.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1369.             return $result;
  1370.         }
  1372.         $this->beginTransaction();
  1374.         return $result;
  1375.     }
  1377.     /**
  1378.      * Commits all current nesting transactions.
  1379.      *
  1380.      * @throws Exception
  1381.      */
  1382.     private function commitAll(): void
  1383.     {
  1384.         while ($this->transactionNestingLevel !== 0) {
  1385.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1386.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1387.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1388.                 $this->commit();
  1390.                 return;
  1391.             }
  1393.             $this->commit();
  1394.         }
  1395.     }
  1397.     /**
  1398.      * Cancels any database changes done during the current transaction.
  1399.      *
  1400.      * @return bool
  1401.      *
  1402.      * @throws Exception
  1403.      */
  1404.     public function rollBack()
  1405.     {
  1406.         if ($this->transactionNestingLevel === 0) {
  1407.             throw ConnectionException::noActiveTransaction();
  1408.         }
  1410.         $connection = $this->getWrappedConnection();
  1412.         $logger = $this->_config->getSQLLogger();
  1414.         if ($this->transactionNestingLevel === 1) {
  1415.             if ($logger !== null) {
  1416.                 $logger->startQuery('"ROLLBACK"');
  1417.             }
  1419.             $this->transactionNestingLevel = 0;
  1420.             $connection->rollBack();
  1421.             $this->isRollbackOnly = false;
  1422.             if ($logger !== null) {
  1423.                 $logger->stopQuery();
  1424.             }
  1426.             if ($this->autoCommit === false) {
  1427.                 $this->beginTransaction();
  1428.             }
  1429.         } elseif ($this->nestTransactionsWithSavepoints) {
  1430.             if ($logger !== null) {
  1431.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1432.             }
  1434.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1435.             --$this->transactionNestingLevel;
  1436.             if ($logger !== null) {
  1437.                 $logger->stopQuery();
  1438.             }
  1439.         } else {
  1440.             $this->isRollbackOnly = true;
  1441.             --$this->transactionNestingLevel;
  1442.         }
  1444.         $this->getEventManager()->dispatchEvent(Events::onTransactionRollBack, new TransactionRollBackEventArgs($this));
  1446.         return true;
  1447.     }
  1449.     /**
  1450.      * Creates a new savepoint.
  1451.      *
  1452.      * @param string $savepoint The name of the savepoint to create.
  1453.      *
  1454.      * @return void
  1455.      *
  1456.      * @throws Exception
  1457.      */
  1458.     public function createSavepoint($savepoint)
  1459.     {
  1460.         $platform = $this->getDatabasePlatform();
  1462.         if (! $platform->supportsSavepoints()) {
  1463.             throw ConnectionException::savepointsNotSupported();
  1464.         }
  1466.         $this->executeStatement($platform->createSavePoint($savepoint));
  1467.     }
  1469.     /**
  1470.      * Releases the given savepoint.
  1471.      *
  1472.      * @param string $savepoint The name of the savepoint to release.
  1473.      *
  1474.      * @return void
  1475.      *
  1476.      * @throws Exception
  1477.      */
  1478.     public function releaseSavepoint($savepoint)
  1479.     {
  1480.         $platform = $this->getDatabasePlatform();
  1482.         if (! $platform->supportsSavepoints()) {
  1483.             throw ConnectionException::savepointsNotSupported();
  1484.         }
  1486.         if (! $platform->supportsReleaseSavepoints()) {
  1487.             return;
  1488.         }
  1490.         $this->executeStatement($platform->releaseSavePoint($savepoint));
  1491.     }
  1493.     /**
  1494.      * Rolls back to the given savepoint.
  1495.      *
  1496.      * @param string $savepoint The name of the savepoint to rollback to.
  1497.      *
  1498.      * @return void
  1499.      *
  1500.      * @throws Exception
  1501.      */
  1502.     public function rollbackSavepoint($savepoint)
  1503.     {
  1504.         $platform = $this->getDatabasePlatform();
  1506.         if (! $platform->supportsSavepoints()) {
  1507.             throw ConnectionException::savepointsNotSupported();
  1508.         }
  1510.         $this->executeStatement($platform->rollbackSavePoint($savepoint));
  1511.     }
  1513.     /**
  1514.      * Gets the wrapped driver connection.
  1515.      *
  1516.      * @deprecated Use {@link getNativeConnection()} to access the native connection.
  1517.      *
  1518.      * @return DriverConnection
  1519.      *
  1520.      * @throws Exception
  1521.      */
  1522.     public function getWrappedConnection()
  1523.     {
  1524.         Deprecation::triggerIfCalledFromOutside(
  1525.             'doctrine/dbal',
  1526.             'https://github.com/doctrine/dbal/issues/4966',
  1527.             'Connection::getWrappedConnection() is deprecated.'
  1528.                 . ' Use Connection::getNativeConnection() to access the native connection.'
  1529.         );
  1531.         $this->connect();
  1533.         assert($this->_conn !== null);
  1535.         return $this->_conn;
  1536.     }
  1538.     /**
  1539.      * @return resource|object
  1540.      */
  1541.     public function getNativeConnection()
  1542.     {
  1543.         $this->connect();
  1545.         assert($this->_conn !== null);
  1546.         if (! method_exists($this->_conn, 'getNativeConnection')) {
  1547.             throw new LogicException(sprintf(
  1548.                 'The driver connection %s does not support accessing the native connection.',
  1549.                 get_class($this->_conn)
  1550.             ));
  1551.         }
  1553.         return $this->_conn->getNativeConnection();
  1554.     }
  1556.     /**
  1557.      * Creates a SchemaManager that can be used to inspect or change the
  1558.      * database schema through the connection.
  1559.      *
  1560.      * @throws Exception
  1561.      */
  1562.     public function createSchemaManager(): AbstractSchemaManager
  1563.     {
  1564.         return $this->_driver->getSchemaManager(
  1565.             $this,
  1566.             $this->getDatabasePlatform()
  1567.         );
  1568.     }
  1570.     /**
  1571.      * Gets the SchemaManager that can be used to inspect or change the
  1572.      * database schema through the connection.
  1573.      *
  1574.      * @deprecated Use {@see createSchemaManager()} instead.
  1575.      *
  1576.      * @return AbstractSchemaManager
  1577.      *
  1578.      * @throws Exception
  1579.      */
  1580.     public function getSchemaManager()
  1581.     {
  1582.         Deprecation::triggerIfCalledFromOutside(
  1583.             'doctrine/dbal',
  1584.             'https://github.com/doctrine/dbal/issues/4515',
  1585.             'Connection::getSchemaManager() is deprecated, use Connection::createSchemaManager() instead.'
  1586.         );
  1588.         if ($this->_schemaManager === null) {
  1589.             $this->_schemaManager = $this->createSchemaManager();
  1590.         }
  1592.         return $this->_schemaManager;
  1593.     }
  1595.     /**
  1596.      * Marks the current transaction so that the only possible
  1597.      * outcome for the transaction to be rolled back.
  1598.      *
  1599.      * @return void
  1600.      *
  1601.      * @throws ConnectionException If no transaction is active.
  1602.      */
  1603.     public function setRollbackOnly()
  1604.     {
  1605.         if ($this->transactionNestingLevel === 0) {
  1606.             throw ConnectionException::noActiveTransaction();
  1607.         }
  1609.         $this->isRollbackOnly = true;
  1610.     }
  1612.     /**
  1613.      * Checks whether the current transaction is marked for rollback only.
  1614.      *
  1615.      * @return bool
  1616.      *
  1617.      * @throws ConnectionException If no transaction is active.
  1618.      */
  1619.     public function isRollbackOnly()
  1620.     {
  1621.         if ($this->transactionNestingLevel === 0) {
  1622.             throw ConnectionException::noActiveTransaction();
  1623.         }
  1625.         return $this->isRollbackOnly;
  1626.     }
  1628.     /**
  1629.      * Converts a given value to its database representation according to the conversion
  1630.      * rules of a specific DBAL mapping type.
  1631.      *
  1632.      * @param mixed  $value The value to convert.
  1633.      * @param string $type  The name of the DBAL mapping type.
  1634.      *
  1635.      * @return mixed The converted value.
  1636.      *
  1637.      * @throws Exception
  1638.      */
  1639.     public function convertToDatabaseValue($value, $type)
  1640.     {
  1641.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1642.     }
  1644.     /**
  1645.      * Converts a given value to its PHP representation according to the conversion
  1646.      * rules of a specific DBAL mapping type.
  1647.      *
  1648.      * @param mixed  $value The value to convert.
  1649.      * @param string $type  The name of the DBAL mapping type.
  1650.      *
  1651.      * @return mixed The converted type.
  1652.      *
  1653.      * @throws Exception
  1654.      */
  1655.     public function convertToPHPValue($value, $type)
  1656.     {
  1657.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  1658.     }
  1660.     /**
  1661.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  1662.      * or DBAL mapping type, to a given statement.
  1663.      *
  1664.      * @param DriverStatement                                                      $stmt   Prepared statement
  1665.      * @param list<mixed>|array<string, mixed>                                     $params Statement parameters
  1666.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1667.      *
  1668.      * @throws Exception
  1669.      */
  1670.     private function _bindTypedValues(DriverStatement $stmt, array $params, array $types): void
  1671.     {
  1672.         // Check whether parameters are positional or named. Mixing is not allowed.
  1673.         if (is_int(key($params))) {
  1674.             $bindIndex = 1;
  1676.             foreach ($params as $key => $value) {
  1677.                 if (isset($types[$key])) {
  1678.                     $type                  = $types[$key];
  1679.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1680.                     $stmt->bindValue($bindIndex, $value, $bindingType);
  1681.                 } else {
  1682.                     $stmt->bindValue($bindIndex, $value);
  1683.                 }
  1685.                 ++$bindIndex;
  1686.             }
  1687.         } else {
  1688.             // Named parameters
  1689.             foreach ($params as $name => $value) {
  1690.                 if (isset($types[$name])) {
  1691.                     $type                  = $types[$name];
  1692.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  1693.                     $stmt->bindValue($name, $value, $bindingType);
  1694.                 } else {
  1695.                     $stmt->bindValue($name, $value);
  1696.                 }
  1697.             }
  1698.         }
  1699.     }
  1701.     /**
  1702.      * Gets the binding type of a given type.
  1703.      *
  1704.      * @param mixed                $value The value to bind.
  1705.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  1706.      *
  1707.      * @return array{mixed, int} [0] => the (escaped) value, [1] => the binding type.
  1708.      *
  1709.      * @throws Exception
  1710.      */
  1711.     private function getBindingInfo($value, $type): array
  1712.     {
  1713.         if (is_string($type)) {
  1714.             $type = Type::getType($type);
  1715.         }
  1717.         if ($type instanceof Type) {
  1718.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  1719.             $bindingType = $type->getBindingType();
  1720.         } else {
  1721.             $bindingType = $type ?? ParameterType::STRING;
  1722.         }
  1724.         return [$value, $bindingType];
  1725.     }
  1727.     /**
  1728.      * Creates a new instance of a SQL query builder.
  1729.      *
  1730.      * @return QueryBuilder
  1731.      */
  1732.     public function createQueryBuilder()
  1733.     {
  1734.         return new Query\QueryBuilder($this);
  1735.     }
  1737.     /**
  1738.      * @internal
  1739.      *
  1740.      * @param list<mixed>|array<string, mixed>                                     $params
  1741.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1742.      */
  1743.     final public function convertExceptionDuringQuery(
  1744.         Driver\Exception $e,
  1745.         string $sql,
  1746.         array $params = [],
  1747.         array $types = []
  1748.     ): DriverException {
  1749.         return $this->handleDriverException($e, new Query($sql, $params, $types));
  1750.     }
  1752.     /**
  1753.      * @internal
  1754.      */
  1755.     final public function convertException(Driver\Exception $e): DriverException
  1756.     {
  1757.         return $this->handleDriverException($e, null);
  1758.     }
  1760.     /**
  1761.      * @param array<int, mixed>|array<string, mixed>                               $params
  1762.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1763.      *
  1764.      * @return array{string, list<mixed>, array<int,Type|int|string|null>}
  1765.      */
  1766.     private function expandArrayParameters(string $sql, array $params, array $types): array
  1767.     {
  1768.         if ($this->parser === null) {
  1769.             $this->parser = $this->getDatabasePlatform()->createSQLParser();
  1770.         }
  1772.         $visitor = new ExpandArrayParameters($params, $types);
  1774.         $this->parser->parse($sql, $visitor);
  1776.         return [
  1777.             $visitor->getSQL(),
  1778.             $visitor->getParameters(),
  1779.             $visitor->getTypes(),
  1780.         ];
  1781.     }
  1783.     /**
  1784.      * @param array<int, mixed>|array<string, mixed>                               $params
  1785.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  1786.      */
  1787.     private function needsArrayParameterConversion(array $params, array $types): bool
  1788.     {
  1789.         if (is_string(key($params))) {
  1790.             return true;
  1791.         }
  1793.         foreach ($types as $type) {
  1794.             if (
  1795.                 $type === self::PARAM_INT_ARRAY
  1796.                 || $type === self::PARAM_STR_ARRAY
  1797.                 || $type === self::PARAM_ASCII_STR_ARRAY
  1798.             ) {
  1799.                 return true;
  1800.             }
  1801.         }
  1803.         return false;
  1804.     }
  1806.     private function handleDriverException(
  1807.         Driver\Exception $driverException,
  1808.         ?Query $query
  1809.     ): DriverException {
  1810.         if ($this->exceptionConverter === null) {
  1811.             $this->exceptionConverter = $this->_driver->getExceptionConverter();
  1812.         }
  1814.         $exception = $this->exceptionConverter->convert($driverException, $query);
  1816.         if ($exception instanceof ConnectionLost) {
  1817.             $this->close();
  1818.         }
  1820.         return $exception;
  1821.     }
  1823.     /**
  1824.      * BC layer for a wide-spread use-case of old DBAL APIs
  1825.      *
  1826.      * @deprecated This API is deprecated and will be removed after 2022
  1827.      *
  1828.      * @param array<mixed>           $params The query parameters
  1829.      * @param array<int|string|null> $types  The parameter types
  1830.      */
  1831.     public function executeUpdate(string $sql, array $params = [], array $types = []): int
  1832.     {
  1833.         return $this->executeStatement($sql, $params, $types);
  1834.     }
  1836.     /**
  1837.      * BC layer for a wide-spread use-case of old DBAL APIs
  1838.      *
  1839.      * @deprecated This API is deprecated and will be removed after 2022
  1840.      */
  1841.     public function query(string $sql): Result
  1842.     {
  1843.         return $this->executeQuery($sql);
  1844.     }
  1846.     /**
  1847.      * BC layer for a wide-spread use-case of old DBAL APIs
  1848.      *
  1849.      * @deprecated This API is deprecated and will be removed after 2022
  1850.      */
  1851.     public function exec(string $sql): int
  1852.     {
  1853.         return $this->executeStatement($sql);
  1854.     }
  1855. }