minor #15607 Deprecate getDoctrine() and dispatchMessage() shortcuts (javiereguiluz)

This PR was squashed before being merged into the 5.4 branch.

Discussion
----------

Deprecate getDoctrine() and dispatchMessage() shortcuts

Fixes #15605.

Commits
-------

735a24b Deprecate getDoctrine() and dispatchMessage() shortcuts

Author: javiereguiluz

doctrine.rst

@@ -367,11 +367,9 @@ and save it::
         /**
          * @Route("/product", name="create_product")
          */
-        public function createProduct(): Response
+        public function createProduct(ManagerRegistry $doctrine): Response
         {
-            // you can fetch the EntityManager via $this->getDoctrine()
-            // or you can add an argument to the action: createProduct(EntityManagerInterface $entityManager)
-            $entityManager = $this->getDoctrine()->getManager();
+            $entityManager = $doctrine->getManager();
 
             $product = new Product();
             $product->setName('Keyboard');
@@ -406,7 +404,11 @@ Take a look at the previous example in more detail:
 
 .. _doctrine-entity-manager:
 
-* **line 18** The ``$this->getDoctrine()->getManager()`` method gets Doctrine's
+* **line 14** The ``ManagerRegistry $doctrine`` argument tells Symfony to
+  :ref:`inject the Doctrine service <services-constructor-injection>` into the
+  controller method.
+
+* **line 16** The ``$doctrine->getManager()`` method gets Doctrine's
   *entity manager* object, which is the most important object in Doctrine. It's
   responsible for saving objects to, and fetching objects from, the database.
 
@@ -516,11 +518,9 @@ be able to go to ``/product/1`` to see your new product::
         /**
          * @Route("/product/{id}", name="product_show")
          */
-        public function show(int $id): Response
+        public function show(ManagerRegistry $doctrine, int $id): Response
         {
-            $product = $this->getDoctrine()
-                ->getRepository(Product::class)
-                ->find($id);
+            $product = $doctrine->getRepository(Product::class)->find($id);
 
             if (!$product) {
                 throw $this->createNotFoundException(
@@ -571,7 +571,7 @@ job is to help you fetch entities of a certain class.
 
 Once you have a repository object, you have many helper methods::
 
-    $repository = $this->getDoctrine()->getRepository(Product::class);
+    $repository = $doctrine->getRepository(Product::class);
 
     // look for a single Product by its primary key (usually "id")
     $product = $repository->find($id);
@@ -667,9 +667,9 @@ with any PHP model::
         /**
          * @Route("/product/edit/{id}")
          */
-        public function update(int $id): Response
+        public function update(ManagerRegistry $doctrine, int $id): Response
         {
-            $entityManager = $this->getDoctrine()->getManager();
+            $entityManager = $doctrine->getManager();
             $product = $entityManager->getRepository(Product::class)->find($id);
 
             if (!$product) {
@@ -718,8 +718,7 @@ You've already seen how the repository object allows you to run basic queries
 without any work::
 
     // from inside a controller
-    $repository = $this->getDoctrine()->getRepository(Product::class);
-
+    $repository = $doctrine->getRepository(Product::class);
     $product = $repository->find($id);
 
 But what if you need a more complex query? When you generated your entity with
@@ -786,9 +785,7 @@ Now, you can call this method on the repository::
     // from inside a controller
     $minPrice = 1000;
 
-    $products = $this->getDoctrine()
-        ->getRepository(Product::class)
-        ->findAllGreaterThanPrice($minPrice);
+    $products = $doctrine->getRepository(Product::class)->findAllGreaterThanPrice($minPrice);
 
     // ...
 

doctrine/associations.rst

@@ -320,14 +320,15 @@ Now you can see this new code in action! Imagine you're inside a controller::
     // ...
     use App\Entity\Category;
     use App\Entity\Product;
+    use Doctrine\Persistence\ManagerRegistry;
     use Symfony\Component\HttpFoundation\Response;
 
     class ProductController extends AbstractController
     {
         /**
          * @Route("/product", name="product")
          */
-        public function index(): Response
+        public function index(ManagerRegistry $doctrine): Response
         {
             $category = new Category();
             $category->setName('Computer Peripherals');
@@ -340,7 +341,7 @@ Now you can see this new code in action! Imagine you're inside a controller::
             // relates this product to the category
             $product->setCategory($category);
 
-            $entityManager = $this->getDoctrine()->getManager();
+            $entityManager = $doctrine->getManager();
             $entityManager->persist($category);
             $entityManager->persist($product);
             $entityManager->flush();
@@ -386,12 +387,9 @@ before. First, fetch a ``$product`` object and then access its related
 
     class ProductController extends AbstractController
     {
-        public function show(int $id): Response
+        public function show(ManagerRegistry $doctrine, int $id): Response
         {
-            $product = $this->getDoctrine()
-                ->getRepository(Product::class)
-                ->find($id);
-
+            $product = $doctrine->getRepository(Product::class)->find($id);
             // ...
 
             $categoryName = $product->getCategory()->getName();
@@ -422,11 +420,9 @@ direction::
     // ...
     class ProductController extends AbstractController
     {
-        public function showProducts(int $id): Response
+        public function showProducts(ManagerRegistry $doctrine, int $id): Response
         {
-            $category = $this->getDoctrine()
-                ->getRepository(Category::class)
-                ->find($id);
+            $category = $doctrine->getRepository(Category::class)->find($id);
 
             $products = $category->getProducts();
 
@@ -445,9 +441,7 @@ by adding JOINs.
     a "proxy" object in place of the true object. Look again at the above
     example::
 
-        $product = $this->getDoctrine()
-            ->getRepository(Product::class)
-            ->find($id);
+        $product = $doctrine->getRepository(Product::class)->find($id);
 
         $category = $product->getCategory();
 
@@ -517,11 +511,9 @@ object and its related ``Category`` in one query::
     // ...
     class ProductController extends AbstractController
     {
-        public function show(int $id): Response
+        public function show(ManagerRegistry $doctrine, int $id): Response
         {
-            $product = $this->getDoctrine()
-                ->getRepository(Product::class)
-                ->findOneByIdJoinedToCategory($id);
+            $product = $doctrine->getRepository(Product::class)->findOneByIdJoinedToCategory($id);
 
             $category = $product->getCategory();
 

doctrine/multiple_entity_managers.rst

@@ -232,20 +232,18 @@ the default entity manager (i.e. ``default``) is returned::
 
     // ...
     use Doctrine\ORM\EntityManagerInterface;
+    use Doctrine\Persistence\ManagerRegistry;
 
     class UserController extends AbstractController
     {
-        public function index(EntityManagerInterface $entityManager): Response
+        public function index(ManagerRegistry $doctrine): Response
         {
-            // These methods also return the default entity manager, but it's preferred
-            // to get it by injecting EntityManagerInterface in the action method
-            $entityManager = $this->getDoctrine()->getManager();
-            $entityManager = $this->getDoctrine()->getManager('default');
-            $entityManager = $this->get('doctrine.orm.default_entity_manager');
+            // Both methods return the default entity manager
+            $entityManager = $doctrine->getManager();
+            $entityManager = $doctrine->getManager('default');
 
-            // Both of these return the "customer" entity manager
-            $customerEntityManager = $this->getDoctrine()->getManager('customer');
-            $customerEntityManager = $this->get('doctrine.orm.customer_entity_manager');
+            // This method returns instead the "customer" entity manager
+            $customerEntityManager = $doctrine->getManager('customer');
 
             // ...
         }
@@ -267,29 +265,21 @@ The same applies to repository calls::
 
     use AcmeStoreBundle\Entity\Customer;
     use AcmeStoreBundle\Entity\Product;
+    use Doctrine\Persistence\ManagerRegistry;
     // ...
 
     class UserController extends AbstractController
     {
-        public function index(): Response
+        public function index(ManagerRegistry $doctrine): Response
         {
-            // Retrieves a repository managed by the "default" em
-            $products = $this->getDoctrine()
-                ->getRepository(Product::class)
-                ->findAll()
-            ;
+            // Retrieves a repository managed by the "default" entity manager
+            $products = $doctrine->getRepository(Product::class)->findAll();
 
-            // Explicit way to deal with the "default" em
-            $products = $this->getDoctrine()
-                ->getRepository(Product::class, 'default')
-                ->findAll()
-            ;
+            // Explicit way to deal with the "default" entity manager
+            $products = $doctrine->getRepository(Product::class, 'default')->findAll();
 
-            // Retrieves a repository managed by the "customer" em
-            $customers = $this->getDoctrine()
-                ->getRepository(Customer::class, 'customer')
-                ->findAll()
-            ;
+            // Retrieves a repository managed by the "customer" entity manager
+            $customers = $doctrine->getRepository(Customer::class, 'customer')->findAll();
 
             // ...
         }

forms.rst

@@ -397,10 +397,6 @@ written into the form object::
                 $task = $form->getData();
 
                 // ... perform some action, such as saving the task to the database
-                // for example, if Task is a Doctrine entity, save it!
-                // $entityManager = $this->getDoctrine()->getManager();
-                // $entityManager->persist($task);
-                // $entityManager->flush();
 
                 return $this->redirectToRoute('task_success');
             }

introduction/from_flat_php_to_symfony.rst

@@ -540,24 +540,21 @@ them for you. Here's the same sample application, now built in Symfony::
     namespace App\Controller;
 
     use App\Entity\Post;
+    use Doctrine\Persistence\ManagerRegistry;
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 
     class BlogController extends AbstractController
     {
-        public function list()
+        public function list(ManagerRegistry $doctrine)
         {
-            $posts = $this->getDoctrine()
-                ->getRepository(Post::class)
-                ->findAll();
+            $posts = $doctrine->getRepository(Post::class)->findAll();
 
             return $this->render('blog/list.html.twig', ['posts' => $posts]);
         }
 
-        public function show($id)
+        public function show(ManagerRegistry $doctrine, $id)
         {
-            $post = $this->getDoctrine()
-                ->getRepository(Post::class)
-                ->find($id);
+            $post = $doctrine->getRepository(Post::class)->find($id);
 
             if (!$post) {
                 // cause the 404 page not found to be displayed

messenger.rst

@@ -99,9 +99,6 @@ You're ready! To dispatch the message (and call the handler), inject the
             // will cause the SmsNotificationHandler to be called
             $bus->dispatch(new SmsNotification('Look! I created a message!'));
 
-            // or use the shortcut
-            $this->dispatchMessage(new SmsNotification('Look! I created a message!'));
-
             // ...
         }
     }

reference/configuration/doctrine.rst

@@ -155,13 +155,22 @@ which is the first one defined or the one configured via the
 ``default_connection`` parameter.
 
 Each connection is also accessible via the ``doctrine.dbal.[name]_connection``
-service where ``[name]`` is the name of the connection. In a controller
-extending ``AbstractController``, you can access it directly using the
-``getConnection()`` method and the name of the connection::
-
-    $connection = $this->getDoctrine()->getConnection('customer');
-
-    $result = $connection->fetchAll('SELECT name FROM customer');
+service where ``[name]`` is the name of the connection. In a :doc:`controller </controller>`
+you can access it using the ``getConnection()`` method and the name of the connection::
+
+    // src/Controller/SomeController.php
+    use Doctrine\Persistence\ManagerRegistry;
+
+    class SomeController
+    {
+        public function someMethod(ManagerRegistry $doctrine)
+        {
+            $connection = $doctrine->getConnection('customer');
+            $result = $connection->fetchAll('SELECT name FROM customer');
+
+            // ...
+        }
+    }
 
 Doctrine ORM Configuration
 --------------------------