Deprecate EntityManager::create() (doctrine#9961)

UPGRADE.md

@@ -27,6 +27,13 @@ It will be removed in 3.0. Use one of the dedicated event classes instead:
 
 # Upgrade to 2.13
 
+## Deprecated `EntityManager::create()`
+
+The constructor of `EntityManager` is now public and should be used instead of the `create()` method.
+However, the constructor expects a `Connection` while `create()` accepted an array with connection parameters.
+You can pass that array to DBAL's `Doctrine\DBAL\DriverManager::getConnection()` method to bootstrap the
+connection.
+
 ## Deprecated `QueryBuilder` methods and constants.
 
 1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.

docs/en/cookbook/advanced-field-value-conversion-using-custom-mapping-types.rst

@@ -196,7 +196,7 @@ Example usage
     <?php
 
     // Bootstrapping stuff...
-    // $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config);
+    // $em = new \Doctrine\ORM\EntityManager($connection, $config);
 
     // Setup custom mapping type
     use Doctrine\DBAL\Types\Type;

docs/en/cookbook/dql-user-defined-functions.rst

@@ -46,7 +46,7 @@ configuration:
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
 
-    $em = EntityManager::create($dbParams, $config);
+    $em = new EntityManager($connection, $config);
 
 The ``$name`` is the name the function will be referred to in the
 DQL query. ``$class`` is a string of a class-name which has to
@@ -247,5 +247,3 @@ vendor sql functions and extend the DQL languages scope.
 Code for this Extension to DQL and other Doctrine Extensions can be
 found
 `in the GitHub DoctrineExtensions repository <https://github.com/beberlei/DoctrineExtensions>`_.
-
-

docs/en/cookbook/resolve-target-entity-listener.rst

@@ -127,7 +127,8 @@ the targetEntity resolution will occur reliably:
     // Add the ResolveTargetEntityListener
     $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $rtel);
 
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
+    $connection = \Doctrine\DBAL\DriverManager::createConnection($connectionOptions, $config, $evm);
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);
 
 Final Thoughts
 --------------
@@ -136,5 +137,3 @@ With the ``ResolveTargetEntityListener``, we are able to decouple our
 bundles, keeping them usable by themselves, but still being able to
 define relationships between different objects. By using this method,
 I've found my bundles end up being easier to maintain independently.
-
-

docs/en/cookbook/sql-table-prefixes.rst

@@ -81,6 +81,4 @@ before the prefix has been set.
     $tablePrefix = new \DoctrineExtensions\TablePrefix('prefix_');
     $evm->addEventListener(\Doctrine\ORM\Events::loadClassMetadata, $tablePrefix);
     
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
-
-
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);

docs/en/reference/advanced-configuration.rst

@@ -41,12 +41,12 @@ steps of configuration.
         $config->setAutoGenerateProxyClasses(false);
     }
 
-    $connectionOptions = array(
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
-        'path' => 'database.sqlite'
-    );
+        'path' => 'database.sqlite',
+    ], $config);
 
-    $em = EntityManager::create($connectionOptions, $config);
+    $em = new EntityManager($connection, $config);
 
 Doctrine and Caching
 --------------------
@@ -276,15 +276,13 @@ proxy sets an exclusive file lock which can cause serious
 performance bottlenecks in systems with regular concurrent
 requests.
 
-Connection Options
-------------------
+Connection
+----------
 
-The ``$connectionOptions`` passed as the first argument to
-``EntityManager::create()`` has to be either an array or an
-instance of ``Doctrine\DBAL\Connection``. If an array is passed it
-is directly passed along to the DBAL Factory
-``Doctrine\DBAL\DriverManager::getConnection()``. The DBAL
-configuration is explained in the
+The ``$connection`` passed as the first argument to he constructor of
+``EntityManager`` has to be an instance of ``Doctrine\DBAL\Connection``.
+You can use the factory ``Doctrine\DBAL\DriverManager::getConnection()``
+to create such a connection. The DBAL configuration is explained in the
 `DBAL section <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html>`_.
 
 Proxy Objects

docs/en/reference/configuration.rst

@@ -41,22 +41,24 @@ access point to ORM functionality provided by Doctrine.
     // bootstrap.php
     require_once "vendor/autoload.php";
 
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
     use Doctrine\ORM\ORMSetup;
 
-    $paths = array("/path/to/entity-files");
+    $paths = ['/path/to/entity-files'];
     $isDevMode = false;
 
     // the connection configuration
