Site Configuration [v9]

Neos 9.x Content

This is content for the upcoming Neos 9.0 release with the rewritten Content Repository based on Event Sourcing.

We heavily work on these docs right now, so expect rough edges.

#Site Configuration in Settings.yaml

Starting with Neos 9, site-specific configuration has been introduced in Settings.yaml, underneath the key Neos.Neos.sites.

You can either specify configuration for a certain site node name, or you can specify a fallback configuration using the special key *.

The custom configuration is not merged with the fallback: If you create custom configuration for a site, you need to specify it completely or use presets (see below).

Let's look at an example:

Neos:
  Neos:
    sites:
      'docsneosio':
        contentRepository: docs
        contentDimensions:
          resolver:
            factoryClassName: Neos\Neos\FrontendRouting\DimensionResolution\Resolver\UriPathResolverFactory
            options:
              # separator between different dimensions, default "-"
              separator: '-'
              segments:
				- dimensionIdentifier: language
                  dimensionValueMapping:
                    en_US: ''
                    de: 'de'

For the site with the site node name docsneosio, explicit configuration is used, specifying the dimension routing configuration, and a separate content repository (which must be created in Neos.ContentRepositoryRegistry.contentRepositories.docs - as explained on Content Repository Configuration).

For all other sites, the default ContentRepository is used.

#Site configuration presets

In order to prevent duplication when configuring multiple similar sites, presets can be defined underneath Neos.Neos.sitePresets

Neos comes with a predefined default preset that is used by the * fallback:

Neos:
  Neos:
    sitePresets:
      'default':
        uriPathSuffix: '.html'
        contentRepository: default
        contentDimensions:
          resolver:
            factoryClassName: Neos\Neos\FrontendRouting\DimensionResolution\Resolver\AutoUriPathResolverFactory
    sites:
      '*':
        preset: 'default'

configuration from the site preset is merged and can be overridden:

Neos:
  Neos:
    sitePresets:
      'default':
        uriPathSuffix: '.html'
        contentRepository: default
        contentDimensions:
          resolver:
            factoryClassName: Neos\Neos\FrontendRouting\DimensionResolution\Resolver\AutoUriPathResolverFactory
    sites:
      '*':
        preset: 'default'
      'someSiteNode':
        preset: 'default'
        uriPathSuffix: ''
        # ...

#Site Specific Configuration Reference

For each site (or the fallback *), you can configure:

contentRepository (required): Identifier of the contentRepository to use
The uriPathSuffix that will be appended to all Neos URLs (except for the homepage URL)
contentDimensions
- resolver
  - factoryClassName: class name pointing to a DimensionResolverFactory. You'll either use existing ones, or create your own class and reference it here. See Reference: DimensionResolvers for DimensionResolvers shipped with Neos.
  - options: Options for the resolver. See Reference: DimensionResolvers for resolver-specific options.
- defaultDimensionSpacePoint (Dimension Space Point) - this is relevant for the following scenario:
  - If the user visits the homepage (/), and no dimension resolver resolves this, which dimension should be shown.

#adjusting Site Resolving

For context, the Routing Architecture gives helpful overview.

Site resolving is normally done via the SiteDetectionMiddleware, which implements the default logic, checking out site and domain records in the database.

Feel free to copy and adjust the SiteDetectionMiddleware to your own package - this is a planned extension point. In your middleware, you need to create a SiteDetectionResult, and then store it in the HTTP request.

You then need to override the detectSite middleware via Settings.yaml (make sure to add a composer dependency to neos/neos in your site package, to ensure your configuration wins):

Neos:
  Flow:
    http:
      middlewares:
        'detectSite':
          position: 'before routing'
          middleware: 'Your\Custom\SiteDetectionMiddleware'

This way, you can freely change how you resolve which site (and content repository) is active for the given request.

If you change this, you'll likely also want to override CrossSiteLinkerInterface for the reverse direction when generating links.

#Accessing the ContentRepositoryId from within PHP

If you received a ContentRepository instance from somewhere from the framework, you can assume this is the correct instance.

If you write PHP controllers, you can retrieve the ContentRepositoryId from the SiteDetectionResult via the following snippet:

<?php

class YourController extends ActionController {
    public function indexAction(string $nodeAddress) {
        $contentRepositoryId = SiteDetectionResult::fromRequest($this->request->getHttpRequest())->contentRepositoryId;

        // for reference, this is how you fetch the ContentRepository then.
        $contentRepository = $this->contentRepositoryRegistry->get($contentRepositoryId);

        // as soon as you have the ContentRepository, you can resolve the NodeAddress
        $nodeAddressFactory = NodeAddressFactory::create($contentRepository);
        $contextNodeAddress = $nodeAddressFactory->createFromUriString($contextNode);

        // ... and then you can load the node via the content graph.
        $subgraph = $contentRepository->getContentGraph()->getSubgraph($contextNodeAddress->contentStreamId, $contextNodeAddress->dimensionSpacePoint, VisibilityConstraints::withoutRestrictions());
        $contextNode = $subgraph->findNodeById($contextNodeAddress->nodeAggregateId);

   }
}