Merge pull request #11372 from ThomasLandauer/patch-12

[Documentation] Query Result Formats

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

@@ -1003,7 +1003,7 @@ The Query class
 ---------------
 
 An instance of the ``Doctrine\ORM\Query`` class represents a DQL
-query. You create a Query instance be calling
+query. You create a Query instance by calling
 ``EntityManager#createQuery($dql)``, passing the DQL query string.
 Alternatively you can create an empty ``Query`` instance and invoke
 ``Query#setDQL($dql)`` afterwards. Here are some examples:
@@ -1023,55 +1023,39 @@ Alternatively you can create an empty ``Query`` instance and invoke
 Query Result Formats
 ~~~~~~~~~~~~~~~~~~~~
 
-The format in which the result of a DQL SELECT query is returned
-can be influenced by a so-called ``hydration mode``. A hydration
-mode specifies a particular way in which a SQL result set is
-transformed. Each hydration mode has its own dedicated method on
-the Query class. Here they are:
+The way in which the SQL result set of a DQL SELECT query is transformed
+to PHP is determined by the so-called "hydration mode":
 
-
--  ``Query#getResult()``: Retrieves a collection of objects. The
+-  **``getResult()``** (``HYDRATE_OBJECT``): Retrieves a collection of objects. The
    result is either a plain collection of objects (pure) or an array
    where the objects are nested in the result rows (mixed).
--  ``Query#getSingleResult()``: Retrieves a single object. If the
-   result contains more than one object, an ``NonUniqueResultException``
-   is thrown. If the result contains no objects, an ``NoResultException``
+-  **``getSingleResult()``**: Retrieves a single object. If the
+   result contains more than one object, a ``NonUniqueResultException``
+   is thrown. If the result contains no objects, a ``NoResultException``
    is thrown. The pure/mixed distinction does not apply.
--  ``Query#getOneOrNullResult()``: Retrieve a single object. If the
+-  **``getOneOrNullResult()``**: Retrieve a single object. If the
    result contains more than one object, a ``NonUniqueResultException``
    is thrown. If no object is found null will be returned.
--  ``Query#getArrayResult()``: Retrieves an array graph (a nested
-   array) that is largely interchangeable with the object graph
-   generated by ``Query#getResult()`` for read-only purposes.
+-  **``getArrayResult()``** (``HYDRATE_ARRAY``): Retrieves an array graph (a nested
+   array) for read-only purposes.
 
     .. note::
 
         An array graph can differ from the corresponding object
         graph in certain scenarios due to the difference of the identity
         semantics between arrays and objects.
 
-
-
--  ``Query#getScalarResult()``: Retrieves a flat/rectangular result
+-  **``getScalarResult()``** (``HYDRATE_SCALAR``): Retrieves a flat/rectangular result
    set of scalar values that can contain duplicate data. The
    pure/mixed distinction does not apply.
--  ``Query#getSingleScalarResult()``: Retrieves a single scalar
+-  **``getSingleScalarResult()``** (``HYDRATE_SINGLE_SCALAR``: Retrieves a single scalar
    value from the result returned by the dbms. If the result contains
-   more than a single scalar value, an exception is thrown. The
+   more than a single scalar value, a ``NonUniqueResultException`` is thrown. The
    pure/mixed distinction does not apply.
 
-Instead of using these methods, you can alternatively use the
-general-purpose method
-``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
-execute method. For example, the method ``Query#getResult()``
-internally invokes execute, passing in ``Query::HYDRATE_OBJECT`` as
-the hydration mode.
-
-The use of the methods mentioned earlier is generally preferred as
-it leads to more concise code.
+In parentheses are the constants of the ``Query`` class which you can use with the
+general-purpose method ``Query::execute(array $params = [], $hydrationMode = Query::HYDRATE_OBJECT)``.
+In fact, the methods in the list are just convenient shortcuts for the hydration mode.
 
 Pure and Mixed Results
 ~~~~~~~~~~~~~~~~~~~~~~