Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Query Builder docs #14

Merged
merged 3 commits into from Jan 14, 2013

Conversation

Projects
None yet
2 participants
Contributor

dantleech commented Jan 13, 2013

So this is an updated query builder reference, I've kept the original documentation at the bottom under the heading The PHPCR Query Builder.

@dbu dbu commented on an outdated diff Jan 13, 2013

en/reference/query-builder.rst
+is equal to ``daniel`` and orders the results by ``username`` in ascending order.
+
+.. code-block:: php
+
+ <?php
+
+ $qb->where($qb->expr()->eq('name', 'daniel'))
+ ->orderBy('username', 'ASC');
+
+ $query = $qb->getQuery();
+ $users = $query->execute();
+
+.. note::
+
+ Unlike the ORM it is not nescessary to specify a source to select from, the above
+ example will **any** record matching the criteria.
@dbu

dbu Jan 13, 2013

Member

find any document matching the criteria. (or if you want to talk about the db its Node, not record)

@dbu dbu and 1 other commented on an outdated diff Jan 13, 2013

en/reference/query-builder.rst
+
+.. _qbref_select:
+
+Selecting specific properties - select
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+ <?php
+ $qb->select('username');
+ $qb->addSelect('firstname');
+ $qb->addSelect('lastname');
+
+.. note::
+
+ @todo: Not 100% sure how this works atm, I'm guessing it will only hydrate the specified
@dbu

dbu Jan 13, 2013

Member

afaik doing such selects only matters if we hydrate to array. not 100% sure if at the moment we hydrate a document from the result even if you select all needed fields or if we still do a separate query to get the node from phpcr.

@dantleech

dantleech Jan 13, 2013

Contributor

ok. I will test this out and see what happens, and maybe add an Array hydration mode if it is trivial.

@dbu dbu and 1 other commented on an outdated diff Jan 13, 2013

en/reference/query-builder.rst
+.. _qbref_from:
+.. _qbref_nodeType:
+
+Restrict query to document class or node type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can restrict **either** the document class **or** the node type. Attempting to
+specify both will result in an Exception because by setting the document class
+you are implicitly setting the node type.
+
+.. code-block:: php
+
+ <?php
+
+ $qb = $dm->getQueryBuilder();
+ $qb->from('User'); // select only from user documents
@dbu

dbu Jan 13, 2013

Member

i guess this should be a FQN, right? maybe specify a namespaced class to make that clear.

@dbu dbu and 1 other commented on an outdated diff Jan 13, 2013

en/reference/query-builder.rst
+
+.. code-block:: php
+
+ <?php
+
+ $qb = $dm->getQueryBuilder();
+ $qb->from('User'); // select only from user documents
+
+ // or
+
+ $qb = $dm->getQueryBuilder();
+ $qb->nodeType('nt:mynodetype'); // select only documents with node type nt:mynodetype.
+
+ // but not
+
+ $qb = $dm->getQueryBuilder();
@dbu

dbu Jan 13, 2013

Member

why not chain those calls together? its fluent interface, or is it not?

@dantleech

dantleech Jan 13, 2013

Contributor

yeah, it is a fluent interface, but its my habbit to not use fluent interfaces as they are harder to edit, e.g. its easier to comment out or delete a non fluid line and you don't have to worry about indentation and moving semi-colons around. But yeah its probably better to be uniform and advertise the fact that it is a fluent interface. Ill chage that.

@dbu

dbu Jan 13, 2013

Member

imho the right code formatting to use a fluent interface is this:

$query = $dm->getQueryBuilder()
    ->nodeType('nt:mynodetype')
    ->from('User')
    ->getQuery()
;

then you can comment out and add things just as flexible :-)

@dantleech

dantleech Jan 14, 2013

Contributor

That is better, not sure I like the hanging semi-colon though :) Shame there isn't a coding style for this - what do most people do?

@dantleech

dantleech Jan 14, 2013

Contributor

The doctrine docs do it with the semi-colon on the last line, so I'll stick with that for now.

@dbu dbu and 1 other commented on an outdated diff Jan 13, 2013

en/reference/query-builder.rst
+.. code-block:: php
+
+ <?php
+
+ $qb = $dm->createQueryBuilder();
+ $qb->orderBy('username', 'ASC'); // username assending
+
+ $qb = $dm->createQueryBuilder();
+ $qb->orderBy('username', 'DESC'); // username descending
+
+ $qb = $dm->createQueryBuilder();
+ $qb->orderBy('username');
+ $qb->addOrderBy('name'); // username then name ascending (ORDER BY username, name ASC)
+
+ $qb = $dm->createQueryBuilder();
+ $qb->orderBy(array('username', 'name'), 'ASC'); // same as above
@dbu

dbu Jan 13, 2013

Member

the second sorting for username makes it DESC, so this is not the same as above. maybe split the examples, into each block that stands for itselves. it can be a bit confusing like this.

@dantleech

dantleech Jan 13, 2013

Contributor

Yeah, I tried to make it clear by creating a new QB instance for each one, but maybe splitting the code blocks would be better.

Member

dbu commented Jan 13, 2013

thanks, a good documentation, i quite like it. commented a few clarification proposals.

@dantleech dantleech referenced this pull request in doctrine/phpcr-odm Jan 13, 2013

Merged

Query builder odm #204

Contributor

dantleech commented Jan 14, 2013

ok, updated with some minor fixes.

Contributor

dantleech commented Jan 14, 2013

Also I think we are now missing documentation for the new Query object, e.g. it would be good to document the various hydration modes and the ways to get results etc.

The ORM does this in the DQL section, as we don't (yet) have a flavor of DQL - where should this go? Should we put it in this doc and renmae it "Query Reference", or maybe somewhere else?

@dbu dbu commented on the diff Jan 14, 2013

en/reference/query-builder.rst
+.. _qbref_from:
+.. _qbref_nodeType:
+
+Restrict query to document class or node type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can restrict **either** the document class **or** the node type. Attempting to
+specify both will result in an Exception because by setting the document class
+you are implicitly setting the node type.
+
+.. code-block:: php
+
+ <?php
+
+ $dm->getQueryBuilder()
+ ->from('MyVendor/Blog/Document/User'); // select only from user documents
@dbu

dbu Jan 14, 2013

Member

i do like the dangling semicolon in fluent code :-) it avoids diffs on lines that are not affected. same as having a , on the last line of an array if you do one value per line. but i am not religous on this, lets keep with the other doctrine style then.

dbu added a commit that referenced this pull request Jan 14, 2013

@dbu dbu merged commit bcf832a into doctrine:master Jan 14, 2013

Member

dbu commented Jan 14, 2013

thanks for the doc!
regarding hydration modes i suggest to document that in the querybuilder doc for now at the place where it makes sense to explain that. maybe put a .rst comment next to it that this could be moved to the DQL chapter once we have that and we point to that chapter in the querybulder chapter. i just merged as we already merged the code, just start a new PR if you can write something here. maybe a new section before the PHPCR query builder section? and mention it in the introduction that you can also hydrate differently than the default of getting documents.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment