vendor/doctrine/dbal/src/DriverManager.php line 164

  1. <?php
  3. namespace Doctrine\DBAL;
  5. use Doctrine\Common\EventManager;
  6. use Doctrine\DBAL\Driver\IBMDB2;
  7. use Doctrine\DBAL\Driver\Mysqli;
  8. use Doctrine\DBAL\Driver\OCI8;
  9. use Doctrine\DBAL\Driver\PDO;
  10. use Doctrine\DBAL\Driver\PgSQL;
  11. use Doctrine\DBAL\Driver\SQLite3;
  12. use Doctrine\DBAL\Driver\SQLSrv;
  13. use Doctrine\DBAL\Exception\MalformedDsnException;
  14. use Doctrine\DBAL\Tools\DsnParser;
  15. use Doctrine\Deprecations\Deprecation;
  16. use SensitiveParameter;
  18. use function array_keys;
  19. use function array_merge;
  20. use function is_a;
  22. /**
  23.  * Factory for creating {@see Connection} instances.
  24.  *
  25.  * @psalm-type OverrideParams = array{
  26.  *     application_name?: string,
  27.  *     charset?: string,
  28.  *     dbname?: string,
  29.  *     default_dbname?: string,
  30.  *     driver?: key-of<self::DRIVER_MAP>,
  31.  *     driverClass?: class-string<Driver>,
  32.  *     driverOptions?: array<mixed>,
  33.  *     host?: string,
  34.  *     password?: string,
  35.  *     path?: string,
  36.  *     persistent?: bool,
  37.  *     platform?: Platforms\AbstractPlatform,
  38.  *     port?: int,
  39.  *     serverVersion?: string,
  40.  *     url?: string,
  41.  *     user?: string,
  42.  *     unix_socket?: string,
  43.  * }
  44.  * @psalm-type Params = array{
  45.  *     application_name?: string,
  46.  *     charset?: string,
  47.  *     dbname?: string,
  48.  *     defaultTableOptions?: array<string, mixed>,
  49.  *     default_dbname?: string,
  50.  *     driver?: key-of<self::DRIVER_MAP>,
  51.  *     driverClass?: class-string<Driver>,
  52.  *     driverOptions?: array<mixed>,
  53.  *     host?: string,
  54.  *     keepSlave?: bool,
  55.  *     keepReplica?: bool,
  56.  *     master?: OverrideParams,
  57.  *     memory?: bool,
  58.  *     password?: string,
  59.  *     path?: string,
  60.  *     persistent?: bool,
  61.  *     platform?: Platforms\AbstractPlatform,
  62.  *     port?: int,
  63.  *     primary?: OverrideParams,
  64.  *     replica?: array<OverrideParams>,
  65.  *     serverVersion?: string,
  66.  *     sharding?: array<string,mixed>,
  67.  *     slaves?: array<OverrideParams>,
  68.  *     url?: string,
  69.  *     user?: string,
  70.  *     wrapperClass?: class-string<Connection>,
  71.  *     unix_socket?: string,
  72.  * }
  73.  */
  74. final class DriverManager
  75. {
  76.     /**
  77.      * List of supported drivers and their mappings to the driver classes.
  78.      *
  79.      * To add your own driver use the 'driverClass' parameter to {@see DriverManager::getConnection()}.
  80.      */
  81.     private const DRIVER_MAP = [
  82.         'pdo_mysql'          => PDO\MySQL\Driver::class,
  83.         'pdo_sqlite'         => PDO\SQLite\Driver::class,
  84.         'pdo_pgsql'          => PDO\PgSQL\Driver::class,
  85.         'pdo_oci'            => PDO\OCI\Driver::class,
  86.         'oci8'               => OCI8\Driver::class,
  87.         'ibm_db2'            => IBMDB2\Driver::class,
  88.         'pdo_sqlsrv'         => PDO\SQLSrv\Driver::class,
  89.         'mysqli'             => Mysqli\Driver::class,
  90.         'pgsql'              => PgSQL\Driver::class,
  91.         'sqlsrv'             => SQLSrv\Driver::class,
  92.         'sqlite3'            => SQLite3\Driver::class,
  93.     ];
  95.     /**
  96.      * List of URL schemes from a database URL and their mappings to driver.
  97.      *
  98.      * @deprecated Use actual driver names instead.
  99.      *
  100.      * @var array<string, string>
  101.      * @psalm-var array<string, key-of<self::DRIVER_MAP>>
  102.      */
  103.     private static array $driverSchemeAliases = [
  104.         'db2'        => 'ibm_db2',
  105.         'mssql'      => 'pdo_sqlsrv',
  106.         'mysql'      => 'pdo_mysql',
  107.         'mysql2'     => 'pdo_mysql', // Amazon RDS, for some weird reason
  108.         'postgres'   => 'pdo_pgsql',
  109.         'postgresql' => 'pdo_pgsql',
  110.         'pgsql'      => 'pdo_pgsql',
  111.         'sqlite'     => 'pdo_sqlite',
  112.         'sqlite3'    => 'pdo_sqlite',
  113.     ];
  115.     /**
  116.      * Private constructor. This class cannot be instantiated.
  117.      *
  118.      * @codeCoverageIgnore
  119.      */
  120.     private function __construct()
  121.     {
  122.     }
  124.     /**
  125.      * Creates a connection object based on the specified parameters.
  126.      * This method returns a Doctrine\DBAL\Connection which wraps the underlying
  127.      * driver connection.
  128.      *
  129.      * $params must contain at least one of the following.
  130.      *
  131.      * Either 'driver' with one of the array keys of {@see DRIVER_MAP},
  132.      * OR 'driverClass' that contains the full class name (with namespace) of the
  133.      * driver class to instantiate.
  134.      *
  135.      * Other (optional) parameters:
  136.      *
  137.      * <b>user (string)</b>:
  138.      * The username to use when connecting.
  139.      *
  140.      * <b>password (string)</b>:
  141.      * The password to use when connecting.
  142.      *
  143.      * <b>driverOptions (array)</b>:
  144.      * Any additional driver-specific options for the driver. These are just passed
  145.      * through to the driver.
  146.      *
  147.      * <b>wrapperClass</b>:
  148.      * You may specify a custom wrapper class through the 'wrapperClass'
  149.      * parameter but this class MUST inherit from Doctrine\DBAL\Connection.
  150.      *
  151.      * <b>driverClass</b>:
  152.      * The driver class to use.
  153.      *
  154.      * @param Configuration|null $config       The configuration to use.
  155.      * @param EventManager|null  $eventManager The event manager to use.
  156.      * @psalm-param Params $params
  157.      *
  158.      * @psalm-return ($params is array{wrapperClass: class-string<T>} ? T : Connection)
  159.      *
  160.      * @throws Exception
  161.      *
  162.      * @template T of Connection
  163.      */
  164.     public static function getConnection(
  165.         #[SensitiveParameter]
  166.         array $params,
  167.         ?Configuration $config = null,
  168.         ?EventManager $eventManager = null
  169.     ): Connection {
  170.         // create default config and event manager, if not set
  171.         $config       ??= new Configuration();
  172.         $eventManager ??= new EventManager();
  173.         $params         = self::parseDatabaseUrl($params);
  175.         // URL support for PrimaryReplicaConnection
  176.         if (isset($params['primary'])) {
  177.             $params['primary'] = self::parseDatabaseUrl($params['primary']);
  178.         }
  180.         if (isset($params['replica'])) {
  181.             foreach ($params['replica'] as $key => $replicaParams) {
  182.                 $params['replica'][$key] = self::parseDatabaseUrl($replicaParams);
  183.             }
  184.         }
  186.         $driver = self::createDriver($params['driver'] ?? null, $params['driverClass'] ?? null);
  188.         foreach ($config->getMiddlewares() as $middleware) {
  189.             $driver = $middleware->wrap($driver);
  190.         }
  192.         $wrapperClass = $params['wrapperClass'] ?? Connection::class;
  193.         if (! is_a($wrapperClass, Connection::class, true)) {
  194.             throw Exception::invalidWrapperClass($wrapperClass);
  195.         }
  197.         return new $wrapperClass($params, $driver, $config, $eventManager);
  198.     }
  200.     /**
  201.      * Returns the list of supported drivers.
  202.      *
  203.      * @return string[]
  204.      * @psalm-return list<key-of<self::DRIVER_MAP>>
  205.      */
  206.     public static function getAvailableDrivers(): array
  207.     {
  208.         return array_keys(self::DRIVER_MAP);
  209.     }
  211.     /**
  212.      * @throws Exception
  213.      *
  214.      * @psalm-assert key-of<self::DRIVER_MAP>|null $driver
  215.      * @psalm-assert class-string<Driver>|null     $driverClass
  216.      */
  217.     private static function createDriver(?string $driver, ?string $driverClass): Driver
  218.     {
  219.         if ($driverClass === null) {
  220.             if ($driver === null) {
  221.                 throw Exception::driverRequired();
  222.             }
  224.             if (! isset(self::DRIVER_MAP[$driver])) {
  225.                 throw Exception::unknownDriver($driver, array_keys(self::DRIVER_MAP));
  226.             }
  228.             $driverClass = self::DRIVER_MAP[$driver];
  229.         } elseif (! is_a($driverClass, Driver::class, true)) {
  230.             throw Exception::invalidDriverClass($driverClass);
  231.         }
  233.         return new $driverClass();
  234.     }
  236.     /**
  237.      * Extracts parts from a database URL, if present, and returns an
  238.      * updated list of parameters.
  239.      *
  240.      * @param mixed[] $params The list of parameters.
  241.      * @psalm-param Params $params
  242.      *
  243.      * @return mixed[] A modified list of parameters with info from a database
  244.      *                 URL extracted into indidivual parameter parts.
  245.      * @psalm-return Params
  246.      *
  247.      * @throws Exception
  248.      */
  249.     private static function parseDatabaseUrl(
  250.         #[SensitiveParameter]
  251.         array $params
  252.     ): array {
  253.         if (! isset($params['url'])) {
  254.             return $params;
  255.         }
  257.         Deprecation::trigger(
  258.             'doctrine/dbal',
  259.             'https://github.com/doctrine/dbal/pull/5843',
  260.             'The "url" connection parameter is deprecated. Please use %s to parse a database url before calling %s.',
  261.             DsnParser::class,
  262.             self::class,
  263.         );
  265.         $parser = new DsnParser(self::$driverSchemeAliases);
  266.         try {
  267.             $parsedParams = $parser->parse($params['url']);
  268.         } catch (MalformedDsnException $e) {
  269.             throw new Exception('Malformed parameter "url".', 0, $e);
  270.         }
  272.         if (isset($parsedParams['driver'])) {
  273.             // The requested driver from the URL scheme takes precedence
  274.             // over the default custom driver from the connection parameters (if any).
  275.             unset($params['driverClass']);
  276.         }
  278.         $params = array_merge($params, $parsedParams);
  280.         // If a schemeless connection URL is given, we require a default driver or default custom driver
  281.         // as connection parameter.
  282.         if (! isset($params['driverClass']) && ! isset($params['driver'])) {
  283.             throw Exception::driverRequired($params['url']);
  284.         }
  286.         return $params;
  287.     }
  288. }