Association Mapping

Child restriction

You may either specify which classes may be children of a document or that a document is not allowed to have children (i.e. that it is a leaf node).

1
<?php
use Fqn\Article;
use Fqn\Page;

#[Document(childClasses: [Article::class, Page::class])]
class ContentFolder
{
    // ...
}
2
3
4
5
6
7
8
9

1
<doctrine-mapping>
    <document class="ContentFolder">
        <child-class>Fqn\Article</child-class>
        <child-class>Fqn\Page</child-class>
        <!-- ... -->
    </document>
</doctrine-mapping>
2
3
4
5
6
7

1
ContentFolder:
    # ...
    child_classes: [ "Fqn\Article", "Fqn\Page" ]
2
3

To specify that a document can have no children:

1
<?php
#[Document(isLeaf: true)]
class LeafDocument
{
    // ...
}
2
3
4
5
6

1
<doctrine-mapping>
    <document class="LeafDocument" is-leaf="true">
        <!-- ... -->
    </document>
</doctrine-mapping>
2
3
4
5

1
MyPersistentClass:
    # ...
    is_leaf: true
2
3

Referenceable documents

To be allowed to reference a document, it needs to be referenceable. To achieve this, this fact needs to be specified in the Document mapping. Having a referenceable document also allows you to map its uuid to a field.

The Uuid is read only, autogenerated on the first flush of the document. It follows the universally unique id standard and is guaranteed to be unique for the whole PHPCR repository (all workspaces).

1
use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;

#[PHPCR\Document(referenceable: true)]
class MyPersistentClass
{
    #[PHPCR\Uuid]
    private string $uuid;

}
2
3
4
5
6
7
8
9

1
<doctrine-mapping>
    <document class="MyPersistentClass" referenceable="true">
        <uuid fieldName="uuid" />
    </document>
</doctrine-mapping>
2
3
4
5

1
MyPersistentClass:
  referenceable: true
  fields:
    uuid:
      uuid: true
2
3
4
5

Reference other documents

As noted above, the target document needs to be referenceable. Apart from that, there is no limitation on the type of the target document, giving you great flexibility.

There are two mappings, ReferenceOne and ReferenceMany to reference one or several target documents. ReferenceMany is using doctrine/common's collections.

You can specify for each reference if it should ensure referencial integrity or just be a weak reference. By default, a weak reference is created, allowing you to delete the referenced target document. Alternatively you can also tell PHPCR-ODM to reference by path, which is interesting to create references to non-referenceable documents and when using relative paths. A path reference will never ensure referential integrity. (TODO: solve the open issue of how we can make paths relative and document here)

1
use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;
use Doctrine\ODM\PHPCR\ReferenceManyCollection;

#[PHPCR\ReferenceOne(strategy: 'weak')]
private object $weakTarget;

#[PHPCR\ReferenceOne(strategy: 'hard')]
private object $hardTarget;

#[PHPCR\ReferenceOne(strategy: 'path')]
private object $pathTarget;

#[PHPCR\ReferenceMany(strategy: 'weak')]
private ReferenceManyCollection $weakGroup;

#[PHPCR\ReferenceMany(strategy: 'hard')]
private ReferenceManyCollection $hardGroup;

#[PHPCR\ReferenceMany(strategy: 'path')]
private ReferenceManyCollection $pathGroup;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

1
<doctrine-mapping>
    <document class="MyPersistentClass">
        <reference-one fieldName="weakTarget" strategy="weak" />
        <reference-one fieldName="hardTarget" strategy="hard" />
        <reference-one fieldName="pathTarget" strategy="path" />
        <reference-many fieldName="weakGroup" strategy="weak" />
        <reference-many fieldName="hardGroup" strategy="hard" />
        <reference-many fieldName="pathGroup" strategy="path" />
    </document>
</doctrine-mapping>
2
3
4
5
6
7
8
9
10

1
MyPersistentClass:
    referenceOne:
        weakTarget:
          strategy: weak
        hardTarget:
          strategy: hard
        pathTarget:
          strategy: path
    referenceMany:
        weakGroup:
          strategy: weak
        hardGroup:
          strategy: hard
        pathGroup:
          strategy: path
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ReferenceMany documents will always be handled as collections to allow for lazy loading, regardless of the strategy chosen.

All types of reference support the optional argument targetDocument. This can be used to tell what the expected document type for the reference target is. If you only reference documents of one specific type, you can use this as sanity check, additionally path references will be faster this way.

If you do not set the targetDocument, you can reference documents of any type. In ReferenceMany collections, you can even have documents of mixed types.

Referrers to inverse the reference relation

PHPCR-ODM is able to tell which documents reference a specific document, if the hard or weak strategy is used. The Referrers mapping is a collection of documents that have a reference to this document.

In ORM terms, the Reference is the owning side of the association, while the Referrer is the inverse side. Contrary to the ORM, the PHPCR references really are directional, they are always stored in the property of the document with the ReferenceOne or ReferenceMany field. Referrer is a purely virtual information that is not explicitly stored in the PHPCR database but determined at runtime.

