updating the rest of the Doctrine docs

Author: weaverryan

doctrine.rst

@@ -23,7 +23,7 @@ code:
 
 .. code-block:: terminal
 
-    composer require orm maker
+    composer require doctrine maker
 
 Configuring the Database
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -36,7 +36,7 @@ The database connection information is stored as an environment variable called
     # .env
 
     # customize this line!
-    DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name?charset=utf8mb4&serverVersion=5.7"
+    DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"
 
     # to use sqlite:
     # DATABASE_URL="sqlite://%kernel.project_dir%/var/app.db"
@@ -48,6 +48,9 @@ database for you:
 
     $ php bin/console doctrine:database:create
 
+There are more optiosn in ``config/packages/doctrine.yaml`` that you can configure,
+including your ``server_version`` (e.g. 5.7 if you're using MySQL 5.7), which may
+affect how Doctrine functions.
 
 .. tip::
 
@@ -75,7 +78,6 @@ You now have a new ``src/Entity/Product.php`` file::
 
     /**
      * @ORM\Entity(repositoryClass="App\Repository\ProductRepository")
-     * @ORM\Table()
      */
     class Product
     {
@@ -140,7 +142,7 @@ in the database. This is usually done with annotations:
 
     .. code-block:: yaml
 
-        # src/Resources/config/doctrine/Product.orm.yml
+        # config/doctrine/Product.orm.yml
         App\Entity\Product:
             type: entity
             id:
@@ -159,7 +161,7 @@ in the database. This is usually done with annotations:
 
     .. code-block:: xml
 
-        <!-- src/Resources/config/doctrine/Product.orm.xml -->
+        <!-- config/doctrine/Product.orm.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -177,14 +179,16 @@ in the database. This is usually done with annotations:
 
 Doctrine supports a wide variety of different field types, each with their own options.
 To see a full list of types and options, see `Doctrine's Mapping Types documentation`_.
+If you want to use ``xml`` instead of annotations, you'll need to configure this in your
+``config/packages/doctrine.yaml`` file.
 
 .. caution::
 
     Be careful not to use reserved SQL keywords as your table or column names
     (e.g. ``GROUP`` or ``USER``). See Doctrine's `Reserved SQL keywords documentation`_
     for details on how to escape these. Or, configure the table name with
-    ``@ORM\Table(name="groups")`` or the column name with the ``name="group_name"``
-    option.
+    ``@ORM\Table(name="groups")`` above the class or configure the column name with
+    the ``name="group_name"`` option.
 
 .. _doctrine-creating-the-database-tables-schema:
 
@@ -423,7 +427,7 @@ be able to go to ``/product/1`` to see your new product::
 
         // or render a template
         // in the template, print things with {{ product.name }}
-        // $this->render('product/show.html.twig', ['product' => $product]);
+        // return $this->render('product/show.html.twig', ['product' => $product]);
     }
 
 Try it out!
@@ -472,7 +476,40 @@ the :ref:`doctrine-queries` section.
 
     If the number of database queries is too high, the icon will turn yellow to
     indicate that something may not be correct. Click on the icon to open the
-    Symfony Profiler and see the exact queries that were executed.
+    Symfony Profiler and see the exact queries that were executed. If you don't
+    see the web debug toolbar, try running ``composer require profiler`` to install
+    it.
+
+Automatically Fetching Objects (ParamConverter)
+-----------------------------------------------
+
+In many cases, you can use the `SensioFrameworkExtraBundle`_ to do the query
+for you automatically! First, install the bundle in case you don't have it:
+
+.. code-block:: terminal
+
+    $ composer require annotations
+
+Now, simplify your controller::
+
+    // src/Controller/ProductController.php
+
+    use App\Entity\Product;
+    // ...
+
+    /**
+     * @Route("/product/{id}", name="product_show")
+     */
+    public function showAction(Product $product)
+    {
+        // use the Product!
+        // ...
+    }
+
+That's it! The bundle uses the ``{id}`` from the route to query for the ``Product``
+by the ``id`` column. If it's not found, a 404 page is generated.
+
+There are many more options you can use. Read more about the `ParamConverter`_.
 
 Updating an Object
 ------------------
@@ -692,14 +729,11 @@ Learn more
 .. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html
 .. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html
 .. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
-.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping
 .. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words
-.. _`Creating Classes for the Database`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#creating-classes-for-the-database
 .. _`DoctrineMongoDBBundle`: https://symfony.com/doc/current/bundles/DoctrineMongoDBBundle/index.html
-.. _`migrations`: https://symfony.com/doc/current/bundles/DoctrineMigrationsBundle/index.html
 .. _`DoctrineFixturesBundle`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
-.. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`newer utf8mb4 character set`: https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
 .. _`Transactions and Concurrency`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/transactions-and-concurrency.html
 .. _`DoctrineMigrationsBundle`: https://github.com/doctrine/DoctrineMigrationsBundle
 .. _`NativeQuery`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/native-sql.html
+.. _`SensioFrameworkExtraBundle`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
+.. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html

doctrine/associations.rst

@@ -290,6 +290,14 @@ about your database, and instead *only* think about your objects. Instead of set
 the category's integer id onto ``Product``, you set the entire ``Category`` *object*.
 Doctrine takes care of the rest when saving.
 
+.. sidebar:: Updating the Relationship from the Inverse Side
+
+    Could you also call ``$category->setProducts()`` to set the relationship? Actually,
+    no! Earlier, you did *not* add a ``setProducts()`` method on ``Category``. That's
+    on purpose: you can *only* set data on the *owning* side of the relationship. In
+    other words, if you call ``$category->setProducts()`` only, that is *completely*
+    ignored when saving. For more details, see: `associations-inverse-side`_.
+
 Fetching Related Objects
 ------------------------
 
@@ -330,24 +338,21 @@ the category (i.e. it's "lazily loaded").
 Because we mapped the optiona ``OneToMany`` side, you can also query in the other
 direction::
 
-    public function showProductsAction($categoryId)
+    public function showProductsAction($id)
     {
         $category = $this->getDoctrine()
             ->getRepository(Category::class)
-            ->find($categoryId);
+            ->find($id);
 
         $products = $category->getProducts();
 
         // ...
     }
 
-TODO TODO, STARTING HERE!!!!!!!!!!!!!!!!!!
-
-In this case, the same things occur: you first query out for a single ``Category``
-object, and then Doctrine makes a second query to retrieve the related ``Product``
-objects, but only once/if you ask for them (i.e. when you call ``getProducts()``).
-The ``$products`` variable is an array of all ``Product`` objects that relate
-to the given ``Category`` object via their ``category_id`` value.
+In this case, the same things occur: you first query for a single ``Category``
+object. Then, only when (and if) you access the products, Doctrine makes a second
+query to retrieve the related ``Product`` objects. This extra query can be avoided
+by adding JOINs.
 
 .. sidebar:: Relationships and Proxy Classes
 
@@ -357,7 +362,7 @@ to the given ``Category`` object via their ``category_id`` value.
 
         $product = $this->getDoctrine()
             ->getRepository(Product::class)
-            ->find($productId);
+            ->find($id);
 
         $category = $product->getCategory();
 
@@ -371,8 +376,8 @@ to the given ``Category`` object via their ``category_id`` value.
     actually need that data (e.g. until you call ``$category->getName()``).
 
     The proxy classes are generated by Doctrine and stored in the cache directory.
-    And though you'll probably never even notice that your ``$category``
-    object is actually a proxy object, it's important to keep it in mind.
+    You'll probably never even notice that your ``$category`` object is actually
+    a proxy object.
 
     In the next section, when you retrieve the product and category data
     all at once (via a *join*), Doctrine will return the *true* ``Category``
@@ -381,7 +386,7 @@ to the given ``Category`` object via their ``category_id`` value.
 Joining Related Records
 -----------------------
 
-In the above examples, two queries were made - one for the original object
+In the examples above, two queries were made - one for the original object
 (e.g. a ``Category``) and one for the related object(s) (e.g. the ``Product``
 objects).
 
@@ -397,34 +402,129 @@ following method to the ``ProductRepository`` class::
     // src/Repository/ProductRepository.php
     public function findOneByIdJoinedToCategory($productId)
     {
-        $query = $this->getEntityManager()
-            ->createQuery(
-            'SELECT p, c FROM App:Product p
-            JOIN p.category c
-            WHERE p.id = :id'
-        )->setParameter('id', $productId);
-
-        try {
-            return $query->getSingleResult();
-        } catch (\Doctrine\ORM\NoResultException $e) {
-            return null;
-        }
+        return $this->createQueryBuilder('p')
+            // p.category refers to the "category" property on product
+            ->innerJoin('p.category', 'c')
+            // selects all the category data to avoid the query
+            ->addSelect('c')
+            ->andWhere('p.id = :id')
+            ->setParameter('id', $productId)
+            ->getQuery()
+            ->getOneOrNullResult();
     }
 
+This will *still* return an array of ``Product`` objects. But now, when you call
+``$product->getCategory()`` and use that data, no second query is made.
+
 Now, you can use this method in your controller to query for a ``Product``
 object and its related ``Category`` with just one query::
 
-    public function showAction($productId)
+    public function showAction($id)
     {
         $product = $this->getDoctrine()
             ->getRepository(Product::class)
-            ->findOneByIdJoinedToCategory($productId);
+            ->findOneByIdJoinedToCategory($id);
 
         $category = $product->getCategory();
 
         // ...
     }
 
+.. _associations-inverse-side:
+
+Setting Information from the Inverse Side
+-----------------------------------------
+
+So far, you've updated the relationship by calling ``$product->setCategory($category)``.
+This is no accident: you *must* set the relationship on the *owning* side. The owning
+side is always where the ``ManyToOne`` mapping is set (for a ``ManyToMany`` relation,
+you can choose which side is the owning side).
+
+Does this means it's not possible to call ``$category->setProducts()``? Actually,
+it *is* possible, by writing clever methods. First, instead of a ``setProducts()``
+method, create a ``addProduct()`` method::
+
+    // src/Entity/Category.php
+    
+    // ...
+    class Category
+    {
+        // ...
+
+        public function addProduct(Product $product)
+        {
+            if ($this->products->contains($product)) {
+                return;
+            }
+
+            $this->products[] = $product;
+            // set the *owning* side!
+            $product->setCategory($this);
+        }
+    }
+
+That's it! The *key* is ``$product->setCategory($this)``, which sets the *owning*
+side. Now, when you save, the relationship *will* update in the database.
+
+What about *removing* a ``Product`` from a ``Category``? Add a ``removeProduct()``
+method::
+
+    // src/Entity/Category.php
+    
+    // ...
+    class Category
+    {
+        // ...
+
+        public function removeProduct(Product $product)
+        {
+            $this->products->removeElement($product);
+            // set the owning side to null
+            $product->setCategory(null);
+        }
+    }
+
+To make this work, you *now* need to allow ``null`` to be passed to ``Product::setCategory()``:
+
+.. code-block:: diff
+
+    // src/Entity/Product.php
+
+    // ...
+    class Product
+    {
+        // ...
+
+        - public function getCategory(): Category
+        + public function getCategory(): ?Category
+        // ...
+
+        - public function setCategory(Category $category)
+        + public function setCategory(Category $category = null)
+        {
+            $this->category = $category;
+        }
+    }
+
+And that's it! Now, if you call ``$category->removeProduct($product)``, the ``category_id``
+on that ``Product`` will be set to ``null`` in the database.
+
+But, instead of setting the ``category_id`` to null, what if you want the ``Product``
+to be *deleted* if it becomes "orphaned" (i.e. without a ``Category``)? To choose
+that behavior, use the `orphanRemoval`_ option inside ``Category``::
+
+    // src/Entity/Category.php
+    
+    // ...
+
+    /**
+     * @ORM\OneToMany(targetEntity="App\Entity\Product", mappedBy="category", orphanRemoval=true)
+     */
+    private $products;
+
+Thanks to this, if the ``Product`` is removed from the ``Category``, it will be
+removed from the database entirely.
+
 More Information on Associations
 --------------------------------
 
@@ -437,7 +537,7 @@ Doctrine's `Association Mapping Documentation`_.
 
     If you're using annotations, you'll need to prepend all annotations with
     ``@ORM\`` (e.g. ``@ORM\OneToMany``), which is not reflected in Doctrine's
-    documentation. You'll also need to include the ``use Doctrine\ORM\Mapping as ORM;``
-    statement, which *imports* the ``ORM`` annotations prefix.
+    documentation.
 
 .. _`Association Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/association-mapping.html
+.. _`orphanRemoval`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/working-with-associations.html#orphan-removal

doctrine/custom_dql_functions.rst

@@ -13,7 +13,7 @@ In Symfony, you can register your custom DQL functions as follows:
 
     .. code-block:: yaml
 
-        # app/config/config.yml
+        # config/packages/doctrine.yaml
         doctrine:
             orm:
                 # ...
@@ -28,7 +28,7 @@ In Symfony, you can register your custom DQL functions as follows:
 
     .. code-block:: xml
 
-        <!-- app/config/config.xml -->
+        <!-- config/packages/doctrine.xml -->
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
@@ -52,7 +52,7 @@ In Symfony, you can register your custom DQL functions as follows:
 
     .. code-block:: php
 
-        // app/config/config.php
+        // config/packages/doctrine.php
         use App\DQL\StringFunction;
         use App\DQL\SecondStringFunction;
         use App\DQL\NumericFunction;