Inline content deprecation

packages/guides-graphs/resources/template/html/body/uml.html.twig

@@ -1,9 +1,8 @@
-{% apply spaceless %}
-    <figure
-        class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
-        {% if node.hasOption('width') %}style="width: {{ node.option('width') }}"{% endif %}
-    >
-        {{ uml(node.value) }}
-    {% if node.caption %}<figcaption>{{ node.caption }}</figcaption>{% endif %}
-    </figure>
-{% endapply %}
+<figure class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
+    {%- if node.hasOption('width') %} style="width: {{ node.option('width') }}"{% endif -%}
+>
+    {{ uml(node.value) }}
+    {% if node.caption %}
+    <figcaption>{{ node.caption }}</figcaption>
+    {% endif %}
+</figure>

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/EmphasisParser.php

@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use Psr\Log\LoggerInterface;
 
 /** @extends AbstractInlineTextDecoratorParser<EmphasisInlineNode> */
@@ -39,7 +40,7 @@ protected function getType(): string
     /** @param InlineNodeInterface[] $children */
     protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new EmphasisInlineNode($content ?? '', $children);
+        return new EmphasisInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php

@@ -18,6 +18,7 @@
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use Psr\Log\LoggerInterface;
 
 use function assert;
@@ -48,13 +49,12 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
     {
         assert($commonMarkNode instanceof Link);
 
-        $content ??= $commonMarkNode->getUrl();
         $url =  $commonMarkNode->getUrl();
         if (str_ends_with($url, '.md') && filter_var($url, FILTER_VALIDATE_URL) === false) {
             $url = substr($url, 0, -3);
         }
 
-        return new HyperLinkNode($content, $url, $children);
+        return new HyperLinkNode($content ? [new PlainTextInlineNode($content)] : $children, $url);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/StrongParser.php

@@ -17,6 +17,7 @@
 use League\CommonMark\Node\Node as CommonMarkNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use Psr\Log\LoggerInterface;
 
@@ -39,7 +40,7 @@ protected function getType(): string
     /** @param InlineNodeInterface[] $children */
     protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
     {
-        return new StrongInlineNode($content ?? '', $children);
+        return new StrongInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php

@@ -77,21 +77,21 @@ public function processNode(
     private function resolveLinkTarget(string $targetReference): LinkInlineNode
     {
         if (filter_var($targetReference, FILTER_VALIDATE_EMAIL)) {
-            return new HyperLinkNode('', $targetReference);
+            return new HyperLinkNode([], $targetReference);
         }
 
         if (filter_var($targetReference, FILTER_VALIDATE_URL)) {
-            return new HyperLinkNode('', $targetReference);
+            return new HyperLinkNode([], $targetReference);
         }
 
         if (preg_match(self::REFERENCE_REGEX, $targetReference, $matches)) {
-            return new ReferenceNode($matches[1], '');
+            return new ReferenceNode($matches[1]);
         }
 
         if (preg_match(self::REFERENCE_ESCAPED_REGEX, $targetReference, $matches)) {
-            return new ReferenceNode($matches[1], '');
+            return new ReferenceNode($matches[1]);
         }
 
-        return new DocReferenceNode($targetReference, '');
+        return new DocReferenceNode($targetReference);
     }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/EmphasisRule.php

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
 
                     $lexer->moveNext();
 
-                    return new EmphasisInlineNode($text);
+                    return new EmphasisInlineNode([new PlainTextInlineNode($text)]);
 
                 default:
                     $text .= $token->value;

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php

@@ -16,6 +16,7 @@
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 
 use function filter_var;
@@ -39,13 +40,17 @@ protected function createReference(BlockContext $blockContext, string $reference
         if (str_ends_with($reference, '.rst') && filter_var($reference, FILTER_VALIDATE_URL) === false) {
             $reference = substr($reference, 0, -4);
 
-            return new DocReferenceNode($reference, $text ?? $reference);
+            $text ??= $reference;
+
+            return new DocReferenceNode($reference, $text !== '' ? [new PlainTextInlineNode($text)] : []);
         }
 
         if ($registerLink && $text !== null) {
             $blockContext->getDocumentParserContext()->setLink($text, $reference);
         }
 
-        return new HyperLinkNode($text ?? $reference, $reference);
+        $text ??= $reference;
+
+        return new HyperLinkNode($text !== '' ? [new PlainTextInlineNode($text)] : [], $reference);
     }
 }

packages/guides-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/StrongRule.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
 use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
 
                     $lexer->moveNext();
 
-                    return new StrongInlineNode($text);
+                    return new StrongInlineNode([new PlainTextInlineNode($text)]);
 
                 default:
                     $text .= $token->value;

packages/guides-restructured-text/src/RestructuredText/TextRoles/ApiClassTextRole.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -49,6 +50,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
         $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, self::TYPE, $prefix);
+        return new ReferenceNode($reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink, self::TYPE, $prefix);
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/DocReferenceTextRole.php

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
 
 /**
@@ -51,6 +52,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
     {
         $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
 
-        return new DocReferenceNode($interlinkData->reference, $referenceName ?? '', $interlinkData->interlink);
+        return new DocReferenceNode($interlinkData->reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink);
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/GenericReferenceTextRole.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -48,6 +49,12 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
         $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType, $prefix);
+        return new ReferenceNode(
+            $reference,
+            $referenceName ? [new PlainTextInlineNode($referenceName)] : [],
+            $interlinkData->interlink,
+            $linkType,
+            $prefix,
+        );
     }
 }

packages/guides-restructured-text/src/RestructuredText/TextRoles/ReferenceTextRole.php

@@ -14,6 +14,7 @@
 namespace phpDocumentor\Guides\RestructuredText\TextRoles;
 
 use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
 use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 
 final class ReferenceTextRole extends AbstractReferenceTextRole
@@ -34,6 +35,6 @@ public function getAliases(): array
     /** @return ReferenceNode */
     protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
     {
-        return new ReferenceNode($referenceTarget, $referenceName ?? '');
+        return new ReferenceNode($referenceTarget, $referenceName ? [new PlainTextInlineNode($referenceName)] : []);
     }
 }

packages/guides-theme-rst/resources/template/rst/inline/emphasis.rst.twig

@@ -1 +1 @@
-*{{- node.value|raw -}}*
+*{{- node|plaintext -}}*

packages/guides-theme-rst/resources/template/rst/inline/link.rst.twig

@@ -1,7 +1,7 @@
 {%- if node.url -%}
-    `{{ node.value|raw }} <{{- node.url -}}>`__
+    `{{ node|plaintext }} <{{- node.url -}}>`__
 {%- elseif node.targetReference -%}
-    :doc:`{{ node.value|raw }} <{{- node.targetReference -}}>`
+    :doc:`{{ node|plaintext }} <{{- node.targetReference -}}>`
 {%- else -%}
-    {{- node.value -}}
+    {{- node|plaintext -}}
 {%- endif -%}

packages/guides-theme-rst/resources/template/rst/inline/strong.rst.twig

@@ -1 +1 @@
-**{{- node.value|raw -}}**
+**{{- node|plaintext -}}**

packages/guides-theme-rst/src/RstTheme/Twig/RstExtension.php

@@ -14,6 +14,8 @@
 namespace phpDocumentor\Guides\RstTheme\Twig;
 
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Table\TableColumn;
 use phpDocumentor\Guides\Nodes\Table\TableRow;
 use phpDocumentor\Guides\Nodes\TableNode;
@@ -57,14 +59,24 @@ public function getFunctions(): array
     public function getFilters(): array
     {
         return [
-            new TwigFilter('clean_content', [$this, 'cleanContent']),
+            new TwigFilter('clean_content', $this->cleanContent(...)),
+            new TwigFilter('plaintext', $this->plaintext(...)),
         ];
     }
 
+    public function plaintext(InlineNodeInterface $node): string
+    {
+        if ($node instanceof InlineCompoundNode) {
+            return implode('', array_map($this->plaintext(...), $node->getChildren()));
+        }
+
+        return $node->toString();
+    }
+
     public function cleanContent(string $content): string
     {
         $lines = explode("\n", $content);
-        $lines = array_map('rtrim', $lines);
+        $lines = array_map(rtrim(...), $lines);
         $content = implode("\n", $lines);
 
         $content = preg_replace('/(\n){2,}/', "\n\n", $content);

packages/guides/src/Nodes/Inline/AbstractLinkInlineNode.php

@@ -16,6 +16,10 @@
 use Doctrine\Deprecations\Deprecation;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 
+use function func_get_arg;
+use function func_num_args;
+use function is_string;
+
 abstract class AbstractLinkInlineNode extends InlineCompoundNode implements LinkInlineNode
 {
     use BCInlineNodeBehavior;
@@ -26,16 +30,24 @@ abstract class AbstractLinkInlineNode extends InlineCompoundNode implements Link
     public function __construct(
         private readonly string $type,
         private readonly string $targetReference,
-        string $value = '',
-        array $children = [],
+        string|array $children = [],
     ) {
-        if (empty($children)) {
+        if (is_string($children)) {
             Deprecation::trigger(
                 'phpdocumentor/guides',
                 'https://github.com/phpDocumentor/guides/issues/1161',
-                'Please provide the children as an array of InlineNodeInterface instances instead of a string.',
+                'Passing the content of %s as string is deprecated, pass an array of InlineNodeInterface instances instead. New signature: string $type, string $targetReference, array $children',
+                static::class,
             );
-            $children = [new PlainTextInlineNode($value)];
+
+            if (func_num_args() < 4) {
+                // compat with (string $type, string $targetReference, string $value) signature
+                $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+            } else {
+                // compat with (string $type, string $targetReference, string $value, array $children = []) signature
+                /** @var InlineNodeInterface[] $children */
+                $children = func_get_arg(3);
+            }
         }
 
         parent::__construct($children);
@@ -62,7 +74,7 @@ public function getDebugInformation(): array
         return [
             'type' => $this->getType(),
             'targetReference' => $this->getTargetReference(),
-            'value' => $this->getValue(),
+            'value' => $this->toString(),
         ];
     }
 

packages/guides/src/Nodes/Inline/BCInlineNodeBehavior.php

@@ -24,7 +24,8 @@ public function getValue(): string
         Deprecation::trigger(
             'phpdocumentor/guides',
             'https://github.com/phpDocumentor/guides/issues/1161',
-            'Use getChildren to access the value of this node.',
+            'Use getChildren to access the value of %s.',
+            static::class,
         );
 
         return $this->toString();
@@ -34,12 +35,13 @@ public function getValue(): string
     public function setValue(mixed $value): void
     {
         if (is_string($value)) {
-            $value = [new PlainTextInlineNode($value)];
+            $value = $value === '' ? [] : [new PlainTextInlineNode($value)];
 
             Deprecation::trigger(
                 'phpdocumentor/guides',
                 'https://github.com/phpDocumentor/guides/issues/1161',
-                'Please provide the children as an array of InlineNodeInterface instances instead of a string.',
+                'Passing a string to %s is deprecated, pass an array of InlineNodeInterface instances instead.',
+                __METHOD__,
             );
         }