You need to specify the referringDocument to specify the (base) class of the document that has the reference, and referencedBy to tell which field of the referencing document contains the reference. After flushing, the reference property will contain the referenced document.

1
use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;
use Doctrine\ODM\PHPCR\ReferrersCollection;

#[PHPCR\Referrers(referringDocument: ClassName::class, referencedBy: 'otherFieldName')]
private ReferrersCollection $specificReferrers;

#[PHPCR\Referrers(referringDocument: OtherClassName::class, referencedBy: 'someFieldName', cascade: 'persist, remove')]
private ReferrersCollection $cascadedReferrers;
2
3
4
5
6
7
8

1
<doctrine-mapping>
    <document class="MyPersistentClass">
        <referrers fieldName="specificReferrers" referring-document="FQN\Class\Name" referenced-by="otherFieldName" />
        <referrers fieldName="cascadedReferrers" referring-document="Other\Class\Name" referenced-by="someFieldName" cascade="persist, remove" />
    </document>
</doctrine-mapping>
2
3
4
5
6

1
MyPersistentClass:
    referrers:
        specificReferrers:
            referringDocument: FQN\Class\Name
            referencedBy: otherFieldName
        cascadedReferrers:
            referringDocument: Other\Class\Name
            referencedBy: someFieldName
            cascade: persist, remove
2
3
4
5
6
7
8
9

Referrers can cascade like the other association mappings to persist or delete their referrers if desired.

MixedReferrers

The mixed referrers is a much simpler but read only mapping to get a collection of all documents that have a reference to this document. The only possible option of mixed referrers is referenceType to limit the referrers to only hard resp. weak references. If left out, you get both types of references.

Mixed referrers can even be mapped on a document that is not referenceable, as you might do it on a base document of which some extending documents are referenceable. An example for this is the Generic document provided by phpcr-odm itself.

1
use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;
use Doctrine\ODM\PHPCR\ReferrersCollection;

#[PHPCR\MixedReferrers]
private ReferrersCollection $allReferrers;

#[PHPCR\MixedReferrers(referenceType: 'hard')]
private ReferrersCollection $hardReferrers;
2
3
4
5
6
7
8

1
<doctrine-mapping>
    <document class="MyPersistentClass">
        <mixed-referrers fieldName="allReferrers" />
        <mixed-referrers fieldName="hardReferrers" reference-type="hard" />
    </document>
</doctrine-mapping>
2
3
4
5
6

1
MyPersistentClass:
    mixedReferrers:
        allReferrers: ~
        hardReferrers:
            referenceType: hard
2
3
4
5

Persistence by Reachability: Cascade Persist

There are additional semantics that apply to the Cascade Persist operation. During each flush() operation Doctrine detects if there are new documents in any collection and three possible cases can happen:

1. New documents in a collection marked as cascade persist will be directly persisted by Doctrine.
2. New documents in a collection not marked as cascade persist will produce an Exception and rollback the flush() operation.
3. Collections without new documents are skipped.

This concept is called "Persistence by Reachability". New documents that are found on already managed documents are automatically persisted as long as the association is defined as cascade persist.

Initializing Collections

You have to be careful when using document fields that contain a collection of related documents. Say we have a User document that contains a collection of groups:

use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;
use Doctrine\ODM\PHPCR\ReferenceManyCollection;

#[PHPCR\Document]
class User
{
    #[PHPCR\ReferenceMany]
    private ReferenceManyCollection $groups;

    public function getGroups(): ReferenceManyCollection
    {
        return $this->groups;
    }
}

With this code alone the $groups field only contains an instance of Doctrine\Common\Collections\Collection if the user is retrieved from Doctrine, however not after you instantiated a fresh instance of the User. When your user document is still new $groups will obviously be null.

This is why we recommend to initialize all collection fields to an empty ArrayCollection in your documents constructor:

use Doctrine\Common\Collections\Collection;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ODM\PHPCR\Mapping\Attributes as PHPCR;

#[PHPCR\Document]
class User
{
    #[PHPCR\ReferenceMany]
    private Collection $groups;

    public function __construct()
    {
        $this->groups = new ArrayCollection();
    }

    public function getGroups(): Collection
    {
        return $this->groups;
    }
}

Now the following code will be working even if the Document hasn't been associated with a DocumentManager yet:

$ group = $documentManager->find(null, $groupId);
$ user = new User();
$ user->getGroups()->add($group);

New Collections after Flushing

On flushing, Doctrine replaces all collection fields (children, reference many, referrers, mixed referrers) that contain plain arrays or ArrayCollection with the appropriate persistent collection class for the field type.

When flushing a new document, their collections are not synchronized with the database, though cascading happens as explained above. The collections thus only show the documents that where explicitly added. If other documents are added directly (e.g. a child with assigned id), you will only see them after calling $dm->refresh(), or in subsequent requests.

On an existing document, setting a field to an array or new collection overwrites all existing documents that previously where in that field, leading to the deletion of the previous documents.