References

Neos 9

This page is for Neos 9.0 with the new Event Sourced Content Repository.

As explained in the chapter Node Relations we support first class references from one Node to another.

#Reading references

Since references are no longer properties of a node but describe the relation between two of them, it is no longer possible to call Node::getProperty for reference properties. Instead, like all graph query operations, references can be resolved via the subgraph. The corresponding methods are

Reference resolution in PHP
$subgraph->findReferences(
    $sourceNodeAggregateId,
    FindReferencesFilter::create()
);
$subgraph->findReferences(
    $sourceNodeAggregateId,
    FindReferencesFilter::create(referenceName: 'someReferenceProperty')
);

, which will return a collection of references from the source node to any target matching the filter, and

Referencing resolution in PHP
$subgraph->findBackReferences(
    $targetNodeAggregateId,
    FindBackReferencesFilter::create()
);
$subgraph->findBackReferences(
    $targetNodeAggregateId,
    FindBackReferencesFilter::create(referenceName: 'someReferenceProperty')
);

, which will return a collection of references to the target node from any source matching the filter.

#Writing references

Simple references without properties can be set like before using the Neos UI. If using the PHP command API, the full feature is already available.

#SetNodeReferences PHP API

With the separation of read and write models in CR version 9+, there is no method in the node class for setting references. This is done via the content repository command API:

Issuing a SetReferences command
$contentRepository->handle(
    SetNodeReferences::create(
        $workspaceName, // the workspace to write to, e.g. live or a user workspace
        $sourceNodeAggregateId, // the ID of the node where the reference is set
        $sourceOriginDimensionSpacePoint, // the origin DSP of the node where the reference is set
		NodeReferencesToWrite::create(
			NodeReferencesForName::fromTargets(
				ReferenceName::fromString($referenceName), // the reference name to use
				NodeAggregateIds::fromArray($destinationNodeAggregateIds) // the IDs of the node the reference is set *to*
			)
		)
    )
)

// with properties use this structure
NodeReferencesToWrite::create(
    NodeReferencesForName::fromReferences(
        ReferenceName::fromString($referenceName),
        [
            NodeReferenceToWrite::fromTargetAndProperties(
                NodeAggregateId::fromString($targetNodeAggregateId),
                PropertyValuesToWrite::fromArray([
                    'myString' => 'text',
                    'myUri' => new Uri('https://neos.io')
                ]) // some properties for the reference
            )
        ]
    )
);

this will result in a reference being created from node$sourceNodeAggregateIdto node$targetNodeAggregateIdwith name$referenceName and properties "myString" of value "text" and "myUri" with value Uri to https://neos.io

Nodes
Content Repository