Discussion Neos's Helper / High level API for the new CR

mhsdesign commented 1 month ago

To ease interaction with the CR from the Neos CMS we should discuss a few higher level API ideas.

Neos' Workspace

The Publishing bonanza introduced a new high level Neos Workspace Model that can be used to publish or discard pending changes.

Todos:

[ ] It encapsulates (partially) the quirks of the removalAttachmentPoint, though that should be further encapsulated from the Ui as well

I agree there should be a high-level API in Neos.Neos for this as well. In fact I think that all node operations should pass a Neos.Neos layer instead of the UI communicating with the CR directly.

Neos.Neos is the place where the distinction between sites, documents and contents can be established semantically (which is the underlying problem addressed by removalAttachmentPoint). So, this is where commands like RemoveDocument or RemoveContent can reasonably exist without violating the boundaries of the content repository. (Not saying that those exact commands should actually exist - only that Neos.Neos is allowed to speak of "Documents" and "Contents" where the CR is not)

Such logic exists in Neos.Neos.Ui at the moment, but more as a band-aid.

[ ] Add WorkspaceProvider::provideForUser($contentRepositoryId, $user);, currently we use different logic at different places to fetch (or create) the user workspace. This should be abstracted.
[ ] Possibly add Workspace::getSubgraph($dsp, $visibility): ContentSubgraphInterface;

SubgraphThing

Idea copied from https://github.com/neos/neos-development-collection/pull/4943#issuecomment-2024851775

We always had this higher level API in mind when we thought about replacing the communication from Neos UI to the backend with a cleaner API. But I can totally see that this already makes sense now. And I agree that it should not be limited to workspace publishing, looking at the hoops we currently have to jump just to get hold of the Subgraph, e.g. in the UI BackendController, our quirky change classes and in Neos itself.

So to elaborate on the Neos' Workspace idea, I could imagine some central authority (built from request, from a node instance or by specifying all required parameters explicitly) that returns two different models:

one that is bound to a contentRepositoryId and a workspaceName that allows to issue workspace related higher-level commands (like the ones you mentioned above) and maybe ways to retrieve information about this workspace (pending changes, ...)
- -> this was implemented as Neos' Workspace Model
one that is bound to a contentRepositoryId, a workspaceName, a dimensionSpacePoint and visibilityConstraints that can be used to apply/query changes in a single subgraph

Those two models basically reflect what we currently have in the Neos Backend already:

To publish a workspace instead of

$cr->handle(new PublishWorkspace($workspaceName, $newContentStreamId));

it could be sth like

$workspaceThingy->publish();

And to set properties on the "subgraph-bound model", instead of

$cr->handle(new SetNodeProperties($workspaceName, $nodeId, $originDimensionSpacePoint, $propertyValues)

the higher-level API could look something like this

$subgraphThingy->handle(new SetNodeProperties($nodeId, $propertyValues));

..or maybe even

$subgraphThingy->setNodeProperties($nodeId, $propertyValues);

`ContentRepository::subgraphForNode` or `subgraphFor(ContentSubgraphIdentity)`

copied from https://github.com/neos/neos-development-collection/pull/5047

Seeing code like this

$subgraph = $this->contentRepositoryRegistry->subgraphForNode($node);
$nodeTypeManager = $this->contentRepositoryRegistry->get($node->contentRepositoryId)->getNodeTypeManager();

this seems just double because the contentRepository is fetched twice and not passed

$subgraph = $this->contentRepositoryRegistry->subgraphForNode($node);
$contentRepository = $this->contentRepositoryRegistry->get($node->contentRepositoryId);
$contentRepository-> ...

makes me rethink if were not going to far with contentRepositoryRegistry->subgraphForNode, id like to fetch the cr more often in code directly and then get the subgraph:

$contentRepository = $this->contentRepositoryRegistry->get($node->contentRepositoryId);
$subgraph = $contentRepository->subgraphForNode($node);
$nodeTypeManager = $contentRepository->getNodeTypeManager();

We decided against a ContentSubgraphIdentity and an attached NodeAddress on the node and preferred first level values. That prevents us from having to do anything with the objects in total as each time we would pass them to a content repository it would need to validate that the correct cr is used which is hard to statically lint and just shows a flaw and is not even that helpful as one needs to ask the cr registry or some other thing always first as well. Maybe if we decide to have a CrRegistryInterface it will be worth to reconsider it but not for now.

mhsdesign commented 2 weeks ago

regarding other things users currently do (see some parts of https://github.com/neos/rector/issues/68) we might have to introduce tooling.

For example to fetch the site node by site entity could deserve Site->getRootNode() but currently looks rather complicated.
...

kitsunet commented 1 week ago

Doing a lot of reading with the API in different places I realize the SubgraphIdentity was good for endusers. Right now I sometimes just need to pass around where from something needs to be fetched, not necessarily a full "NodeAddress", so it's a bit of a PITA to use the separate parts. IMHO the [crId, dimensionspacepoint, workspace] triplet at least should be something

neos / neos-development-collection