vendor/doctrine/dbal/lib/Doctrine/DBAL/Connection.php line 1940

Open in your IDE?
  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Closure;
  6. use Doctrine\Common\EventManager;
  7. use Doctrine\DBAL\Cache\ArrayStatement;
  8. use Doctrine\DBAL\Cache\CacheException;
  9. use Doctrine\DBAL\Cache\QueryCacheProfile;
  10. use Doctrine\DBAL\Cache\ResultCacheStatement;
  11. use Doctrine\DBAL\Driver\Connection as DriverConnection;
  12. use Doctrine\DBAL\Driver\PingableConnection;
  13. use Doctrine\DBAL\Driver\ResultStatement;
  14. use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
  15. use Doctrine\DBAL\Exception\ConnectionLost;
  16. use Doctrine\DBAL\Exception\InvalidArgumentException;
  17. use Doctrine\DBAL\Exception\NoKeyValue;
  18. use Doctrine\DBAL\Platforms\AbstractPlatform;
  19. use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
  20. use Doctrine\DBAL\Query\QueryBuilder;
  21. use Doctrine\DBAL\Schema\AbstractSchemaManager;
  22. use Doctrine\DBAL\Types\Type;
  23. use Doctrine\Deprecations\Deprecation;
  24. use Throwable;
  25. use Traversable;
  27. use function array_key_exists;
  28. use function array_shift;
  29. use function assert;
  30. use function func_get_args;
  31. use function implode;
  32. use function is_int;
  33. use function is_string;
  34. use function key;
  36. /**
  37.  * A wrapper around a Doctrine\DBAL\Driver\Connection that adds features like
  38.  * events, transaction isolation levels, configuration, emulated transaction nesting,
  39.  * lazy connecting and more.
  40.  *
  41.  * @psalm-import-type Params from DriverManager
  42.  */
  43. class Connection implements DriverConnection
  44. {
  45.     /**
  46.      * Constant for transaction isolation level READ UNCOMMITTED.
  47.      *
  48.      * @deprecated Use TransactionIsolationLevel::READ_UNCOMMITTED.
  49.      */
  50.     public const TRANSACTION_READ_UNCOMMITTED = TransactionIsolationLevel::READ_UNCOMMITTED;
  52.     /**
  53.      * Constant for transaction isolation level READ COMMITTED.
  54.      *
  55.      * @deprecated Use TransactionIsolationLevel::READ_COMMITTED.
  56.      */
  57.     public const TRANSACTION_READ_COMMITTED = TransactionIsolationLevel::READ_COMMITTED;
  59.     /**
  60.      * Constant for transaction isolation level REPEATABLE READ.
  61.      *
  62.      * @deprecated Use TransactionIsolationLevel::REPEATABLE_READ.
  63.      */
  64.     public const TRANSACTION_REPEATABLE_READ = TransactionIsolationLevel::REPEATABLE_READ;
  66.     /**
  67.      * Constant for transaction isolation level SERIALIZABLE.
  68.      *
  69.      * @deprecated Use TransactionIsolationLevel::SERIALIZABLE.
  70.      */
  71.     public const TRANSACTION_SERIALIZABLE = TransactionIsolationLevel::SERIALIZABLE;
  73.     /**
  74.      * Represents an array of ints to be expanded by Doctrine SQL parsing.
  75.      */
  76.     public const PARAM_INT_ARRAY = ParameterType::INTEGER + self::ARRAY_PARAM_OFFSET;
  78.     /**
  79.      * Represents an array of strings to be expanded by Doctrine SQL parsing.
  80.      */
  81.     public const PARAM_STR_ARRAY = ParameterType::STRING + self::ARRAY_PARAM_OFFSET;
  83.     /**
  84.      * Offset by which PARAM_* constants are detected as arrays of the param type.
  85.      */
  86.     public const ARRAY_PARAM_OFFSET = 100;
  88.     /**
  89.      * The wrapped driver connection.
  90.      *
  91.      * @var \Doctrine\DBAL\Driver\Connection|null
  92.      */
  93.     protected $_conn;
  95.     /** @var Configuration */
  96.     protected $_config;
  98.     /** @var EventManager */
  99.     protected $_eventManager;
  101.     /** @var ExpressionBuilder */
  102.     protected $_expr;
  104.     /**
  105.      * The current auto-commit mode of this connection.
  106.      *
  107.      * @var bool
  108.      */
  109.     private $autoCommit = true;
  111.     /**
  112.      * The transaction nesting level.
  113.      *
  114.      * @var int
  115.      */
  116.     private $transactionNestingLevel = 0;
  118.     /**
  119.      * The currently active transaction isolation level or NULL before it has been determined.
  120.      *
  121.      * @var int|null
  122.      */
  123.     private $transactionIsolationLevel;
  125.     /**
  126.      * If nested transactions should use savepoints.
  127.      *
  128.      * @var bool
  129.      */
  130.     private $nestTransactionsWithSavepoints = false;
  132.     /**
  133.      * The parameters used during creation of the Connection instance.
  134.      *
  135.      * @var array<string,mixed>
  136.      * @phpstan-var array<string,mixed>
  137.      * @psalm-var Params
  138.      */
  139.     private $params;
  141.     /**
  142.      * The database platform object used by the connection or NULL before it's initialized.
  143.      *
  144.      * @var AbstractPlatform|null
  145.      */
  146.     private $platform;
  148.     /**
  149.      * The schema manager.
  150.      *
  151.      * @var AbstractSchemaManager|null
  152.      */
  153.     protected $_schemaManager;
  155.     /**
  156.      * The used DBAL driver.
  157.      *
  158.      * @var Driver
  159.      */
  160.     protected $_driver;
  162.     /**
  163.      * Flag that indicates whether the current transaction is marked for rollback only.
  164.      *
  165.      * @var bool
  166.      */
  167.     private $isRollbackOnly = false;
  169.     /** @var int */
  170.     protected $defaultFetchMode = FetchMode::ASSOCIATIVE;
  172.     /**
  173.      * Initializes a new instance of the Connection class.
  174.      *
  175.      * @internal The connection can be only instantiated by the driver manager.
  176.      *
  177.      * @param array<string,mixed> $params       The connection parameters.
  178.      * @param Driver              $driver       The driver to use.
  179.      * @param Configuration|null  $config       The configuration, optional.
  180.      * @param EventManager|null   $eventManager The event manager, optional.
  181.      *
  182.      * @throws Exception
  183.      *
  184.      * @phpstan-param array<string,mixed> $params
  185.      * @psalm-param Params $params
  186.      */
  187.     public function __construct(
  188.         array $params,
  189.         Driver $driver,
  190.         ?Configuration $config = null,
  191.         ?EventManager $eventManager = null
  192.     ) {
  193.         $this->_driver = $driver;
  194.         $this->params  = $params;
  196.         if (isset($params['pdo'])) {
  197.             $this->_conn = $params['pdo'];
  198.             unset($this->params['pdo']);
  199.         }
  201.         if (isset($params['platform'])) {
  202.             if (! $params['platform'] instanceof Platforms\AbstractPlatform) {
  203.                 throw Exception::invalidPlatformType($params['platform']);
  204.             }
  206.             $this->platform = $params['platform'];
  207.         }
  209.         // Create default config and event manager if none given
  210.         if (! $config) {
  211.             $config = new Configuration();
  212.         }
  214.         if (! $eventManager) {
  215.             $eventManager = new EventManager();
  216.         }
  218.         $this->_config       = $config;
  219.         $this->_eventManager = $eventManager;
  221.         $this->_expr = new Query\Expression\ExpressionBuilder($this);
  223.         $this->autoCommit = $config->getAutoCommit();
  224.     }
  226.     /**
  227.      * Gets the parameters used during instantiation.
  228.      *
  229.      * @internal
  230.      *
  231.      * @return array<string,mixed>
  232.      *
  233.      * @phpstan-return array<string,mixed>
  234.      * @psalm-return Params
  235.      */
  236.     public function getParams()
  237.     {
  238.         return $this->params;
  239.     }
  241.     /**
  242.      * Gets the name of the database this Connection is connected to.
  243.      *
  244.      * @return string
  245.      */
  246.     public function getDatabase()
  247.     {
  248.         return $this->_driver->getDatabase($this);
  249.     }
  251.     /**
  252.      * Gets the hostname of the currently connected database.
  253.      *
  254.      * @deprecated
  255.      *
  256.      * @return string|null
  257.      */
  258.     public function getHost()
  259.     {
  260.         Deprecation::trigger(
  261.             'doctrine/dbal',
  262.             'https://github.com/doctrine/dbal/issues/3580',
  263.             'Connection::getHost() is deprecated, get the database server host from application config ' .
  264.             'or as a last resort from internal Connection::getParams() API.'
  265.         );
  267.         return $this->params['host'] ?? null;
  268.     }
  270.     /**
  271.      * Gets the port of the currently connected database.
  272.      *
  273.      * @deprecated
  274.      *
  275.      * @return mixed
  276.      */
  277.     public function getPort()
  278.     {
  279.         Deprecation::trigger(
  280.             'doctrine/dbal',
  281.             'https://github.com/doctrine/dbal/issues/3580',
  282.             'Connection::getPort() is deprecated, get the database server port from application config ' .
  283.             'or as a last resort from internal Connection::getParams() API.'
  284.         );
  286.         return $this->params['port'] ?? null;
  287.     }
  289.     /**
  290.      * Gets the username used by this connection.
  291.      *
  292.      * @deprecated
  293.      *
  294.      * @return string|null
  295.      */
  296.     public function getUsername()
  297.     {
  298.         Deprecation::trigger(
  299.             'doctrine/dbal',
  300.             'https://github.com/doctrine/dbal/issues/3580',
  301.             'Connection::getUsername() is deprecated, get the username from application config ' .
  302.             'or as a last resort from internal Connection::getParams() API.'
  303.         );
  305.         return $this->params['user'] ?? null;
  306.     }
  308.     /**
  309.      * Gets the password used by this connection.
  310.      *
  311.      * @deprecated
  312.      *
  313.      * @return string|null
  314.      */
  315.     public function getPassword()
  316.     {
  317.         Deprecation::trigger(
  318.             'doctrine/dbal',
  319.             'https://github.com/doctrine/dbal/issues/3580',
  320.             'Connection::getPassword() is deprecated, get the password from application config ' .
  321.             'or as a last resort from internal Connection::getParams() API.'
  322.         );
  324.         return $this->params['password'] ?? null;
  325.     }
  327.     /**
  328.      * Gets the DBAL driver instance.
  329.      *
  330.      * @return Driver
  331.      */
  332.     public function getDriver()
  333.     {
  334.         return $this->_driver;
  335.     }
  337.     /**
  338.      * Gets the Configuration used by the Connection.
  339.      *
  340.      * @return Configuration
  341.      */
  342.     public function getConfiguration()
  343.     {
  344.         return $this->_config;
  345.     }
  347.     /**
  348.      * Gets the EventManager used by the Connection.
  349.      *
  350.      * @return EventManager
  351.      */
  352.     public function getEventManager()
  353.     {
  354.         return $this->_eventManager;
  355.     }
  357.     /**
  358.      * Gets the DatabasePlatform for the connection.
  359.      *
  360.      * @return AbstractPlatform
  361.      *
  362.      * @throws Exception
  363.      */
  364.     public function getDatabasePlatform()
  365.     {
  366.         if ($this->platform === null) {
  367.             $this->platform = $this->detectDatabasePlatform();
  368.             $this->platform->setEventManager($this->_eventManager);
  369.         }
  371.         return $this->platform;
  372.     }
  374.     /**
  375.      * Gets the ExpressionBuilder for the connection.
  376.      *
  377.      * @return ExpressionBuilder
  378.      */
  379.     public function getExpressionBuilder()
  380.     {
  381.         return $this->_expr;
  382.     }
  384.     /**
  385.      * Establishes the connection with the database.
  386.      *
  387.      * @return bool TRUE if the connection was successfully established, FALSE if
  388.      *              the connection is already open.
  389.      */
  390.     public function connect()
  391.     {
  392.         if ($this->_conn !== null) {
  393.             return false;
  394.         }
  396.         $driverOptions = $this->params['driverOptions'] ?? [];
  397.         $user          = $this->params['user'] ?? null;
  398.         $password      = $this->params['password'] ?? null;
  400.         $this->_conn = $this->_driver->connect($this->params, $user, $password, $driverOptions);
  402.         $this->transactionNestingLevel = 0;
  404.         if ($this->autoCommit === false) {
  405.             $this->beginTransaction();
  406.         }
  408.         if ($this->_eventManager->hasListeners(Events::postConnect)) {
  409.             $eventArgs = new Event\ConnectionEventArgs($this);
  410.             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
  411.         }
  413.         return true;
  414.     }
  416.     /**
  417.      * Detects and sets the database platform.
  418.      *
  419.      * Evaluates custom platform class and version in order to set the correct platform.
  420.      *
  421.      * @throws Exception If an invalid platform was specified for this connection.
  422.      */
  423.     private function detectDatabasePlatform(): AbstractPlatform
  424.     {
  425.         $version = $this->getDatabasePlatformVersion();
  427.         if ($version !== null) {
  428.             assert($this->_driver instanceof VersionAwarePlatformDriver);
  430.             return $this->_driver->createDatabasePlatformForVersion($version);
  431.         }
  433.         return $this->_driver->getDatabasePlatform();
  434.     }
  436.     /**
  437.      * Returns the version of the related platform if applicable.
  438.      *
  439.      * Returns null if either the driver is not capable to create version
  440.      * specific platform instances, no explicit server version was specified
  441.      * or the underlying driver connection cannot determine the platform
  442.      * version without having to query it (performance reasons).
  443.      *
  444.      * @return string|null
  445.      *
  446.      * @throws Throwable
  447.      */
  448.     private function getDatabasePlatformVersion()
  449.     {
  450.         // Driver does not support version specific platforms.
  451.         if (! $this->_driver instanceof VersionAwarePlatformDriver) {
  452.             return null;
  453.         }
  455.         // Explicit platform version requested (supersedes auto-detection).
  456.         if (isset($this->params['serverVersion'])) {
  457.             return $this->params['serverVersion'];
  458.         }
  460.         // If not connected, we need to connect now to determine the platform version.
  461.         if ($this->_conn === null) {
  462.             try {
  463.                 $this->connect();
  464.             } catch (Throwable $originalException) {
  465.                 if (empty($this->params['dbname'])) {
  466.                     throw $originalException;
  467.                 }
  469.                 // The database to connect to might not yet exist.
  470.                 // Retry detection without database name connection parameter.
  471.                 $params = $this->params;
  473.                 unset($this->params['dbname']);
  475.                 try {
  476.                     $this->connect();
  477.                 } catch (Throwable $fallbackException) {
  478.                     // Either the platform does not support database-less connections
  479.                     // or something else went wrong.
  480.                     throw $originalException;
  481.                 } finally {
  482.                     $this->params = $params;
  483.                 }
  485.                 $serverVersion = $this->getServerVersion();
  487.                 // Close "temporary" connection to allow connecting to the real database again.
  488.                 $this->close();
  490.                 return $serverVersion;
  491.             }
  492.         }
  494.         return $this->getServerVersion();
  495.     }
  497.     /**
  498.      * Returns the database server version if the underlying driver supports it.
  499.      *
  500.      * @return string|null
  501.      */
  502.     private function getServerVersion()
  503.     {
  504.         $connection = $this->getWrappedConnection();
  506.         // Automatic platform version detection.
  507.         if ($connection instanceof ServerInfoAwareConnection && ! $connection->requiresQueryForServerVersion()) {
  508.             return $connection->getServerVersion();
  509.         }
  511.         // Unable to detect platform version.
  512.         return null;
  513.     }
  515.     /**
  516.      * Returns the current auto-commit mode for this connection.
  517.      *
  518.      * @see    setAutoCommit
  519.      *
  520.      * @return bool True if auto-commit mode is currently enabled for this connection, false otherwise.
  521.      */
  522.     public function isAutoCommit()
  523.     {
  524.         return $this->autoCommit === true;
  525.     }
  527.     /**
  528.      * Sets auto-commit mode for this connection.
  529.      *
  530.      * If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual
  531.      * transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either
  532.      * the method commit or the method rollback. By default, new connections are in auto-commit mode.
  533.      *
  534.      * NOTE: If this method is called during a transaction and the auto-commit mode is changed, the transaction is
  535.      * committed. If this method is called and the auto-commit mode is not changed, the call is a no-op.
  536.      *
  537.      * @see   isAutoCommit
  538.      *
  539.      * @param bool $autoCommit True to enable auto-commit mode; false to disable it.
  540.      *
  541.      * @return void
  542.      */
  543.     public function setAutoCommit($autoCommit)
  544.     {
  545.         $autoCommit = (bool) $autoCommit;
  547.         // Mode not changed, no-op.
  548.         if ($autoCommit === $this->autoCommit) {
  549.             return;
  550.         }
  552.         $this->autoCommit = $autoCommit;
  554.         // Commit all currently active transactions if any when switching auto-commit mode.
  555.         if ($this->_conn === null || $this->transactionNestingLevel === 0) {
  556.             return;
  557.         }
  559.         $this->commitAll();
  560.     }
  562.     /**
  563.      * Sets the fetch mode.
  564.      *
  565.      * @deprecated Use one of the fetch- or iterate-related methods.
  566.      *
  567.      * @param int $fetchMode
  568.      *
  569.      * @return void
  570.      */
  571.     public function setFetchMode($fetchMode)
  572.     {
  573.         Deprecation::trigger(
  574.             'doctrine/dbal',
  575.             'https://github.com/doctrine/dbal/pull/4019',
  576.             'Default Fetch Mode configuration is deprecated, use explicit Connection::fetch*() APIs instead.'
  577.         );
  579.         $this->defaultFetchMode = $fetchMode;
  580.     }
  582.     /**
  583.      * Prepares and executes an SQL query and returns the first row of the result
  584.      * as an associative array.
  585.      *
  586.      * @deprecated Use fetchAssociative()
  587.      *
  588.      * @param string                                                               $sql    SQL query
  589.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  590.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  591.      *
  592.      * @return array<string, mixed>|false False is returned if no rows are found.
  593.      *
  594.      * @throws Exception
  595.      */
  596.     public function fetchAssoc($sql, array $params = [], array $types = [])
  597.     {
  598.         Deprecation::trigger(
  599.             'doctrine/dbal',
  600.             'https://github.com/doctrine/dbal/pull/4019',
  601.             'Connection::fetchAssoc() is deprecated, use Connection::fetchAssociative() API instead.'
  602.         );
  604.         return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::ASSOCIATIVE);
  605.     }
  607.     /**
  608.      * Prepares and executes an SQL query and returns the first row of the result
  609.      * as a numerically indexed array.
  610.      *
  611.      * @deprecated Use fetchNumeric()
  612.      *
  613.      * @param string                                                               $sql    SQL query
  614.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  615.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  616.      *
  617.      * @return array<int, mixed>|false False is returned if no rows are found.
  618.      */
  619.     public function fetchArray($sql, array $params = [], array $types = [])
  620.     {
  621.         Deprecation::trigger(
  622.             'doctrine/dbal',
  623.             'https://github.com/doctrine/dbal/pull/4019',
  624.             'Connection::fetchArray() is deprecated, use Connection::fetchNumeric() API instead.'
  625.         );
  627.         return $this->executeQuery($sql, $params, $types)->fetch(FetchMode::NUMERIC);
  628.     }
  630.     /**
  631.      * Prepares and executes an SQL query and returns the value of a single column
  632.      * of the first row of the result.
  633.      *
  634.      * @deprecated Use fetchOne() instead.
  635.      *
  636.      * @param string                                                               $sql    SQL query
  637.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  638.      * @param int                                                                  $column 0-indexed column number
  639.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  640.      *
  641.      * @return mixed|false False is returned if no rows are found.
  642.      *
  643.      * @throws Exception
  644.      */
  645.     public function fetchColumn($sql, array $params = [], $column = 0, array $types = [])
  646.     {
  647.         Deprecation::trigger(
  648.             'doctrine/dbal',
  649.             'https://github.com/doctrine/dbal/pull/4019',
  650.             'Connection::fetchColumn() is deprecated, use Connection::fetchOne() API instead.'
  651.         );
  653.         return $this->executeQuery($sql, $params, $types)->fetchColumn($column);
  654.     }
  656.     /**
  657.      * Prepares and executes an SQL query and returns the first row of the result
  658.      * as an associative array.
  659.      *
  660.      * @param string                                                               $query  SQL query
  661.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  662.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  663.      *
  664.      * @return array<string, mixed>|false False is returned if no rows are found.
  665.      *
  666.      * @throws Exception
  667.      */
  668.     public function fetchAssociative(string $query, array $params = [], array $types = [])
  669.     {
  670.         try {
  671.             $stmt = $this->ensureForwardCompatibilityStatement(
  672.                 $this->executeQuery($query, $params, $types)
  673.             );
  675.             return $stmt->fetchAssociative();
  676.         } catch (Throwable $e) {
  677.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  678.         }
  679.     }
  681.     /**
  682.      * Prepares and executes an SQL query and returns the first row of the result
  683.      * as a numerically indexed array.
  684.      *
  685.      * @param string                                                               $query  SQL query
  686.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  687.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  688.      *
  689.      * @return array<int, mixed>|false False is returned if no rows are found.
  690.      *
  691.      * @throws Exception
  692.      */
  693.     public function fetchNumeric(string $query, array $params = [], array $types = [])
  694.     {
  695.         try {
  696.             $stmt = $this->ensureForwardCompatibilityStatement(
  697.                 $this->executeQuery($query, $params, $types)
  698.             );
  700.             return $stmt->fetchNumeric();
  701.         } catch (Throwable $e) {
  702.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  703.         }
  704.     }
  706.     /**
  707.      * Prepares and executes an SQL query and returns the value of a single column
  708.      * of the first row of the result.
  709.      *
  710.      * @param string                                                               $query  SQL query
  711.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  712.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  713.      *
  714.      * @return mixed|false False is returned if no rows are found.
  715.      *
  716.      * @throws Exception
  717.      */
  718.     public function fetchOne(string $query, array $params = [], array $types = [])
  719.     {
  720.         try {
  721.             $stmt = $this->ensureForwardCompatibilityStatement(
  722.                 $this->executeQuery($query, $params, $types)
  723.             );
  725.             return $stmt->fetchOne();
  726.         } catch (Throwable $e) {
  727.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  728.         }
  729.     }
  731.     /**
  732.      * Whether an actual connection to the database is established.
  733.      *
  734.      * @return bool
  735.      */
  736.     public function isConnected()
  737.     {
  738.         return $this->_conn !== null;
  739.     }
  741.     /**
  742.      * Checks whether a transaction is currently active.
  743.      *
  744.      * @return bool TRUE if a transaction is currently active, FALSE otherwise.
  745.      */
  746.     public function isTransactionActive()
  747.     {
  748.         return $this->transactionNestingLevel > 0;
  749.     }
  751.     /**
  752.      * Adds condition based on the criteria to the query components
  753.      *
  754.      * @param array<string,mixed> $criteria   Map of key columns to their values
  755.      * @param string[]            $columns    Column names
  756.      * @param mixed[]             $values     Column values
  757.      * @param string[]            $conditions Key conditions
  758.      *
  759.      * @throws Exception
  760.      */
  761.     private function addCriteriaCondition(
  762.         array $criteria,
  763.         array &$columns,
  764.         array &$values,
  765.         array &$conditions
  766.     ): void {
  767.         $platform = $this->getDatabasePlatform();
  769.         foreach ($criteria as $columnName => $value) {
  770.             if ($value === null) {
  771.                 $conditions[] = $platform->getIsNullExpression($columnName);
  772.                 continue;
  773.             }
  775.             $columns[]    = $columnName;
  776.             $values[]     = $value;
  777.             $conditions[] = $columnName . ' = ?';
  778.         }
  779.     }
  781.     /**
  782.      * Executes an SQL DELETE statement on a table.
  783.      *
  784.      * Table expression and columns are not escaped and are not safe for user-input.
  785.      *
  786.      * @param string                                                               $table    Table name
  787.      * @param array<string, mixed>                                                 $criteria Deletion criteria
  788.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  789.      *
  790.      * @return int The number of affected rows.
  791.      *
  792.      * @throws Exception
  793.      */
  794.     public function delete($table, array $criteria, array $types = [])
  795.     {
  796.         if (empty($criteria)) {
  797.             throw InvalidArgumentException::fromEmptyCriteria();
  798.         }
  800.         $columns = $values = $conditions = [];
  802.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  804.         return $this->executeStatement(
  805.             'DELETE FROM ' . $table . ' WHERE ' . implode(' AND ', $conditions),
  806.             $values,
  807.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  808.         );
  809.     }
  811.     /**
  812.      * Closes the connection.
  813.      *
  814.      * @return void
  815.      */
  816.     public function close()
  817.     {
  818.         $this->_conn = null;
  819.     }
  821.     /**
  822.      * Sets the transaction isolation level.
  823.      *
  824.      * @param int $level The level to set.
  825.      *
  826.      * @return int
  827.      */
  828.     public function setTransactionIsolation($level)
  829.     {
  830.         $this->transactionIsolationLevel = $level;
  832.         return $this->executeStatement($this->getDatabasePlatform()->getSetTransactionIsolationSQL($level));
  833.     }
  835.     /**
  836.      * Gets the currently active transaction isolation level.
  837.      *
  838.      * @return int The current transaction isolation level.
  839.      */
  840.     public function getTransactionIsolation()
  841.     {
  842.         if ($this->transactionIsolationLevel === null) {
  843.             $this->transactionIsolationLevel = $this->getDatabasePlatform()->getDefaultTransactionIsolationLevel();
  844.         }
  846.         return $this->transactionIsolationLevel;
  847.     }
  849.     /**
  850.      * Executes an SQL UPDATE statement on a table.
  851.      *
  852.      * Table expression and columns are not escaped and are not safe for user-input.
  853.      *
  854.      * @param string                                                               $table    Table name
  855.      * @param array<string, mixed>                                                 $data     Column-value pairs
  856.      * @param array<string, mixed>                                                 $criteria Update criteria
  857.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types    Parameter types
  858.      *
  859.      * @return int The number of affected rows.
  860.      *
  861.      * @throws Exception
  862.      */
  863.     public function update($table, array $data, array $criteria, array $types = [])
  864.     {
  865.         $columns = $values = $conditions = $set = [];
  867.         foreach ($data as $columnName => $value) {
  868.             $columns[] = $columnName;
  869.             $values[]  = $value;
  870.             $set[]     = $columnName . ' = ?';
  871.         }
  873.         $this->addCriteriaCondition($criteria, $columns, $values, $conditions);
  875.         if (is_string(key($types))) {
  876.             $types = $this->extractTypeValues($columns, $types);
  877.         }
  879.         $sql = 'UPDATE ' . $table . ' SET ' . implode(', ', $set)
  880.                 . ' WHERE ' . implode(' AND ', $conditions);
  882.         return $this->executeStatement($sql, $values, $types);
  883.     }
  885.     /**
  886.      * Inserts a table row with specified data.
  887.      *
  888.      * Table expression and columns are not escaped and are not safe for user-input.
  889.      *
  890.      * @param string                                                               $table Table name
  891.      * @param array<string, mixed>                                                 $data  Column-value pairs
  892.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types Parameter types
  893.      *
  894.      * @return int The number of affected rows.
  895.      *
  896.      * @throws Exception
  897.      */
  898.     public function insert($table, array $data, array $types = [])
  899.     {
  900.         if (empty($data)) {
  901.             return $this->executeStatement('INSERT INTO ' . $table . ' () VALUES ()');
  902.         }
  904.         $columns = [];
  905.         $values  = [];
  906.         $set     = [];
  908.         foreach ($data as $columnName => $value) {
  909.             $columns[] = $columnName;
  910.             $values[]  = $value;
  911.             $set[]     = '?';
  912.         }
  914.         return $this->executeStatement(
  915.             'INSERT INTO ' . $table . ' (' . implode(', ', $columns) . ')' .
  916.             ' VALUES (' . implode(', ', $set) . ')',
  917.             $values,
  918.             is_string(key($types)) ? $this->extractTypeValues($columns, $types) : $types
  919.         );
  920.     }
  922.     /**
  923.      * Extract ordered type list from an ordered column list and type map.
  924.      *
  925.      * @param array<int, string>                                                   $columnList
  926.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  927.      *
  928.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  929.      */
  930.     private function extractTypeValues(array $columnList, array $types)
  931.     {
  932.         $typeValues = [];
  934.         foreach ($columnList as $columnIndex => $columnName) {
  935.             $typeValues[] = $types[$columnName] ?? ParameterType::STRING;
  936.         }
  938.         return $typeValues;
  939.     }
  941.     /**
  942.      * Quotes a string so it can be safely used as a table or column name, even if
  943.      * it is a reserved name.
  944.      *
  945.      * Delimiting style depends on the underlying database platform that is being used.
  946.      *
  947.      * NOTE: Just because you CAN use quoted identifiers does not mean
  948.      * you SHOULD use them. In general, they end up causing way more
  949.      * problems than they solve.
  950.      *
  951.      * @param string $str The name to be quoted.
  952.      *
  953.      * @return string The quoted name.
  954.      */
  955.     public function quoteIdentifier($str)
  956.     {
  957.         return $this->getDatabasePlatform()->quoteIdentifier($str);
  958.     }
  960.     /**
  961.      * {@inheritDoc}
  962.      *
  963.      * @param mixed                $value
  964.      * @param int|string|Type|null $type
  965.      */
  966.     public function quote($value, $type = ParameterType::STRING)
  967.     {
  968.         $connection = $this->getWrappedConnection();
  970.         [$value, $bindingType] = $this->getBindingInfo($value, $type);
  972.         return $connection->quote($value, $bindingType);
  973.     }
  975.     /**
  976.      * Prepares and executes an SQL query and returns the result as an associative array.
  977.      *
  978.      * @deprecated Use fetchAllAssociative()
  979.      *
  980.      * @param string         $sql    The SQL query.
  981.      * @param mixed[]        $params The query parameters.
  982.      * @param int[]|string[] $types  The query parameter types.
  983.      *
  984.      * @return mixed[]
  985.      */
  986.     public function fetchAll($sql, array $params = [], $types = [])
  987.     {
  988.         return $this->executeQuery($sql, $params, $types)->fetchAll();
  989.     }
  991.     /**
  992.      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
  993.      *
  994.      * @param string                                                               $query  SQL query
  995.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  996.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  997.      *
  998.      * @return array<int,array<int,mixed>>
  999.      *
  1000.      * @throws Exception
  1001.      */
  1002.     public function fetchAllNumeric(string $query, array $params = [], array $types = []): array
  1003.     {
  1004.         try {
  1005.             $stmt = $this->ensureForwardCompatibilityStatement(
  1006.                 $this->executeQuery($query, $params, $types)
  1007.             );
  1009.             return $stmt->fetchAllNumeric();
  1010.         } catch (Throwable $e) {
  1011.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1012.         }
  1013.     }
  1015.     /**
  1016.      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
  1017.      *
  1018.      * @param string                                                               $query  SQL query
  1019.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1020.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1021.      *
  1022.      * @return array<int,array<string,mixed>>
  1023.      *
  1024.      * @throws Exception
  1025.      */
  1026.     public function fetchAllAssociative(string $query, array $params = [], array $types = []): array
  1027.     {
  1028.         try {
  1029.             $stmt = $this->ensureForwardCompatibilityStatement(
  1030.                 $this->executeQuery($query, $params, $types)
  1031.             );
  1033.             return $stmt->fetchAllAssociative();
  1034.         } catch (Throwable $e) {
  1035.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1036.         }
  1037.     }
  1039.     /**
  1040.      * Prepares and executes an SQL query and returns the result as an associative array with the keys
  1041.      * mapped to the first column and the values mapped to the second column.
  1042.      *
  1043.      * @param string                                           $query  SQL query
  1044.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1045.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1046.      *
  1047.      * @return array<mixed,mixed>
  1048.      *
  1049.      * @throws Exception
  1050.      */
  1051.     public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
  1052.     {
  1053.         $stmt = $this->executeQuery($query, $params, $types);
  1055.         $this->ensureHasKeyValue($stmt);
  1057.         $data = [];
  1059.         foreach ($stmt->fetchAll(FetchMode::NUMERIC) as [$key, $value]) {
  1060.             $data[$key] = $value;
  1061.         }
  1063.         return $data;
  1064.     }
  1066.     /**
  1067.      * Prepares and executes an SQL query and returns the result as an associative array with the keys mapped
  1068.      * to the first column and the values being an associative array representing the rest of the columns
  1069.      * and their values.
  1070.      *
  1071.      * @param string                                           $query  SQL query
  1072.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1073.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1074.      *
  1075.      * @return array<mixed,array<string,mixed>>
  1076.      *
  1077.      * @throws Exception
  1078.      */
  1079.     public function fetchAllAssociativeIndexed(string $query, array $params = [], array $types = []): array
  1080.     {
  1081.         $stmt = $this->executeQuery($query, $params, $types);
  1083.         $data = [];
  1085.         foreach ($stmt->fetchAll(FetchMode::ASSOCIATIVE) as $row) {
  1086.             $data[array_shift($row)] = $row;
  1087.         }
  1089.         return $data;
  1090.     }
  1092.     /**
  1093.      * Prepares and executes an SQL query and returns the result as an array of the first column values.
  1094.      *
  1095.      * @param string                                                               $query  SQL query
  1096.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1097.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1098.      *
  1099.      * @return array<int,mixed>
  1100.      *
  1101.      * @throws Exception
  1102.      */
  1103.     public function fetchFirstColumn(string $query, array $params = [], array $types = []): array
  1104.     {
  1105.         try {
  1106.             $stmt = $this->ensureForwardCompatibilityStatement(
  1107.                 $this->executeQuery($query, $params, $types)
  1108.             );
  1110.             return $stmt->fetchFirstColumn();
  1111.         } catch (Throwable $e) {
  1112.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1113.         }
  1114.     }
  1116.     /**
  1117.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
  1118.      *
  1119.      * @param string                                                               $query  SQL query
  1120.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1121.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1122.      *
  1123.      * @return Traversable<int,array<int,mixed>>
  1124.      *
  1125.      * @throws Exception
  1126.      */
  1127.     public function iterateNumeric(string $query, array $params = [], array $types = []): Traversable
  1128.     {
  1129.         try {
  1130.             $stmt = $this->ensureForwardCompatibilityStatement(
  1131.                 $this->executeQuery($query, $params, $types)
  1132.             );
  1134.             yield from $stmt->iterateNumeric();
  1135.         } catch (Throwable $e) {
  1136.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1137.         }
  1138.     }
  1140.     /**
  1141.      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
  1142.      * as associative arrays.
  1143.      *
  1144.      * @param string                                                               $query  SQL query
  1145.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1146.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1147.      *
  1148.      * @return Traversable<int,array<string,mixed>>
  1149.      *
  1150.      * @throws Exception
  1151.      */
  1152.     public function iterateAssociative(string $query, array $params = [], array $types = []): Traversable
  1153.     {
  1154.         try {
  1155.             $stmt = $this->ensureForwardCompatibilityStatement(
  1156.                 $this->executeQuery($query, $params, $types)
  1157.             );
  1159.             yield from $stmt->iterateAssociative();
  1160.         } catch (Throwable $e) {
  1161.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1162.         }
  1163.     }
  1165.     /**
  1166.      * Prepares and executes an SQL query and returns the result as an iterator with the keys
  1167.      * mapped to the first column and the values mapped to the second column.
  1168.      *
  1169.      * @param string                                           $query  SQL query
  1170.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1171.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1172.      *
  1173.      * @return Traversable<mixed,mixed>
  1174.      *
  1175.      * @throws Exception
  1176.      */
  1177.     public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
  1178.     {
  1179.         $stmt = $this->executeQuery($query, $params, $types);
  1181.         $this->ensureHasKeyValue($stmt);
  1183.         while (($row = $stmt->fetch(FetchMode::NUMERIC)) !== false) {
  1184.             yield $row[0] => $row[1];
  1185.         }
  1186.     }
  1188.     /**
  1189.      * Prepares and executes an SQL query and returns the result as an iterator with the keys mapped
  1190.      * to the first column and the values being an associative array representing the rest of the columns
  1191.      * and their values.
  1192.      *
  1193.      * @param string                                           $query  SQL query
  1194.      * @param array<int, mixed>|array<string, mixed>           $params Query parameters
  1195.      * @param array<int, int|string>|array<string, int|string> $types  Parameter types
  1196.      *
  1197.      * @return Traversable<mixed,array<string,mixed>>
  1198.      *
  1199.      * @throws Exception
  1200.      */
  1201.     public function iterateAssociativeIndexed(string $query, array $params = [], array $types = []): Traversable
  1202.     {
  1203.         $stmt = $this->executeQuery($query, $params, $types);
  1205.         while (($row = $stmt->fetch(FetchMode::ASSOCIATIVE)) !== false) {
  1206.             yield array_shift($row) => $row;
  1207.         }
  1208.     }
  1210.     /**
  1211.      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
  1212.      *
  1213.      * @param string                                                               $query  SQL query
  1214.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1215.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1216.      *
  1217.      * @return Traversable<int,mixed>
  1218.      *
  1219.      * @throws Exception
  1220.      */
  1221.     public function iterateColumn(string $query, array $params = [], array $types = []): Traversable
  1222.     {
  1223.         try {
  1224.             $stmt = $this->ensureForwardCompatibilityStatement(
  1225.                 $this->executeQuery($query, $params, $types)
  1226.             );
  1228.             yield from $stmt->iterateColumn();
  1229.         } catch (Throwable $e) {
  1230.             $this->handleExceptionDuringQuery($e, $query, $params, $types);
  1231.         }
  1232.     }
  1234.     /**
  1235.      * Prepares an SQL statement.
  1236.      *
  1237.      * @param string $sql The SQL statement to prepare.
  1238.      *
  1239.      * @return Statement The prepared statement.
  1240.      *
  1241.      * @throws Exception
  1242.      */
  1243.     public function prepare($sql)
  1244.     {
  1245.         try {
  1246.             $stmt = new Statement($sql, $this);
  1247.         } catch (Throwable $e) {
  1248.             $this->handleExceptionDuringQuery($e, $sql);
  1249.         }
  1251.         $stmt->setFetchMode($this->defaultFetchMode);
  1253.         return $stmt;
  1254.     }
  1256.     /**
  1257.      * Executes an, optionally parametrized, SQL query.
  1258.      *
  1259.      * If the query is parametrized, a prepared statement is used.
  1260.      * If an SQLLogger is configured, the execution is logged.
  1261.      *
  1262.      * @param string                                                               $sql    SQL query
  1263.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1264.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1265.      *
  1266.      * @return ForwardCompatibility\DriverStatement|ForwardCompatibility\DriverResultStatement
  1267.      *
  1268.      * The executed statement or the cached result statement if a query cache profile is used
  1269.      *
  1270.      * @throws Exception
  1271.      */
  1272.     public function executeQuery($sql, array $params = [], $types = [], ?QueryCacheProfile $qcp = null)
  1273.     {
  1274.         if ($qcp !== null) {
  1275.             return $this->executeCacheQuery($sql, $params, $types, $qcp);
  1276.         }
  1278.         $connection = $this->getWrappedConnection();
  1280.         $logger = $this->_config->getSQLLogger();
  1281.         if ($logger) {
  1282.             $logger->startQuery($sql, $params, $types);
  1283.         }
  1285.         try {
  1286.             if ($params) {
  1287.                 [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1289.                 $stmt = $connection->prepare($sql);
  1290.                 if ($types) {
  1291.                     $this->_bindTypedValues($stmt, $params, $types);
  1292.                     $stmt->execute();
  1293.                 } else {
  1294.                     $stmt->execute($params);
  1295.                 }
  1296.             } else {
  1297.                 $stmt = $connection->query($sql);
  1298.             }
  1299.         } catch (Throwable $e) {
  1300.             $this->handleExceptionDuringQuery(
  1301.                 $e,
  1302.                 $sql,
  1303.                 $params,
  1304.                 $types
  1305.             );
  1306.         }
  1308.         $stmt->setFetchMode($this->defaultFetchMode);
  1310.         if ($logger) {
  1311.             $logger->stopQuery();
  1312.         }
  1314.         return $this->ensureForwardCompatibilityStatement($stmt);
  1315.     }
  1317.     /**
  1318.      * Executes a caching query.
  1319.      *
  1320.      * @param string                                                               $sql    SQL query
  1321.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  1322.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1323.      *
  1324.      * @return ForwardCompatibility\DriverResultStatement
  1325.      *
  1326.      * @throws CacheException
  1327.      */
  1328.     public function executeCacheQuery($sql, $params, $types, QueryCacheProfile $qcp)
  1329.     {
  1330.         $resultCache = $qcp->getResultCacheDriver() ?? $this->_config->getResultCacheImpl();
  1332.         if ($resultCache === null) {
  1333.             throw CacheException::noResultDriverConfigured();
  1334.         }
  1336.         $connectionParams = $this->params;
  1337.         unset($connectionParams['platform']);
  1339.         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
  1341.         // fetch the row pointers entry
  1342.         $data = $resultCache->fetch($cacheKey);
  1344.         if ($data !== false) {
  1345.             // is the real key part of this row pointers map or is the cache only pointing to other cache keys?
  1346.             if (isset($data[$realKey])) {
  1347.                 $stmt = new ArrayStatement($data[$realKey]);
  1348.             } elseif (array_key_exists($realKey, $data)) {
  1349.                 $stmt = new ArrayStatement([]);
  1350.             }
  1351.         }
  1353.         if (! isset($stmt)) {
  1354.             $stmt = new ResultCacheStatement(
  1355.                 $this->executeQuery($sql, $params, $types),
  1356.                 $resultCache,
  1357.                 $cacheKey,
  1358.                 $realKey,
  1359.                 $qcp->getLifetime()
  1360.             );
  1361.         }
  1363.         $stmt->setFetchMode($this->defaultFetchMode);
  1365.         return $this->ensureForwardCompatibilityStatement($stmt);
  1366.     }
  1368.     /**
  1369.      * @return ForwardCompatibility\Result
  1370.      */
  1371.     private function ensureForwardCompatibilityStatement(ResultStatement $stmt)
  1372.     {
  1373.         return ForwardCompatibility\Result::ensure($stmt);
  1374.     }
  1376.     /**
  1377.      * Executes an, optionally parametrized, SQL query and returns the result,
  1378.      * applying a given projection/transformation function on each row of the result.
  1379.      *
  1380.      * @deprecated
  1381.      *
  1382.      * @param string  $sql      The SQL query to execute.
  1383.      * @param mixed[] $params   The parameters, if any.
  1384.      * @param Closure $function The transformation function that is applied on each row.
  1385.      *                           The function receives a single parameter, an array, that
  1386.      *                           represents a row of the result set.
  1387.      *
  1388.      * @return mixed[] The projected result of the query.
  1389.      */
  1390.     public function project($sql, array $params, Closure $function)
  1391.     {
  1392.         Deprecation::trigger(
  1393.             'doctrine/dbal',
  1394.             'https://github.com/doctrine/dbal/pull/3823',
  1395.             'Connection::project() is deprecated without replacement, implement data projections in your own code.'
  1396.         );
  1398.         $result = [];
  1399.         $stmt   = $this->executeQuery($sql, $params);
  1401.         while ($row = $stmt->fetch()) {
  1402.             $result[] = $function($row);
  1403.         }
  1405.         $stmt->closeCursor();
  1407.         return $result;
  1408.     }
  1410.     /**
  1411.      * Executes an SQL statement, returning a result set as a Statement object.
  1412.      *
  1413.      * @deprecated Use {@link executeQuery()} instead.
  1414.      *
  1415.      * @return \Doctrine\DBAL\Driver\Statement
  1416.      *
  1417.      * @throws Exception
  1418.      */
  1419.     public function query()
  1420.     {
  1421.         Deprecation::trigger(
  1422.             'doctrine/dbal',
  1423.             'https://github.com/doctrine/dbal/pull/4163',
  1424.             'Connection::query() is deprecated, use Connection::executeQuery() instead.'
  1425.         );
  1427.         $connection = $this->getWrappedConnection();
  1429.         $args = func_get_args();
  1431.         $logger = $this->_config->getSQLLogger();
  1432.         if ($logger) {
  1433.             $logger->startQuery($args[0]);
  1434.         }
  1436.         try {
  1437.             $statement = $connection->query(...$args);
  1438.         } catch (Throwable $e) {
  1439.             $this->handleExceptionDuringQuery($e, $args[0]);
  1440.         }
  1442.         $statement->setFetchMode($this->defaultFetchMode);
  1444.         if ($logger) {
  1445.             $logger->stopQuery();
  1446.         }
  1448.         return $statement;
  1449.     }
  1451.     /**
  1452.      * Executes an SQL INSERT/UPDATE/DELETE query with the given parameters
  1453.      * and returns the number of affected rows.
  1454.      *
  1455.      * This method supports PDO binding types as well as DBAL mapping types.
  1456.      *
  1457.      * @deprecated Use {@link executeStatement()} instead.
  1458.      *
  1459.      * @param string                                                               $sql    SQL statement
  1460.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  1461.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1462.      *
  1463.      * @return int The number of affected rows.
  1464.      *
  1465.      * @throws Exception
  1466.      */
  1467.     public function executeUpdate($sql, array $params = [], array $types = [])
  1468.     {
  1469.         Deprecation::trigger(
  1470.             'doctrine/dbal',
  1471.             'https://github.com/doctrine/dbal/pull/4163',
  1472.             'Connection::executeUpdate() is deprecated, use Connection::executeStatement() instead.'
  1473.         );
  1475.         return $this->executeStatement($sql, $params, $types);
  1476.     }
  1478.     /**
  1479.      * Executes an SQL statement with the given parameters and returns the number of affected rows.
  1480.      *
  1481.      * Could be used for:
  1482.      *  - DML statements: INSERT, UPDATE, DELETE, etc.
  1483.      *  - DDL statements: CREATE, DROP, ALTER, etc.
  1484.      *  - DCL statements: GRANT, REVOKE, etc.
  1485.      *  - Session control statements: ALTER SESSION, SET, DECLARE, etc.
  1486.      *  - Other statements that don't yield a row set.
  1487.      *
  1488.      * This method supports PDO binding types as well as DBAL mapping types.
  1489.      *
  1490.      * @param string                                                               $sql    SQL statement
  1491.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  1492.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  1493.      *
  1494.      * @return int The number of affected rows.
  1495.      *
  1496.      * @throws Exception
  1497.      */
  1498.     public function executeStatement($sql, array $params = [], array $types = [])
  1499.     {
  1500.         $connection = $this->getWrappedConnection();
  1502.         $logger = $this->_config->getSQLLogger();
  1503.         if ($logger) {
  1504.             $logger->startQuery($sql, $params, $types);
  1505.         }
  1507.         try {
  1508.             if ($params) {
  1509.                 [$sql, $params, $types] = SQLParserUtils::expandListParameters($sql, $params, $types);
  1511.                 $stmt = $connection->prepare($sql);
  1513.                 if ($types) {
  1514.                     $this->_bindTypedValues($stmt, $params, $types);
  1515.                     $stmt->execute();
  1516.                 } else {
  1517.                     $stmt->execute($params);
  1518.                 }
  1520.                 $result = $stmt->rowCount();
  1521.             } else {
  1522.                 $result = $connection->exec($sql);
  1523.             }
  1524.         } catch (Throwable $e) {
  1525.             $this->handleExceptionDuringQuery(
  1526.                 $e,
  1527.                 $sql,
  1528.                 $params,
  1529.                 $types
  1530.             );
  1531.         }
  1533.         if ($logger) {
  1534.             $logger->stopQuery();
  1535.         }
  1537.         return $result;
  1538.     }
  1540.     /**
  1541.      * Executes an SQL statement and return the number of affected rows.
  1542.      *
  1543.      * @deprecated Use {@link executeStatement()} instead.
  1544.      *
  1545.      * @param string $sql
  1546.      *
  1547.      * @return int The number of affected rows.
  1548.      *
  1549.      * @throws Exception
  1550.      */
  1551.     public function exec($sql)
  1552.     {
  1553.         Deprecation::trigger(
  1554.             'doctrine/dbal',
  1555.             'https://github.com/doctrine/dbal/pull/4163',
  1556.             'Connection::exec() is deprecated, use Connection::executeStatement() instead.'
  1557.         );
  1559.         $connection = $this->getWrappedConnection();
  1561.         $logger = $this->_config->getSQLLogger();
  1562.         if ($logger) {
  1563.             $logger->startQuery($sql);
  1564.         }
  1566.         try {
  1567.             $result = $connection->exec($sql);
  1568.         } catch (Throwable $e) {
  1569.             $this->handleExceptionDuringQuery($e, $sql);
  1570.         }
  1572.         if ($logger) {
  1573.             $logger->stopQuery();
  1574.         }
  1576.         return $result;
  1577.     }
  1579.     /**
  1580.      * Returns the current transaction nesting level.
  1581.      *
  1582.      * @return int The nesting level. A value of 0 means there's no active transaction.
  1583.      */
  1584.     public function getTransactionNestingLevel()
  1585.     {
  1586.         return $this->transactionNestingLevel;
  1587.     }
  1589.     /**
  1590.      * Fetches the SQLSTATE associated with the last database operation.
  1591.      *
  1592.      * @deprecated The error information is available via exceptions.
  1593.      *
  1594.      * @return string|null The last error code.
  1595.      */
  1596.     public function errorCode()
  1597.     {
  1598.         Deprecation::trigger(
  1599.             'doctrine/dbal',
  1600.             'https://github.com/doctrine/dbal/pull/3507',
  1601.             'Connection::errorCode() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1602.         );
  1604.         return $this->getWrappedConnection()->errorCode();
  1605.     }
  1607.     /**
  1608.      * {@inheritDoc}
  1609.      *
  1610.      * @deprecated The error information is available via exceptions.
  1611.      */
  1612.     public function errorInfo()
  1613.     {
  1614.         Deprecation::trigger(
  1615.             'doctrine/dbal',
  1616.             'https://github.com/doctrine/dbal/pull/3507',
  1617.             'Connection::errorInfo() is deprecated, use getCode() or getSQLState() on Exception instead.'
  1618.         );
  1620.         return $this->getWrappedConnection()->errorInfo();
  1621.     }
  1623.     /**
  1624.      * Returns the ID of the last inserted row, or the last value from a sequence object,
  1625.      * depending on the underlying driver.
  1626.      *
  1627.      * Note: This method may not return a meaningful or consistent result across different drivers,
  1628.      * because the underlying database may not even support the notion of AUTO_INCREMENT/IDENTITY
  1629.      * columns or sequences.
  1630.      *
  1631.      * @param string|null $name Name of the sequence object from which the ID should be returned.
  1632.      *
  1633.      * @return string A string representation of the last inserted ID.
  1634.      */
  1635.     public function lastInsertId($name = null)
  1636.     {
  1637.         return $this->getWrappedConnection()->lastInsertId($name);
  1638.     }
  1640.     /**
  1641.      * Executes a function in a transaction.
  1642.      *
  1643.      * The function gets passed this Connection instance as an (optional) parameter.
  1644.      *
  1645.      * If an exception occurs during execution of the function or transaction commit,
  1646.      * the transaction is rolled back and the exception re-thrown.
  1647.      *
  1648.      * @param Closure $func The function to execute transactionally.
  1649.      *
  1650.      * @return mixed The value returned by $func
  1651.      *
  1652.      * @throws Throwable
  1653.      */
  1654.     public function transactional(Closure $func)
  1655.     {
  1656.         $this->beginTransaction();
  1657.         try {
  1658.             $res = $func($this);
  1659.             $this->commit();
  1661.             return $res;
  1662.         } catch (Throwable $e) {
  1663.             $this->rollBack();
  1665.             throw $e;
  1666.         }
  1667.     }
  1669.     /**
  1670.      * Sets if nested transactions should use savepoints.
  1671.      *
  1672.      * @param bool $nestTransactionsWithSavepoints
  1673.      *
  1674.      * @return void
  1675.      *
  1676.      * @throws ConnectionException
  1677.      */
  1678.     public function setNestTransactionsWithSavepoints($nestTransactionsWithSavepoints)
  1679.     {
  1680.         if ($this->transactionNestingLevel > 0) {
  1681.             throw ConnectionException::mayNotAlterNestedTransactionWithSavepointsInTransaction();
  1682.         }
  1684.         if (! $this->getDatabasePlatform()->supportsSavepoints()) {
  1685.             throw ConnectionException::savepointsNotSupported();
  1686.         }
  1688.         $this->nestTransactionsWithSavepoints = (bool) $nestTransactionsWithSavepoints;
  1689.     }
  1691.     /**
  1692.      * Gets if nested transactions should use savepoints.
  1693.      *
  1694.      * @return bool
  1695.      */
  1696.     public function getNestTransactionsWithSavepoints()
  1697.     {
  1698.         return $this->nestTransactionsWithSavepoints;
  1699.     }
  1701.     /**
  1702.      * Returns the savepoint name to use for nested transactions are false if they are not supported
  1703.      * "savepointFormat" parameter is not set
  1704.      *
  1705.      * @return mixed A string with the savepoint name or false.
  1706.      */
  1707.     protected function _getNestedTransactionSavePointName()
  1708.     {
  1709.         return 'DOCTRINE2_SAVEPOINT_' . $this->transactionNestingLevel;
  1710.     }
  1712.     /**
  1713.      * {@inheritDoc}
  1714.      */
  1715.     public function beginTransaction()
  1716.     {
  1717.         $connection = $this->getWrappedConnection();
  1719.         ++$this->transactionNestingLevel;
  1721.         $logger = $this->_config->getSQLLogger();
  1723.         if ($this->transactionNestingLevel === 1) {
  1724.             if ($logger) {
  1725.                 $logger->startQuery('"START TRANSACTION"');
  1726.             }
  1728.             $connection->beginTransaction();
  1730.             if ($logger) {
  1731.                 $logger->stopQuery();
  1732.             }
  1733.         } elseif ($this->nestTransactionsWithSavepoints) {
  1734.             if ($logger) {
  1735.                 $logger->startQuery('"SAVEPOINT"');
  1736.             }
  1738.             $this->createSavepoint($this->_getNestedTransactionSavePointName());
  1739.             if ($logger) {
  1740.                 $logger->stopQuery();
  1741.             }
  1742.         }
  1744.         return true;
  1745.     }
  1747.     /**
  1748.      * {@inheritDoc}
  1749.      *
  1750.      * @throws ConnectionException If the commit failed due to no active transaction or
  1751.      *                                            because the transaction was marked for rollback only.
  1752.      */
  1753.     public function commit()
  1754.     {
  1755.         if ($this->transactionNestingLevel === 0) {
  1756.             throw ConnectionException::noActiveTransaction();
  1757.         }
  1759.         if ($this->isRollbackOnly) {
  1760.             throw ConnectionException::commitFailedRollbackOnly();
  1761.         }
  1763.         $result = true;
  1765.         $connection = $this->getWrappedConnection();
  1767.         $logger = $this->_config->getSQLLogger();
  1769.         if ($this->transactionNestingLevel === 1) {
  1770.             if ($logger) {
  1771.                 $logger->startQuery('"COMMIT"');
  1772.             }
  1774.             $result = $connection->commit();
  1776.             if ($logger) {
  1777.                 $logger->stopQuery();
  1778.             }
  1779.         } elseif ($this->nestTransactionsWithSavepoints) {
  1780.             if ($logger) {
  1781.                 $logger->startQuery('"RELEASE SAVEPOINT"');
  1782.             }
  1784.             $this->releaseSavepoint($this->_getNestedTransactionSavePointName());
  1785.             if ($logger) {
  1786.                 $logger->stopQuery();
  1787.             }
  1788.         }
  1790.         --$this->transactionNestingLevel;
  1792.         if ($this->autoCommit !== false || $this->transactionNestingLevel !== 0) {
  1793.             return $result;
  1794.         }
  1796.         $this->beginTransaction();
  1798.         return $result;
  1799.     }
  1801.     /**
  1802.      * Commits all current nesting transactions.
  1803.      */
  1804.     private function commitAll(): void
  1805.     {
  1806.         while ($this->transactionNestingLevel !== 0) {
  1807.             if ($this->autoCommit === false && $this->transactionNestingLevel === 1) {
  1808.                 // When in no auto-commit mode, the last nesting commit immediately starts a new transaction.
  1809.                 // Therefore we need to do the final commit here and then leave to avoid an infinite loop.
  1810.                 $this->commit();
  1812.                 return;
  1813.             }
  1815.             $this->commit();
  1816.         }
  1817.     }
  1819.     /**
  1820.      * Cancels any database changes done during the current transaction.
  1821.      *
  1822.      * @return bool
  1823.      *
  1824.      * @throws ConnectionException If the rollback operation failed.
  1825.      */
  1826.     public function rollBack()
  1827.     {
  1828.         if ($this->transactionNestingLevel === 0) {
  1829.             throw ConnectionException::noActiveTransaction();
  1830.         }
  1832.         $connection = $this->getWrappedConnection();
  1834.         $logger = $this->_config->getSQLLogger();
  1836.         if ($this->transactionNestingLevel === 1) {
  1837.             if ($logger) {
  1838.                 $logger->startQuery('"ROLLBACK"');
  1839.             }
  1841.             $this->transactionNestingLevel = 0;
  1842.             $connection->rollBack();
  1843.             $this->isRollbackOnly = false;
  1844.             if ($logger) {
  1845.                 $logger->stopQuery();
  1846.             }
  1848.             if ($this->autoCommit === false) {
  1849.                 $this->beginTransaction();
  1850.             }
  1851.         } elseif ($this->nestTransactionsWithSavepoints) {
  1852.             if ($logger) {
  1853.                 $logger->startQuery('"ROLLBACK TO SAVEPOINT"');
  1854.             }
  1856.             $this->rollbackSavepoint($this->_getNestedTransactionSavePointName());
  1857.             --$this->transactionNestingLevel;
  1858.             if ($logger) {
  1859.                 $logger->stopQuery();
  1860.             }
  1861.         } else {
  1862.             $this->isRollbackOnly = true;
  1863.             --$this->transactionNestingLevel;
  1864.         }
  1866.         return true;
  1867.     }
  1869.     /**
  1870.      * Creates a new savepoint.
  1871.      *
  1872.      * @param string $savepoint The name of the savepoint to create.
  1873.      *
  1874.      * @return void
  1875.      *
  1876.      * @throws ConnectionException
  1877.      */
  1878.     public function createSavepoint($savepoint)
  1879.     {
  1880.         $platform = $this->getDatabasePlatform();
  1882.         if (! $platform->supportsSavepoints()) {
  1883.             throw ConnectionException::savepointsNotSupported();
  1884.         }
  1886.         $this->getWrappedConnection()->exec($platform->createSavePoint($savepoint));
  1887.     }
  1889.     /**
  1890.      * Releases the given savepoint.
  1891.      *
  1892.      * @param string $savepoint The name of the savepoint to release.
  1893.      *
  1894.      * @return void
  1895.      *
  1896.      * @throws ConnectionException
  1897.      */
  1898.     public function releaseSavepoint($savepoint)
  1899.     {
  1900.         $platform = $this->getDatabasePlatform();
  1902.         if (! $platform->supportsSavepoints()) {
  1903.             throw ConnectionException::savepointsNotSupported();
  1904.         }
  1906.         if (! $platform->supportsReleaseSavepoints()) {
  1907.             return;
  1908.         }
  1910.         $this->getWrappedConnection()->exec($platform->releaseSavePoint($savepoint));
  1911.     }
  1913.     /**
  1914.      * Rolls back to the given savepoint.
  1915.      *
  1916.      * @param string $savepoint The name of the savepoint to rollback to.
  1917.      *
  1918.      * @return void
  1919.      *
  1920.      * @throws ConnectionException
  1921.      */
  1922.     public function rollbackSavepoint($savepoint)
  1923.     {
  1924.         $platform = $this->getDatabasePlatform();
  1926.         if (! $platform->supportsSavepoints()) {
  1927.             throw ConnectionException::savepointsNotSupported();
  1928.         }
  1930.         $this->getWrappedConnection()->exec($platform->rollbackSavePoint($savepoint));
  1931.     }
  1933.     /**
  1934.      * Gets the wrapped driver connection.
  1935.      *
  1936.      * @return DriverConnection
  1937.      */
  1938.     public function getWrappedConnection()
  1939.     {
  1940.         $this->connect();
  1942.         assert($this->_conn !== null);
  1944.         return $this->_conn;
  1945.     }
  1947.     /**
  1948.      * Gets the SchemaManager that can be used to inspect or change the
  1949.      * database schema through the connection.
  1950.      *
  1951.      * @return AbstractSchemaManager
  1952.      */
  1953.     public function getSchemaManager()
  1954.     {
  1955.         if ($this->_schemaManager === null) {
  1956.             $this->_schemaManager = $this->_driver->getSchemaManager($this);
  1957.         }
  1959.         return $this->_schemaManager;
  1960.     }
  1962.     /**
  1963.      * Marks the current transaction so that the only possible
  1964.      * outcome for the transaction to be rolled back.
  1965.      *
  1966.      * @return void
  1967.      *
  1968.      * @throws ConnectionException If no transaction is active.
  1969.      */
  1970.     public function setRollbackOnly()
  1971.     {
  1972.         if ($this->transactionNestingLevel === 0) {
  1973.             throw ConnectionException::noActiveTransaction();
  1974.         }
  1976.         $this->isRollbackOnly = true;
  1977.     }
  1979.     /**
  1980.      * Checks whether the current transaction is marked for rollback only.
  1981.      *
  1982.      * @return bool
  1983.      *
  1984.      * @throws ConnectionException If no transaction is active.
  1985.      */
  1986.     public function isRollbackOnly()
  1987.     {
  1988.         if ($this->transactionNestingLevel === 0) {
  1989.             throw ConnectionException::noActiveTransaction();
  1990.         }
  1992.         return $this->isRollbackOnly;
  1993.     }
  1995.     /**
  1996.      * Converts a given value to its database representation according to the conversion
  1997.      * rules of a specific DBAL mapping type.
  1998.      *
  1999.      * @param mixed  $value The value to convert.
  2000.      * @param string $type  The name of the DBAL mapping type.
  2001.      *
  2002.      * @return mixed The converted value.
  2003.      */
  2004.     public function convertToDatabaseValue($value, $type)
  2005.     {
  2006.         return Type::getType($type)->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2007.     }
  2009.     /**
  2010.      * Converts a given value to its PHP representation according to the conversion
  2011.      * rules of a specific DBAL mapping type.
  2012.      *
  2013.      * @param mixed  $value The value to convert.
  2014.      * @param string $type  The name of the DBAL mapping type.
  2015.      *
  2016.      * @return mixed The converted type.
  2017.      */
  2018.     public function convertToPHPValue($value, $type)
  2019.     {
  2020.         return Type::getType($type)->convertToPHPValue($value, $this->getDatabasePlatform());
  2021.     }
  2023.     /**
  2024.      * Binds a set of parameters, some or all of which are typed with a PDO binding type
  2025.      * or DBAL mapping type, to a given statement.
  2026.      *
  2027.      * @internal Duck-typing used on the $stmt parameter to support driver statements as well as
  2028.      *           raw PDOStatement instances.
  2029.      *
  2030.      * @param \Doctrine\DBAL\Driver\Statement                                      $stmt   Prepared statement
  2031.      * @param array<int, mixed>|array<string, mixed>                               $params Statement parameters
  2032.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  2033.      *
  2034.      * @return void
  2035.      */
  2036.     private function _bindTypedValues($stmt, array $params, array $types)
  2037.     {
  2038.         // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2039.         if (is_int(key($params))) {
  2040.             // Positional parameters
  2041.             $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2042.             $bindIndex  = 1;
  2043.             foreach ($params as $value) {
  2044.                 $typeIndex = $bindIndex + $typeOffset;
  2045.                 if (isset($types[$typeIndex])) {
  2046.                     $type                  = $types[$typeIndex];
  2047.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2048.                     $stmt->bindValue($bindIndex, $value, $bindingType);
  2049.                 } else {
  2050.                     $stmt->bindValue($bindIndex, $value);
  2051.                 }
  2053.                 ++$bindIndex;
  2054.             }
  2055.         } else {
  2056.             // Named parameters
  2057.             foreach ($params as $name => $value) {
  2058.                 if (isset($types[$name])) {
  2059.                     $type                  = $types[$name];
  2060.                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
  2061.                     $stmt->bindValue($name, $value, $bindingType);
  2062.                 } else {
  2063.                     $stmt->bindValue($name, $value);
  2064.                 }
  2065.             }
  2066.         }
  2067.     }
  2069.     /**
  2070.      * Gets the binding type of a given type. The given type can be a PDO or DBAL mapping type.
  2071.      *
  2072.      * @param mixed                $value The value to bind.
  2073.      * @param int|string|Type|null $type  The type to bind (PDO or DBAL).
  2074.      *
  2075.      * @return mixed[] [0] => the (escaped) value, [1] => the binding type.
  2076.      */
  2077.     private function getBindingInfo($value, $type)
  2078.     {
  2079.         if (is_string($type)) {
  2080.             $type = Type::getType($type);
  2081.         }
  2083.         if ($type instanceof Type) {
  2084.             $value       = $type->convertToDatabaseValue($value, $this->getDatabasePlatform());
  2085.             $bindingType = $type->getBindingType();
  2086.         } else {
  2087.             $bindingType = $type;
  2088.         }
  2090.         return [$value, $bindingType];
  2091.     }
  2093.     /**
  2094.      * Resolves the parameters to a format which can be displayed.
  2095.      *
  2096.      * @internal This is a purely internal method. If you rely on this method, you are advised to
  2097.      *           copy/paste the code as this method may change, or be removed without prior notice.
  2098.      *
  2099.      * @param array<int, mixed>|array<string, mixed>                               $params Query parameters
  2100.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types  Parameter types
  2101.      *
  2102.      * @return array<int, int|string|Type|null>|array<string, int|string|Type|null>
  2103.      */
  2104.     public function resolveParams(array $params, array $types)
  2105.     {
  2106.         $resolvedParams = [];
  2108.         // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
  2109.         if (is_int(key($params))) {
  2110.             // Positional parameters
  2111.             $typeOffset = array_key_exists(0, $types) ? -1 : 0;
  2112.             $bindIndex  = 1;
  2113.             foreach ($params as $value) {
  2114.                 $typeIndex = $bindIndex + $typeOffset;
  2115.                 if (isset($types[$typeIndex])) {
  2116.                     $type                       = $types[$typeIndex];
  2117.                     [$value]                    = $this->getBindingInfo($value, $type);
  2118.                     $resolvedParams[$bindIndex] = $value;
  2119.                 } else {
  2120.                     $resolvedParams[$bindIndex] = $value;
  2121.                 }
  2123.                 ++$bindIndex;
  2124.             }
  2125.         } else {
  2126.             // Named parameters
  2127.             foreach ($params as $name => $value) {
  2128.                 if (isset($types[$name])) {
  2129.                     $type                  = $types[$name];
  2130.                     [$value]               = $this->getBindingInfo($value, $type);
  2131.                     $resolvedParams[$name] = $value;
  2132.                 } else {
  2133.                     $resolvedParams[$name] = $value;
  2134.                 }
  2135.             }
  2136.         }
  2138.         return $resolvedParams;
  2139.     }
  2141.     /**
  2142.      * Creates a new instance of a SQL query builder.
  2143.      *
  2144.      * @return QueryBuilder
  2145.      */
  2146.     public function createQueryBuilder()
  2147.     {
  2148.         return new Query\QueryBuilder($this);
  2149.     }
  2151.     /**
  2152.      * Ping the server
  2153.      *
  2154.      * When the server is not available the method returns FALSE.
  2155.      * It is responsibility of the developer to handle this case
  2156.      * and abort the request or reconnect manually:
  2157.      *
  2158.      * @deprecated
  2159.      *
  2160.      * @return bool
  2161.      *
  2162.      * @example
  2163.      *
  2164.      *   if ($conn->ping() === false) {
  2165.      *      $conn->close();
  2166.      *      $conn->connect();
  2167.      *   }
  2168.      *
  2169.      * It is undefined if the underlying driver attempts to reconnect
  2170.      * or disconnect when the connection is not available anymore
  2171.      * as long it returns TRUE when a reconnect succeeded and
  2172.      * FALSE when the connection was dropped.
  2173.      */
  2174.     public function ping()
  2175.     {
  2176.         Deprecation::trigger(
  2177.             'doctrine/dbal',
  2178.             'https://github.com/doctrine/dbal/pull/4119',
  2179.             'Retry and reconnecting lost connections now happens automatically, ping() will be removed in DBAL 3.'
  2180.         );
  2182.         $connection = $this->getWrappedConnection();
  2184.         if ($connection instanceof PingableConnection) {
  2185.             return $connection->ping();
  2186.         }
  2188.         try {
  2189.             $this->query($this->getDatabasePlatform()->getDummySelectSQL());
  2191.             return true;
  2192.         } catch (DBALException $e) {
  2193.             return false;
  2194.         }
  2195.     }
  2197.     /**
  2198.      * @internal
  2199.      *
  2200.      * @param array<int, mixed>|array<string, mixed>                               $params
  2201.      * @param array<int, int|string|Type|null>|array<string, int|string|Type|null> $types
  2202.      *
  2203.      * @throws Exception
  2204.      *
  2205.      * @psalm-return never-return
  2206.      */
  2207.     public function handleExceptionDuringQuery(Throwable $e, string $sql, array $params = [], array $types = []): void
  2208.     {
  2209.         $this->throw(
  2210.             Exception::driverExceptionDuringQuery(
  2211.                 $this->_driver,
  2212.                 $e,
  2213.                 $sql,
  2214.                 $this->resolveParams($params, $types)
  2215.             )
  2216.         );
  2217.     }
  2219.     /**
  2220.      * @internal
  2221.      *
  2222.      * @throws Exception
  2223.      *
  2224.      * @psalm-return never-return
  2225.      */
  2226.     public function handleDriverException(Throwable $e): void
  2227.     {
  2228.         $this->throw(
  2229.             Exception::driverException(
  2230.                 $this->_driver,
  2231.                 $e
  2232.             )
  2233.         );
  2234.     }
  2236.     /**
  2237.      * @internal
  2238.      *
  2239.      * @throws Exception
  2240.      *
  2241.      * @psalm-return never-return
  2242.      */
  2243.     private function throw(Exception $e): void
  2244.     {
  2245.         if ($e instanceof ConnectionLost) {
  2246.             $this->close();
  2247.         }
  2249.         throw $e;
  2250.     }
  2252.     private function ensureHasKeyValue(ResultStatement $stmt): void
  2253.     {
  2254.         $columnCount = $stmt->columnCount();
  2256.         if ($columnCount < 2) {
  2257.             throw NoKeyValue::fromColumnCount($columnCount);
  2258.         }
  2259.     }
  2260. }