-    $dbParams = array(
+    $dbParams = [
         'driver'   => 'pdo_mysql',
         'user'     => 'root',
         'password' => '',
         'dbname'   => 'foo',
-    );
+    ];
 
     $config = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
 
@@ -68,18 +70,20 @@ Or if you prefer XML:
 .. code-block:: php
 
     <?php
-    $paths = array("/path/to/xml-mappings");
+    $paths = ['/path/to/xml-mappings'];
     $config = ORMSetup::createXMLMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 Or if you prefer YAML:
 
 .. code-block:: php
 
     <?php
-    $paths = array("/path/to/yml-mappings");
+    $paths = ['/path/to/yml-mappings'];
     $config = ORMSetup::createYAMLMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     If you want to use yml mapping you should add yaml dependency to your `composer.json`:

docs/en/reference/dql-doctrine-query-language.rst

@@ -319,11 +319,11 @@ With Nested Conditions in WHERE Clause:
 
     <?php
     $query = $em->createQuery('SELECT u FROM ForumUser u WHERE (u.username = :name OR u.username = :name2) AND u.id = :id');
-    $query->setParameters(array(
+    $query->setParameters([
         'name' => 'Bob',
         'name2' => 'Alice',
         'id' => 321,
-    ));
+    ]);
     $users = $query->getResult(); // array of ForumUser objects
 
 With COUNT DISTINCT:
@@ -794,7 +794,7 @@ You can register custom DQL functions in your ORM Configuration:
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
 
-    $em = EntityManager::create($dbParams, $config);
+    $em = new EntityManager($connection, $config);
 
 The functions have to return either a string, numeric or datetime
 value depending on the registered function type. As an example we
@@ -806,8 +806,8 @@ classes have to implement the base class :
     <?php
     namespace MyProject\Query\AST;
 
-    use \Doctrine\ORM\Query\AST\Functions\FunctionNode;
-    use \Doctrine\ORM\Query\Lexer;
+    use Doctrine\ORM\Query\AST\Functions\FunctionNode;
+    use Doctrine\ORM\Query\Lexer;
 
     class MysqlFloor extends FunctionNode
     {
@@ -1057,7 +1057,7 @@ the Query class. Here they are:
 
 Instead of using these methods, you can alternatively use the
 general-purpose method
-``Query#execute(array $params = array(), $hydrationMode = Query::HYDRATE_OBJECT)``.
+``Query#execute(array $params = [], $hydrationMode = Query::HYDRATE_OBJECT)``.
 Using this method you can directly supply the hydration mode as the
 second parameter via one of the Query constants. In fact, the
 methods mentioned earlier are just convenient shortcuts for the

docs/en/reference/events.rst

@@ -416,7 +416,7 @@ EventManager that is passed to the EntityManager factory:
     $eventManager->addEventListener([Events::preUpdate], new MyEventListener());
     $eventManager->addEventSubscriber(new MyEventSubscriber());
 
-    $entityManager = EntityManager::create($dbOpts, $config, $eventManager);
+    $entityManager = new EntityManager($connection, $config, $eventManager);
 
 You can also retrieve the event manager instance after the
 EntityManager was created:
@@ -1016,7 +1016,7 @@ Implementing your own resolver:
 
     // Configure the listener resolver only before instantiating the EntityManager
     $configurations->setEntityListenerResolver(new MyEntityListenerResolver);
-    EntityManager::create(.., $configurations, ..);
+    $entityManager = new EntityManager(.., $configurations, ..);
 
 .. _reference-events-load-class-metadata:
 

docs/en/tutorials/getting-started.rst

@@ -136,6 +136,7 @@ step:
 
     <?php
     // bootstrap.php
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
     use Doctrine\ORM\ORMSetup;
 
@@ -160,14 +161,14 @@ step:
     //    isDevMode: true,
     // );
 
-    // database configuration parameters
-    $conn = array(
+    // configuring the database connection
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
         'path' => __DIR__ . '/db.sqlite',
-    );
+    ], $config)
 
     // obtaining the entity manager
-    $entityManager = EntityManager::create($conn, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     The YAML driver is deprecated and will be removed in version 3.0.

lib/Doctrine/ORM/EntityManager.php

@@ -60,8 +60,8 @@
  *     $paths = ['/path/to/entity/mapping/files'];
  *
  *     $config = ORMSetup::createAttributeMetadataConfiguration($paths);
- *     $dbParams = ['driver' => 'pdo_sqlite', 'memory' => true];
- *     $entityManager = EntityManager::create($dbParams, $config);
+ *     $connection = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true], $config);
+ *     $entityManager = new EntityManager($connection, $config);
  *
  * For more information see
  * {@link http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/configuration.html}
