PHPCR ODM QueryBuilder v2

managed to merge the new query builder.

I developed the original query builder about 9 months ago - it was one of my
first contributions to the PHPCR-ODM doctrine project. It was heavily based on
the ORM query builder and the consensus being that we should make the ODM as
intuitive as possible for existing ORM users.

Abstracting PHPCR to fit the existing interface worked up until a point, we
could implement the basic functionality of the ORM Query Builder exactly,
things started to come undone when we looked at implementing joins.

I had added the joins in the API but didn’t get around to implementing them, the
methods just threw “not implemented” exceptions. Later, when we wanted to
implement them, it wasn’t so simple. Infact, upon closer inspection, many of
the things available in the PHPCR API’s Query Object Model interface were not
covered by the model of the query builder we had chosen, in short, it was not
fit for purpose. I expounded this on the following wiki page:

As detailed in the above linked page, it seemed to me that either we
implemented a 2 part factory heavy query builder or a fluent node based query
builder. The node based design won. However, at the time I never imagined it
would take so long to write! So nearly 2 months later here we are.

Some features of the new query builder

Can fully express the PHPCR QOM (Query Object Model).

Features a fluent interface.

Strict validation and helpful exception messages.

Less verbose than the PHPCR QOM model.

Lets compare a PHPCR QOM query with its new query builder counterpart:

The following two examples are equivalent and both select a blog posts with node
name “My Post Title” having the ODM class “BlogPost”. We order the result set
first by publishing date and then by title.

Whilst the two examples above are equivalent it should be noted that we are
being slightly unfair to the PHPCR QOM as we are forced to add the
phpcr:class constraint, which is a PHPCR-ODMism. Despite this, the new API
is clearly less verbose and, I hope, more intelligible.

As a bonus, the nature of the API also allows us to easily add multiple
constraints to andX and orX operator nodes, something not easily
done with the native PHPCR builder:

<?php$qb->fromDocument('Blog\Post','p');// we can add one or many constraints to an "andX" node...$qb->where()->andX()->fieldIsset('p.username')->gt()->field('p.rank')->literal(50)->end()->eq()->fueld('p.title')->literal('This is a title');

The documentation is now online and is made up of both a guide and a reference: