[FEATURE] Allow "EXT:self" syntax for typo3:site-set-settings (#702)

By default only files within a "Documentation/" directory can be read by
the "typo3:site-set-settings" directive.

However in cases where extensions (Core or third party) provide
additional files in their main directory, these should be accessible, to
allow reading the ACTUAL file contents, and not requiring a copy to be
placed inside Documentation/.

With this patch, a new syntax "EXT:self" allows to refer to this base
"/project/" directory as a path prefix, instead of
"/project/Documentation/". Other file traversal beyond this is
forbidden.

Author: garvinhicking

packages/typo3-docs-theme/src/Directives/SiteSetSettingsDirective.php

@@ -13,6 +13,8 @@
 
 namespace T3Docs\Typo3DocsTheme\Directives;
 
+use League\Flysystem\Adapter\Local;
+use League\Flysystem\Filesystem;
 use phpDocumentor\Guides\RestructuredText\Nodes\ConfvalNode;
 use Symfony\Component\Yaml\Yaml;
 use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
@@ -73,16 +75,52 @@ public function loadFileFromDocumentation(BlockContext $blockContext, Directive
     {
         $parser = $blockContext->getDocumentParserContext()->getParser();
         $parserContext = $parser->getParserContext();
-
-        $path = $parserContext->absoluteRelativePath($directive->getData());
-
+        /** @var Filesystem $origin */
         $origin = $parserContext->getOrigin();
+        /** @var Local $adapter */
+        $adapter = $origin->getAdapter();
+        $pathPrefix = (string)$adapter->getPathPrefix();
+
+        // The path delivered via the directive like:
+        // ..  typo3:site-set-settings:: EXT:self/Configuration/Sets/FluidStyledContent/settings.definitions.yaml
+        $setConfigurationFile = $directive->getData();
+
+        // By default, the RST files are placed inside a "Documentation" subdirectory.
+        // When using the docker container, this origin root path is then set to "/project/Documentation".
+        // No files on the "/project/" directory level can usually be accessed, even though they may belong
+        // to TYPO3 core/third-party extensions that the Documentation belongs to directory-wise.
+        // To allow files to be retrieved on the EXTENSION-level, instead of DOCUMENTATION-level,
+        // a special string "EXT:self" is evaluated here.
+        // If a path starts with that notation, it will be referenced from the "/project/..." directory level.
+        // It will not break out of the "/project/" mapping!
+        if (str_starts_with($setConfigurationFile, 'EXT:self')) {
+            // This will replace "EXT:self/Configuration/Sets/File.yaml" with "/Configuration/Sets/File.yaml"
+            // and is then passed to absoluteRelativePath() which will set $path = "/Configuration/Sets/File.yaml",
+            // but ensure no "../../../" or other path traversal is allowed.
+            $path = $parserContext->absoluteRelativePath(str_replace('EXT:self', '', $setConfigurationFile));
+
+            // Get the current origin Path, usually "/project/Documentation/", and go one level up.
+            $newOriginPath = dirname($pathPrefix) . '/';
+
+            // Temporarily change the path prefix now to "/project/"
+            $adapter->setPathPrefix($newOriginPath);
+        } else {
+            $path = $parserContext->absoluteRelativePath($setConfigurationFile);
+        }
+
         if (!$origin->has($path)) {
-            throw new FileLoadingException(sprintf('The directive .. typo3:site-set-settings:: cannot find the source at %s. ', $path));
+            // Revert temporary change to origin (because it being a singleton)
+            $adapter->setPathPrefix($pathPrefix);
+            throw new FileLoadingException(
+                sprintf('The directive .. typo3:site-set-settings:: cannot find the source at %s. ', $path)
+            );
         }
 
         $contents = $origin->read($path);
 
+        // Revert temporary change to origin (because it being a singleton).
+        $adapter->setPathPrefix($pathPrefix);
+
         if ($contents === false) {
             throw new FileLoadingException(sprintf('The .. typo3:site-set-settings:: cannot load file from path %s. ', $path));
         }

tests/Integration/tests/roles/role-composer/expected/index.html

@@ -13,7 +13,7 @@ <h1>Document Title<a class="headerlink" href="#document-title" data-bs-toggle="m
    data-homepage="https://typo3.org/"
    data-documentation=""
    data-issues="https://github.com/TYPO3/testing-framework/issues"
-   data-source="https://github.com/TYPO3/testing-framework/tree/8.2.0"
+   data-source="https://github.com/TYPO3/testing-framework/tree/8.2.1"
 >
     typo3/testing-framework
 </a> to test projects based on

tests/Integration/tests/site-set-ext-syntax/_root_include/settings.definitions.yaml

@@ -0,0 +1,129 @@
+settings:
+  styles.content.defaultHeaderType:
+    default: 2
+    label: 'Default Header type'
+    type: int
+    description: 'Enter the number of the header layout to be used by default'
+  styles.content.shortcut.tables:
+    default: tt_content
+    label: 'List of accepted tables'
+    type: string
+    description: ''
+  styles.content.allowTags:
+    default: 'a, abbr, acronym, address, article, aside, b, bdo, big, blockquote, br, caption, center, cite, code, col, colgroup, dd, del, dfn, dl, div, dt, em, figure, font, footer, header, h1, h2, h3, h4, h5, h6, hr, i, img, ins, kbd, label, li, link, meta, nav, ol, p, pre, q, s, samp, sdfield, section, small, span, strike, strong, style, sub, sup, table, thead, tbody, tfoot, td, th, tr, title, tt, u, ul, var'
+    label: 'List of allowed HTML tags when rendering RTE content'
+    type: string
+    description: ''
+  styles.content.image.lazyLoading:
+    default: lazy
+    label: 'Default settings for browser-native image lazy loading'
+    type: string
+    enum:
+      lazy: 'Lazy'
+      eager: 'Eager'
+      auto: 'Auto'
+    description: 'Can be "lazy" (browsers could choose to load images later), "eager" (load images right away) or "auto" (browser will determine whether the image should be lazy loaded or not)'
+  styles.content.image.imageDecoding:
+    default: ''
+    label: 'Default settings for an image decoding hint to the browser'
+    type: string
+    enum:
+      sync: 'Sync'
+      async: 'Asynchronous'
+      auto: 'Auto'
+    description: 'Can be "sync" (synchronously for atomic presentation with other content), "async" (asynchronously to avoid delaying presentation of other content), "auto" (no preference in decoding mode) or an empty value to omit the usage of the decoding attribute (same as "auto")'
+  styles.content.textmedia.maxW:
+    default: 600
+    label: 'Max Image/Media Width'
+    type: int
+    description: 'This indicates that maximum number of pixels (width) a block of media elements inserted as content is allowed to consume'
+  styles.content.textmedia.maxWInText:
+    default: 300
+    label: 'Max Image/Media Width (Text)'
+    type: int
+    description: 'Same as above, but this is the maximum width when text is wrapped around an block of media elements. Default is 50% of the normal Max Media Item Width'
+  styles.content.textmedia.columnSpacing:
+    default: 10
+    label: 'Advanced, Column space'
+    type: int
+    description: 'Horizontal distance between media elements in a block in content elements of type "Media & Images". If you change this manually in your CSS, you need to adjust this setting accordingly'
+  styles.content.textmedia.rowSpacing:
+    default: 10
+    label: 'Advanced, Row space'
+    type: int
+    description: 'Vertical distance after each media elements row in content elements of type ""Text & Media". If you change this manually in your CSS, you need to adjust this setting accordingly'
+  styles.content.textmedia.textMargin:
+    default: 10
+    label: 'Advanced, Margin to text'
+    type: int
+    description: 'Horizontal distance between an imageblock and text in content elements of type "Text & Images"'
+  styles.content.textmedia.borderColor:
+    default: '#000000'
+    label: 'Media element border, color'
+    type: color
+    description: 'Bordercolor of media elements in content elements when "Border"-option for an element is set'
+  styles.content.textmedia.borderWidth:
+    default: 2
+    label: 'Media element border, thickness'
+    type: int
+    description: 'Thickness of border around media elements in content elements when "Border"-option for element is set'
+  styles.content.textmedia.borderPadding:
+    default: 0
+    label: 'Media element border, padding'
+    type: int
+    description: 'Padding left and right to the media element, around the border'
+  styles.content.textmedia.linkWrap.width:
+    default: 800m
+    label: 'Click-enlarge Media Width'
+    type: string
+    description: 'This specifies the width of the enlarged media element when click-enlarge is enabled'
+  styles.content.textmedia.linkWrap.height:
+    default: 600m
+    label: 'Click-enlarge Media Height'
+    type: string
+    description: 'This specifies the height of the enlarged media element when click-enlarge is enabled'
+  styles.content.textmedia.linkWrap.newWindow:
+    default: false
+    label: 'Advanced, New window'
+    type: bool
+    description: "If set, every click-enlarged media element will open in it's own popup window and not the current popup window (which may have a wrong size for the media element to fit in)"
+  styles.content.textmedia.linkWrap.lightboxEnabled:
+    default: false
+    label: 'Lightbox click-enlarge rendering'
+    type: bool
+    description: 'Whether media elements with click-enlarge checked should be rendered lightbox-compliant'
+  styles.content.textmedia.linkWrap.lightboxCssClass:
+    default: lightbox
+    label: 'Lightbox CSS class'
+    type: string
+    description: 'Which CSS class to use for lightbox links (only applicable if lightbox rendering is enabled)'
+  styles.content.textmedia.linkWrap.lightboxRelAttribute:
+    default: 'lightbox[{field:uid}]'
+    label: 'Lightbox rel="" attribute'
+    type: string
+    description: 'Which rel="" attribute to use for lightbox links (only applicable if lightbox rendering is enabled)'
+  styles.content.links.extTarget:
+    default: _blank
+    label: 'Target for external links'
+    type: string
+    description: ''
+  styles.content.links.keep:
+    default: path
+    label: 'Parts to keep when building links'
+    type: string
+    description: 'Comma separated list of the link parts to show when building the link-text: scheme,path,query. Example: "" (empty) => www.example.com, "scheme,path" => http://www.example.com'
+  styles.templates.templateRootPath:
+    default: ''
+    label: 'Path of Fluid Templates for all defined content elements'
+    type: string
+    description: ''
+  styles.templates.partialRootPath:
+    default: ''
+    label: 'Path of Fluid Partials for all defined content elements'
+    type: string
+    description: ''
+  styles.templates.layoutRootPath:
+    default: ''
+    label: 'Path of Fluid Layouts for all defined content elements'
+    type: string
+    description: ''