Merge pull request #15 from dantleech/qb_reference

Added descendant(), like and textSearch doc section

en/index.rst

@@ -48,6 +48,7 @@ Working with Objects
 
 * **Query Reference**:
   :doc:`Query Builder API <reference/query-builder>`
+  :doc:`The Query Object <reference/query>`
 
 Advanced Topics
 ---------------

en/reference/query-builder.rst

@@ -1,11 +1,10 @@
+.. _qbref:
+
 The QueryBuilder
 ================
 
 The ``QueryBuilder`` provides an API that is designed for
-programmatically constructing an ODM query object.
-
-It provides a set of classes and methods that is able to
-programmatically build queries, and also provides a fluent API.
+programmatically constructing ODM :ref:`query <queryref>` objects.
 
 Creating a query builder instance
 ---------------------------------
@@ -40,7 +39,7 @@ is equal to ``daniel`` and orders the results by ``username`` in ascending order
 .. note::
 
    Unlike the ORM it is not nescessary to specify a source to select from, the above
-   example will **any** document matching the criteria.
+   example will find **any** class of document matching the criteria.
 
 Via a document repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -57,7 +56,9 @@ will automatically select only those records which are associated with the ``Doc
    $posts = $qb->getQuery()->execute();
 
 The above code block will select all documents in the document tree of class ``Post``. This
-feature is especially usefull within a document repository class.
+feature is especially useful within a document repository class.
+
+Example showing the use of the query builder in a ``DocumentRepository``:
 
 .. code-block:: php
 
@@ -354,6 +355,61 @@ than or equal to the given value.
 
     $qb->expr()->lte('number_of_logins', 50);
 
+.. _qbref_expr_like:
+
+like
+~~~~
+
+Specify that the value of the given field name on the candidate document must match 
+the given pattern.  "%" is a wildcard.
+
+.. code-block:: php
+
+    <?php
+
+    $qb->expr()->like('name', 'cAtS'); // case insesitive will match "CATS" and "cats"
+    $qb->expr()->like('name', '%og'); // will match "dog" but not "doggy" 
+    $qb->expr()->like('name', '%og%'); // will match "dog" and "dogs" 
+    $qb->expr()->like('name', 'dog%'); // will match "dog" and "dogs" but not "the dog"
+
+.. _qbref_expr_descendant:
+
+descendant
+~~~~~~~~~~
+
+Specify that candidate documents must be descendants of the ancestor at the given path.
+
+.. code-block:: php
+
+    <?php
+
+    $qb->expr()->descendant('/blog/posts');
+
+textSearch
+~~~~~~~~~~
+
+Perform a text search - perform a full text search on the specified field.
+
+See `the JCR reference <http://docs.jboss.org/jbossdna/0.7/manuals/reference/html/jcr-query-and-search.html#fulltext-search-query-language>`_ for more information about query syntax.
+
+Search on **all** document types where **body** fields are equal to **dog**:
+
+.. code-block:: php
+
+   <?php
+
+   $qb = // new query builder
+   $qb->expr()->textSearch('body', 'dog');
+
+Search on **all** document types where **any** field **contains** the word "computer":
+
+.. code-block:: php
+
+   <?php
+
+   $qb = // new query builder
+   $qb->expr()->textSearch(null, '*computer*');
+
 .. _qbref_phpcrquerybuilder:
 
 The PHPCR QueryBuilder

en/reference/query.rst

