From ae842259f54eabfdc99330d9fb6c7224dfe2659a Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Sun, 17 Mar 2024 12:24:10 +0100 Subject: [PATCH 1/3] [Documentation] Query Result Formats Page: https://www.doctrine-project.org/projects/doctrine-orm/en/2.19/reference/dql-doctrine-query-language.html#query-result-formats Follow-up of https://github.com/doctrine/orm/pull/11359 The table I suggested is probably not working, since the text for each method is too long. And what I really wanted is to make it more *scanable*. So I tried boldfacing - if this doesn't work, I'll try something else. Questions: 1. This section here is basically the same as https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/dql-doctrine-query-language.html#hydration-modes ! So I'll try to merge them (in another PR), OK? I think the list is a better format (more scanable) - since those methods all work the same, there's no need for a full-blown code sample for each, IMO. 2. `getSingleColumnResult()` is missing. --- .../reference/dql-doctrine-query-language.rst | 46 ++++++------------- 1 file changed, 15 insertions(+), 31 deletions(-) diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst index 571190072e3..0e21c0aa0bc 100644 --- a/docs/en/reference/dql-doctrine-query-language.rst +++ b/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,26 +1023,21 @@ 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:: @@ -1050,28 +1045,17 @@ the Query class. Here they are: 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 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 recommended methods in the list are just convenient shortcuts for the hydration mode. Pure and Mixed Results ~~~~~~~~~~~~~~~~~~~~~~ From 4b4b9b7b6fdd01959e187b4ccfca4c7708a63f3a Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Sun, 17 Mar 2024 12:25:05 +0100 Subject: [PATCH 2/3] Adding `NonUniqueResultException` --- docs/en/reference/dql-doctrine-query-language.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst index 0e21c0aa0bc..65ed4d67b02 100644 --- a/docs/en/reference/dql-doctrine-query-language.rst +++ b/docs/en/reference/dql-doctrine-query-language.rst @@ -1050,7 +1050,7 @@ to PHP is determined by the so-called "hydration mode": pure/mixed distinction does not apply. - **``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. In parentheses are the constants of the ``Query`` class which you can use with the From 46d0865339d00bfa02a35f1ce04e2de7f38600f5 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 21 Mar 2024 17:55:39 +0100 Subject: [PATCH 3/3] Update dql-doctrine-query-language.rst --- docs/en/reference/dql-doctrine-query-language.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst index 65ed4d67b02..1cc4c22cec3 100644 --- a/docs/en/reference/dql-doctrine-query-language.rst +++ b/docs/en/reference/dql-doctrine-query-language.rst @@ -1055,7 +1055,7 @@ to PHP is determined by the so-called "hydration mode": 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 recommended methods in the list are just convenient shortcuts for the hydration mode. +In fact, the methods in the list are just convenient shortcuts for the hydration mode. Pure and Mixed Results ~~~~~~~~~~~~~~~~~~~~~~