Merge pull request #621 from TomHAnderson/doc/editor-5

Doc/editor 5

docs/entity-manager.rst

@@ -3,7 +3,7 @@ Entity Manager
 ==============
 
 The EntityManager is the central access point to ORM functionality. It can be
-used to find, persist, flush and remove entities.
+used to find, persist, remove, and flush entities.
 
 Using the EntityManager
 =======================
@@ -102,7 +102,7 @@ persisted the changes to ``$article`` to the database yet.
 Persisting
 ==========
 
-By passing the entity through the ``$entityManager->persist`` method of the EntityManager,
+By passing the entity through the ``$entityManager->persist()`` method of the EntityManager,
 that entity becomes managed, which means that its persistence is from now
 on managed by an EntityManager. As a result the persistent state of such
 an entity will subsequently be properly synchronised with the database

docs/multiple-connections.rst

@@ -8,16 +8,16 @@ sets of entities. In other words, one entity manager that connects to one
 database will handle some entities while another entity manager that connects
 to another database might handle the rest.
 
-The default manager is configured in ``doctrine.managers``. This one will get
-used when you use the ``EntityManager`` directly. You can add more managers
-to this array.
+The default manager is configured in ``doctrine.managers`` and is
+called ``default``. This one will get used when you use the ``EntityManager``
+directly. You can add more managers to this array.
 
 In your application, you can inject
 ``Doctrine\Common\Persistence\ManagerRegistry``. This holds all entity managers.
-``ManagerRegistry@getManager()`` will return the default manager. By passing
-through the manager name, you will get the connection you want. Alternatively
-you can use ``getManagerForClass($entityName)`` to get a manager which is
-suitable for that entity.
+``$managerRegistry->getManager()`` will return the default manager. By passing
+through the manager name, such as default, you will get the connection you
+want. Alternatively you can use ``getManagerForClass($entityName)`` to get a
+manager which is suitable for that entity.
 
 
 .. role:: raw-html(raw)

docs/repositories.rst

@@ -9,8 +9,7 @@ write collecting logic, build queries, etc.
 
 Repositories are usually modeled as collections to abstract away persistence
 lingo, so it is very common to see methods
-like ``find($id)``, ``findByName("Patrick")``, as if your entities would be in
-a ``Collection`` object instead of a database.
+like ``findByName("Lasso")``, treating the repository as a collection.
 
 Doctrine comes with a generic ``Doctrine\Common\Persistence\ObjectRepository``
 interface that lets you easily find one,
@@ -20,58 +19,56 @@ and an implementation of it in ``Doctrine\ORM\EntityRepository``.
 Getting a repository instance
 =============================
 
-The easiest way to get a repository is to let the EntityManager generate one
+The easiest way to get a repository is to let the EntityManager provide one
 for the Entity you want:
 
 .. code-block:: php
 
-  $repository = EntityManager::getRepository(Scientist::class);
-
-This will generate an instance of the `Doctrine\ORM\EntityRepository`, a
-generic implementation ready to be queried for the class that was given to it.
-
-Injecting repositories
-======================
+.. code-block:: php
 
-You can inject generic repositories by using Laravel's
-`contextual binding <https://laravel.com/docs/container#contextual-binding>`_.
+  use Doctrine\ORM\Mapping as ORM;
+  use Doctrine\Common\Collections\ArrayCollection;
+  use Doctrine\Common\Collections\Collection;
 
-.. code-block:: php
+  #[ORM\Entity(repositoryClass: "App\Doctrine\ORM\Repository\ScientistRepository")]
+  class Scientist
+  {
+      #[ORM\Id]
+      #[ORM\Column(type: "integer")]
+      #[ORM\GeneratedValue(strategy: "AUTO")]
+      private int $id;
 
-  namespace App\Entities\Research;
+      #[ORM\Column(type: "string", nullable: false)]
+      private string $firstName;
 
-  use Doctrine\Common\Persistence\ObjectRepository;
+      #[ORM\Column(type: "string", nullable: false)]
+      private string $lastName;
 
-  class Laboratory
-  {
-      /**
-      * @var ObjectRepository
-      */
-      private $scientists;
+      #[ORM\OneToMany(targetEntity: Theory::class, mappedBy: "scientist")]
+      private Collection $theories;
 
-      public function __construct(ObjectRepository $scientists)
+      public function __construct()
       {
-          $this->scientists = $scientists;
+          $this->theories = new ArrayCollection();
       }
   }
 
-  // Then, in one of your ServiceProviders
-  use App\Entities\Research\Laboratory;
-  use App\Entities\Research\Scientist;
-  use Doctrine\Common\Persistence\ObjectRepository;
+  $repository = EntityManager::getRepository(Scientist::class);
 
-  class AppServiceProvider
-  {
-      public function register()
-      {
-          $this->app
-              ->when(Laboratory::class)
-              ->needs(ObjectRepository::class)
-              ->give(function(){
-                  return EntityManager::getRepository(Scientist::class);
-              });
-      }
-  }
+This will return an instance of the ``App\Doctrine\ORM\Repository\ScientistRepository``.
+For entities that do not have a repositoryClass, an instnace of
+the config ``reposiotry`` repository class is returned.
+
+
+Injecting repositories
+======================
+
+Injecting repositories is **not** recommended.  Inject the entity manager
+instead and always use it as a container for repositories.
+
+The entity manager is both an entity manager and a container similar to
+PSR-11.  Instead of injecting repositories, take a step back and be comfortable
+injecting the container (entity manager).
 
 
 Extending repositories