@@ -156,15 +156,15 @@ class EntityManager implements EntityManagerInterface
      * Creates a new EntityManager that operates on the given database connection
      * and uses the given Configuration and EventManager implementations.
      */
-    public function __construct(Connection $conn, Configuration $config)
+    public function __construct(Connection $conn, Configuration $config, ?EventManager $eventManager = null)
     {
         if (! $config->getMetadataDriverImpl()) {
             throw MissingMappingDriverImplementation::create();
         }
 
         $this->conn         = $conn;
         $this->config       = $config;
-        $this->eventManager = $conn->getEventManager();
+        $this->eventManager = $eventManager ?? $conn->getEventManager();
 
         $metadataFactoryClassName = $config->getClassMetadataFactoryName();
 
@@ -952,6 +952,8 @@ public function initializeObject($obj)
     /**
      * Factory method to create EntityManager instances.
      *
+     * @deprecated Use {@see DriverManager::getConnection()} to bootstrap the connection and call the constructor.
+     *
      * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
      * @param Configuration      $config       The Configuration instance to use.
      * @param EventManager|null  $eventManager The EventManager instance to use.
@@ -964,6 +966,15 @@ public function initializeObject($obj)
      */
     public static function create($connection, Configuration $config, ?EventManager $eventManager = null)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9961',
+            '%s() is deprecated. To boostrap a DBAL connection, call %s::getConnection() instead. Use the constructor to create an instance of %s.',
+            __METHOD__,
+            DriverManager::class,
+            self::class
+        );
+
         $connection = static::createConnection($connection, $config, $eventManager);
 
         return new EntityManager($connection, $config);
@@ -972,6 +983,8 @@ public static function create($connection, Configuration $config, ?EventManager
     /**
      * Factory method to create Connection instances.
      *
+     * @deprecated Use {@see DriverManager::getConnection()} to bootstrap the connection.
+     *
      * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
      * @param Configuration      $config       The Configuration instance to use.
      * @param EventManager|null  $eventManager The EventManager instance to use.
@@ -984,6 +997,14 @@ public static function create($connection, Configuration $config, ?EventManager
      */
     protected static function createConnection($connection, Configuration $config, ?EventManager $eventManager = null)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9961',
+            '%s() is deprecated, call %s::getConnection() instead.',
+            __METHOD__,
+            DriverManager::class
+        );
+
         if (is_array($connection)) {
             return DriverManager::getConnection($connection, $config, $eventManager ?: new EventManager());
         }

psalm.xml

@@ -77,6 +77,7 @@
                 <referencedMethod name="Doctrine\ORM\Internal\Hydration\AbstractHydrator::hydrateRow"/>
                 <referencedMethod name="Doctrine\ORM\Configuration::ensureProductionSettings"/>
                 <referencedMethod name="Doctrine\ORM\Configuration::newDefaultAnnotationDriver"/>
+                <referencedMethod name="Doctrine\ORM\EntityManager::createConnection"/>
                 <referencedMethod name="Doctrine\ORM\Id\AbstractIdGenerator::generate"/>
                 <referencedMethod name="Doctrine\ORM\ORMInvalidArgumentException::invalidEntityName"/>
                 <referencedMethod name="Doctrine\ORM\ORMSetup::createDefaultAnnotationDriver"/>

tests/Doctrine/Performance/EntityManagerFactory.php

@@ -8,6 +8,7 @@
 use Doctrine\DBAL\Cache\QueryCacheProfile;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver\PDO\SQLite\Driver;
+use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\Result;
 use Doctrine\ORM\Configuration;
 use Doctrine\ORM\EntityManager;
@@ -34,11 +35,11 @@ public static function getEntityManager(array $schemaClassNames): EntityManagerI
             realpath(__DIR__ . '/Models/GeoNames'),
         ]));
 
-        $entityManager = EntityManager::create(
-            [
+        $entityManager = new EntityManager(
+            DriverManager::getConnection([
                 'driverClass' => Driver::class,
                 'memory'      => true,
-            ],
+            ], $config),
             $config
         );
 
@@ -71,6 +72,6 @@ public function executeQuery(string $sql, array $params = [], $types = [], ?Quer
             }
         };
 
-        return EntityManager::create($connection, $config, $connection->getEventManager());
+        return new EntityManager($connection, $config);
     }
 }