@@ -0,0 +1,154 @@
+.. _queryref:
+
+The Query Object
+================
+
+Queries at the ODM layer are encapsulated in the `Query` object. This
+object is generated by the :ref:`QueryBuilder <qbref_workingwiththequerybuilder>`
+and is the object which mediates the transformation of queries to results.
+
+Simple example:
+
+.. code-block:: php
+
+    <?php
+
+    $qb = // create a new query builder instance
+    $qb->where($qb->expr()->eq('foo', 'bar'));
+    $query = $qb->getQuery(); // return a new Query object
+    $results = $query->getResults(); // get the results of the query
+
+Once you have retrieved this class from the query builder it is
+ready to go, you have multiple ways for retrieving your data.
+
+Getting single results
+----------------------
+
+getSingleResult
+~~~~~~~~~~~~~~~
+
+Returns a **single** result using the given :ref:`hydration mode <queryref_hydration>`, if
+no results are found, or if the number of results exceeds one it will throw a ``QueryException``.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\ODM\PHPCR\Query\QueryException;
+
+    $query = // get query
+    $query->setMaxResults(1); // remember we get an exception if there is more than one
+
+    try {
+        // default action is always to return a Document
+        $document = $query->getSingleResult();
+    } catch (QueryException $e)
+        // no result or non unique result
+    }
+
+    // we can specify an alternative hydration mode if we want
+    $node = $query->getSingleResult(Query::HYDRATE_PHPCR)
+
+.. note::
+
+   We should be providing seperate exception types for NoResult and NonUniqueResult
+   respectively. QueryException can also mean "Hydration Mode not implemented"" for example.
+
+getOneOrNullResult
+~~~~~~~~~~~~~~~~~~
+
+Either returns a **single** result or returns ``NULL`` using the 
+given :ref:`hydration mode <queryref_hydration>`
+
+Getting multiple results
+------------------------
+
+.. _queryref_getresult:
+
+getResult
+~~~~~~~~~
+
+Returns **all** results for the query using the given 
+:ref:`hydration mode <queryref_hydration>`.
+
+.. _queryref_getphpcrnoderesult:
+
+getPhpcrNodeResult
+~~~~~~~~~~~~~~~~~~
+
+Returns **all** results for the query in PHPCR node format,
+this method is a proxy for ``getResult(Query::HYDRATE_PHPCR)``.
+
+execute
+~~~~~~~
+
+This method is the base method for all other retrieval methods. It
+is equivalent to the :ref:`getResult <queryref_getresult>` method, but allows you
+to specify an array of parameters as the first argument.
+
+.. code-block:: php
+
+    <?php
+
+    $query = // get new query 
+    $docs = $q->execute();
+
+    // is equivalenet to
+
+    $query = // get new query 
+    $docs = $query->execute(array(), Query::HYDRATE_DOCUMENT);
+
+.. note::
+
+    At time of writing parameters are not yet supported in the ODM.
+
+.. _queryref_hydration:
+
+Hydration modes
+---------------
+
+Currently the ``Query`` object allows you to retrieve data in two formats, raw
+PHPCR nodes and ODM Documents. The later being the default.
+
+The hydration mode is specified by the use of the ``Query::HYDRATE_*`` constants.
+
+.. code-block:: php
+    
+    <?php
+
+    use Doctrine\ODM\PHPCR\Query\Query;
+
+    // HYDRATE_DOCUMENT
+    $document = $query->getSingleResult(Query::HYDRATE_DOCUMENT); // the default mode
+    $document->getSomething();
+
+    // HYDRATE_PHPCR
+    $node = $query->getSingleResult(Query::HYDRATE_PHPCR);
+    $node->getProperty('my_property_name');
+
+.. note::
+
+    In the future we will also enable the retrieval of results in Array format.
+
+.. _queryref_limitingresults:
+
+Limiting results
+----------------
+
+The ``Query`` object allows you to specify the maximum number of results
+that should be retrieved, and also the record index from which the results 
+should be retrieved.
+
+.. code-block:: php
+
+    <?php
+
+    $query = // get query
+    $query->setMaxResults(100);
+    $res = $query->getResult(); // will return a maximum of 100 results
+
+    $query = // get query
+    $query->setOffset(50);
+    $query->setMaxResults(150);
+    $res = $query->getResult(); // will return a maximum of 100 results from result index 50
+