Issue Bug Rejected

#110096Dotted site set settings not always read properly

Kevin Meier 06/24/26, 12:17 updated 09/03/26, 11:39

Description

I made a fresh TYPO3 14 installation following the documentation:

mkdir siteset-test
cd siteset-test
ddev config --php-version 8.4 --docroot public --project-type typo3
ddev start
ddev composer create-project "typo3/cms-base-distribution:^14"
ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db --create-site https://siteset-test.ddev.site/

Now, I created a fresh sitepackage at https://get.typo3.org/sitepackage based on Fluid Styled Content which created the following configuration file:

#EXT:sitepackage/Configuration/Sets/Sitepackage/settings.yaml
styles.templates.layoutRootPath: 'EXT:sitepackage/Resources/Private/ContentElements/Layouts/'
styles.templates.partialRootPath: 'EXT:sitepackage/Resources/Private/ContentElements/Partials/'
styles.templates.templateRootPath: 'EXT:sitepackage/Resources/Private/ContentElements/Templates/'

page.pageview.paths: 'EXT:sitepackage/Resources/Private/PageView/'

page.meta.viewport: 'width=device-width, initial-scale=1'
page.meta.robots: 'index,follow'
page.meta.apple-mobile-web-app-capable: 'no'
page.meta.compatible: 'IE=edge'

page.tracking.google.trackingID: ''
page.tracking.google.anonymizeIp: '1'

config.no_cache: '0'
config.removeDefaultJS: '0'
config.admPanel: '1'
config.prefixLocalAnchors: 'all'
config.headerComment: 'build by get.typo3.org/sitepackage'
config.sendCacheHeaders: '1'

Now I ran

composer req "company/sitepackage"

and added the site set in the site configuration of the previously created site. Finally, I ran

ddev typo3 cache:flush -g system

and the HTML output doesn’t resolve the meta tag variables properly (except for generator):

<meta http-equiv="x-ua-compatible" content="{$page.meta.compatible}">
<meta name="generator" content="TYPO3 CMS">
<meta name="viewport" content="{$page.meta.viewport}">
<meta name="robots" content="{$page.meta.robots}">
<meta name="apple-mobile-web-app-capable" content="{$page.meta.apple-mobile-web-app-capable}">

Now I changed all the page.meta configuration to use a tree like this:

page:
  meta:
    viewport: 'width=device-width, initial-scale=1'
    robots: 'index,follow'
    apple-mobile-web-app-capable: 'no'
    compatible: 'IE=edge'

and ran

ddev typo3 cache:flush -g system

again. Now the meta tags look like this:

<meta http-equiv="x-ua-compatible" content="IE=edge">
<meta name="generator" content="TYPO3 CMS">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="index,follow">
<meta name="apple-mobile-web-app-capable" content="no">

It looks like when using the dotted syntax for site settings, they are not properly read in all contexts. Another user reported in slack that when setting

tutu.value: 'initial'

and then calling

getSettings()->get('tutu')

the value is NULL and you have to instead call

getSettings()->get('tutu\\')

to retrieve the value, maybe this helps with tracking down the issue.

Reviews 1

History 3

  1. Helmut Hummel commented <span data-processor="relativetime" data-value="2026-08-25T17:09:03+00:00" > 08/25/26, 17:09 </span>

    the “dotted syntax” only works, when this value is defined in a site set and this site set is required in the site

  2. Benjamin Franzke commented and changed status New Rejected <span data-processor="relativetime" data-value="2026-09-03T11:39:56+00:00" > 09/03/26, 11:39 </span>

    Thanks for bringing this up!

    The reason we have this situation is backwards compatibility, but that made it confusing to understand.
    I understand that this is confusing and I’m actually sorry for that.

    Yes, as Helmut correctly pointed out, dotted syntax does only work for defined settings and that is actually intended behavior.

    The dotted “inline” syntax has been introduced for v13 for defined settings based on site sets, in order to allow a settings like foo.bar and foo.bar.baz to coexist.

    Site settings as a tree (which were introduced in v12) – we now call them legacy anonymous site settings – are still supported (because we didn’t want to break them), but really need to be presented as a tree as, we decided not to create settings implicitly based on the dotted settings syntax.

    There are two reasons for this:

    • We do want to add a new syntax for legacy anonymous settings which are only “allowed” for BC reasons (no new features for legacy stuff)
    • Traditionally (like in v12) the dotted syntax could theoretically be used as well and would have resulted in the same escaping that is applied now. That means supporting unescaped exposure of anonymous settings would have actually been a breaking change (strictly speaking).

    Or in other words (very technical):
    We “consume” all the defined settings from the settings.yaml and assume the remainder is the legacy tree and expose them with the same rules as in v12 for full backwards compatibility.

    I think the feature was not that well known in v12, therefore this dualsupport with diffrent behaviours came surprising. Also we identified that some examples in our documentation still used tree syntax for new settings (which was supported again for BC reasons) because the initial v13 implementation also used a tree, but was changed to dotted syntax in the v13 development phase – but we missed to update the documentation right away.

    Benjamin Kott thankfully adapted the documentation recently [1] (also thanks to the HEADS UP from this issue) to streamline the settings documentation and it now states:
    https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ApiOverview/SiteHandling/SiteSettings.html#site-settings

    > Important*
    >
    > Define every setting in an active site set before reading or overriding it. *An entry in settings.yaml does not create a definition
    . Only a defined setting is guaranteed to be available under its documented identifier, validated and converted to its declared type, supplied with a default value and shown in the site settings editor.
    >
    > TYPO3 retains anonymous values from legacy setting trees without a definition for backward compatibility. They are not a public configuration contract and should not be used by new code.

    Furthermore I’ve started a patch to discover if we should remove the legacy tree altogether, based on a suggestion [2] by Helmut
    > 95438: [!!!][WIP][TASK] Remove legacy tree based site settings | https://review.typo3.org/c/Packages/TYPO3.CMS/+/95438

    I’m a bit reluctant to be breaking at all, but maybe that’s the better option to reduce the likelihood of confusing situations like these in future.

    I’m now closing this issue as we consider it expected behaviour.
    Please feel free to report back if you disagree, so we can discuss if needed.

    Thanks, Benjamin

    [1] https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/6767
    2 https://typo3.slack.com/archives/C025BQLFA/p1787678345563549?thread_ts=1787570972.150259&cid=C025BQLFA