The Query Object

Queries at the ODM layer are encapsulated in the Query object. This object is generated by the QueryBuilder and is the object which mediates the transformation of queries to results.

Build a query with the query builder and execute it:

$ qb = // create a new query builder instance
$ qb->where($qb->expr()->eq('foo', 'bar'));
$ query = $qb->getQuery(); // return a new Query object
$ results = $query->getResult(); // 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 hydration mode, if no results are found, or if the number of results exceeds one it will throw a QueryException:

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)

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 hydration mode

Getting multiple results

getResult

Returns all results for the query using the given hydration mode.

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 getResult method, but allows you to specify an array of parameters as the first argument:

$ query = // get new query
$ docs = $q->execute();

// is equivalenet to

$ query = // get new query
$ docs = $query->execute([], Query::HYDRATE_DOCUMENT);

At time of writing parameters are not yet supported in the ODM.

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:

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');

In the future we will also enable the retrieval of results in Array format.

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:

$ 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

Maintained

Unmaintained