References and related

Proxies

The doctrine ORM and the mongodb ODM use Proxy classes for referenced documents. Those classes store the ID of the document and fetch the document from the data store whenever a public method on the object is invoked.

PHPCR-ODM can use the same mechanism. Instead of storing the uuid or the path the proxy can store the phpcr node. If the object is accessed it is initialized from the node's properties. That way it will be fairly safe to annotate the document with annotations that reference other nodes, @Child, @Children, @Parent, @ReferenceOne, @ReferenceMany and @Referers without pulling the whole tree from the content repository.

Proxy creation

To create the proxy classes Doctrine ORM and Mongodb ODM use a Symfony console command. This adds a dependency on the Console component. Having the console would allow for other commands as well like loading fixtures, checking the setup etc.

Parent

A @Parent annotation can be used to access the parent of the annotated node. A use case for this could be a menu item that needs a list of its siblings ... As discussed in other places, a move should be its own operation. Therefore @Parent should be immutable. Although it could be used to place new nodes in the tree (this generally needs discussion: how do we populate the tree ...).

Children

As discussed on the list there will be a @Children annotation that could be filtered on names of the children like PHPCR Node::getNodes does. A Document can have several @Children annotation to access different subsets of its children. For a start these collections should be immutable and should contain only children not descendants of the node. Since PHPCR Node::getNodes returns an Iterator we might write an IteratorCollection wrapper that implements Doctrine Collection (see http://www.doctrine-project.org/api/common/2.0/doctrine/common/collections/collection.html).

The @Child annotation can be used to assign and read a single child. Currently the name of the child is defined by the annotation but this should be more flexible. E.g. the parent can have a property that contains the name of the child.

References

PHPCR already implements references through the property types REFERENCE and WEAKREFERENCE. @ReferenceOne is a single valued property of either type REFERENCE or WEAKREFERENCE. @ReferenceMany is a similar multivalued property. The reference annotations have an attribute

$weak = true

which denotes the type of the reference, weak or not. Weak is the default. ReferenceMany is implemented as a Doctrine ArrayCollection. Since we can directly get the nodes from the properties, again proxies can be used.

Referrer

Every referenced node in PHPCR can produce a list of the nodes that reference the node through the getReferences and getWeakReferences methods. This can be implemented as a immutable (to keep things simple for a start) collection. A use case could be a list of all usages of an asset e.g. an image in an asset library or a list of all menu items that reference a content node (e.g. for highlighting the current menu item). Again there could be a flag that allows to get either the weak referrers, the (strong) referrers or all. NOTE: The getReferences() is not yet implemented in jackalope. It should not be too hard, but some work has to be invested.

Referencable Documents

To be on the save side referencable nodes should declare this in the @Document so that we can add the proper mixin at node creation. For this a new attribute

$referencable = false

is introduced.