Skip to content

Commit b1a365a

Browse files
jaapiojaapio
authored
Merge pull request #1212 from phpDocumentor/inline-content-deprecation
Inline content deprecation
2 parents 98d5455 + c79ee0c commit b1a365a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+358
-153
lines changed

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

+8-9
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
{% apply spaceless %}
2-
<figure
3-
class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
4-
{% if node.hasOption('width') %}style="width: {{ node.option('width') }}"{% endif %}
5-
>
6-
{{ uml(node.value) }}
7-
{% if node.caption %}<figcaption>{{ node.caption }}</figcaption>{% endif %}
8-
</figure>
9-
{% endapply %}
1+
<figure class="uml-diagram{% if node.classesString %} {{ node.classesString }}{% endif %}"
2+
{%- if node.hasOption('width') %} style="width: {{ node.option('width') }}"{% endif -%}
3+
>
4+
{{ uml(node.value) }}
5+
{% if node.caption %}
6+
<figcaption>{{ node.caption }}</figcaption>
7+
{% endif %}
8+
</figure>

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
2020
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
21+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
2122
use Psr\Log\LoggerInterface;
2223

2324
/** @extends AbstractInlineTextDecoratorParser<EmphasisInlineNode> */
@@ -39,7 +40,7 @@ protected function getType(): string
3940
/** @param InlineNodeInterface[] $children */
4041
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
4142
{
42-
return new EmphasisInlineNode($content ?? '', $children);
43+
return new EmphasisInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
4344
}
4445

4546
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
2020
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
21+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
2122
use Psr\Log\LoggerInterface;
2223

2324
use function assert;
@@ -48,13 +49,12 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
4849
{
4950
assert($commonMarkNode instanceof Link);
5051

51-
$content ??= $commonMarkNode->getUrl();
5252
$url = $commonMarkNode->getUrl();
5353
if (str_ends_with($url, '.md') && filter_var($url, FILTER_VALIDATE_URL) === false) {
5454
$url = substr($url, 0, -3);
5555
}
5656

57-
return new HyperLinkNode($content, $url, $children);
57+
return new HyperLinkNode($content ? [new PlainTextInlineNode($content)] : $children, $url);
5858
}
5959

6060
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
use League\CommonMark\Node\Node as CommonMarkNode;
1818
use phpDocumentor\Guides\Nodes\Inline\InlineNode;
1919
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
20+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
2021
use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
2122
use Psr\Log\LoggerInterface;
2223

@@ -39,7 +40,7 @@ protected function getType(): string
3940
/** @param InlineNodeInterface[] $children */
4041
protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content, array $children = []): InlineNodeInterface
4142
{
42-
return new StrongInlineNode($content ?? '', $children);
43+
return new StrongInlineNode($content ? [new PlainTextInlineNode($content)] : $children);
4344
}
4445

4546
protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

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

+5-5
Original file line numberDiff line numberDiff line change
@@ -77,21 +77,21 @@ public function processNode(
7777
private function resolveLinkTarget(string $targetReference): LinkInlineNode
7878
{
7979
if (filter_var($targetReference, FILTER_VALIDATE_EMAIL)) {
80-
return new HyperLinkNode('', $targetReference);
80+
return new HyperLinkNode([], $targetReference);
8181
}
8282

8383
if (filter_var($targetReference, FILTER_VALIDATE_URL)) {
84-
return new HyperLinkNode('', $targetReference);
84+
return new HyperLinkNode([], $targetReference);
8585
}
8686

8787
if (preg_match(self::REFERENCE_REGEX, $targetReference, $matches)) {
88-
return new ReferenceNode($matches[1], '');
88+
return new ReferenceNode($matches[1]);
8989
}
9090

9191
if (preg_match(self::REFERENCE_ESCAPED_REGEX, $targetReference, $matches)) {
92-
return new ReferenceNode($matches[1], '');
92+
return new ReferenceNode($matches[1]);
9393
}
9494

95-
return new DocReferenceNode($targetReference, '');
95+
return new DocReferenceNode($targetReference);
9696
}
9797
}

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515

1616
use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
1717
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
18+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1819
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1920
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
2021

@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
4546

4647
$lexer->moveNext();
4748

48-
return new EmphasisInlineNode($text);
49+
return new EmphasisInlineNode([new PlainTextInlineNode($text)]);
4950

5051
default:
5152
$text .= $token->value;

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

+7-2
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
1717
use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
1818
use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
19+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1920
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
2021

2122
use function filter_var;
@@ -39,13 +40,17 @@ protected function createReference(BlockContext $blockContext, string $reference
3940
if (str_ends_with($reference, '.rst') && filter_var($reference, FILTER_VALIDATE_URL) === false) {
4041
$reference = substr($reference, 0, -4);
4142

42-
return new DocReferenceNode($reference, $text ?? $reference);
43+
$text ??= $reference;
44+
45+
return new DocReferenceNode($reference, $text !== '' ? [new PlainTextInlineNode($text)] : []);
4346
}
4447

4548
if ($registerLink && $text !== null) {
4649
$blockContext->getDocumentParserContext()->setLink($text, $reference);
4750
}
4851

49-
return new HyperLinkNode($text ?? $reference, $reference);
52+
$text ??= $reference;
53+
54+
return new HyperLinkNode($text !== '' ? [new PlainTextInlineNode($text)] : [], $reference);
5055
}
5156
}

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
1515

1616
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
17+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1718
use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
1819
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
1920
use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
@@ -45,7 +46,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): InlineNod
4546

4647
$lexer->moveNext();
4748

48-
return new StrongInlineNode($text);
49+
return new StrongInlineNode([new PlainTextInlineNode($text)]);
4950

5051
default:
5152
$text .= $token->value;

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\TextRoles;
1515

1616
use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1718
use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
1819
use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
1920
use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -49,6 +50,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
4950
$reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
5051
$prefix = $this->genericLinkProvider->getLinkPrefix($role);
5152

52-
return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, self::TYPE, $prefix);
53+
return new ReferenceNode($reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink, self::TYPE, $prefix);
5354
}
5455
}

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515

1616
use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
1717
use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
18+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1819
use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
1920

2021
/**
@@ -51,6 +52,6 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
5152
{
5253
$interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
5354

54-
return new DocReferenceNode($interlinkData->reference, $referenceName ?? '', $interlinkData->interlink);
55+
return new DocReferenceNode($interlinkData->reference, $referenceName ? [new PlainTextInlineNode($referenceName)] : [], $interlinkData->interlink);
5556
}
5657
}

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

+8-1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\TextRoles;
1515

1616
use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1718
use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
1819
use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
1920
use phpDocumentor\Guides\RestructuredText\Parser\Interlink\InterlinkParser;
@@ -48,6 +49,12 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
4849
$reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
4950
$prefix = $this->genericLinkProvider->getLinkPrefix($role);
5051

51-
return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType, $prefix);
52+
return new ReferenceNode(
53+
$reference,
54+
$referenceName ? [new PlainTextInlineNode($referenceName)] : [],
55+
$interlinkData->interlink,
56+
$linkType,
57+
$prefix,
58+
);
5259
}
5360
}

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

+2-1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
namespace phpDocumentor\Guides\RestructuredText\TextRoles;
1515

1616
use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
1718
use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
1819

1920
final class ReferenceTextRole extends AbstractReferenceTextRole
@@ -34,6 +35,6 @@ public function getAliases(): array
3435
/** @return ReferenceNode */
3536
protected function createNode(string $referenceTarget, string|null $referenceName, string $role): AbstractLinkInlineNode
3637
{
37-
return new ReferenceNode($referenceTarget, $referenceName ?? '');
38+
return new ReferenceNode($referenceTarget, $referenceName ? [new PlainTextInlineNode($referenceName)] : []);
3839
}
3940
}

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
*{{- node.value|raw -}}*
1+
*{{- node|plaintext -}}*

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

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{%- if node.url -%}
2-
`{{ node.value|raw }} <{{- node.url -}}>`__
2+
`{{ node|plaintext }} <{{- node.url -}}>`__
33
{%- elseif node.targetReference -%}
4-
:doc:`{{ node.value|raw }} <{{- node.targetReference -}}>`
4+
:doc:`{{ node|plaintext }} <{{- node.targetReference -}}>`
55
{%- else -%}
6-
{{- node.value -}}
6+
{{- node|plaintext -}}
77
{%- endif -%}

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
**{{- node.value|raw -}}**
1+
**{{- node|plaintext -}}**

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

+14-2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
namespace phpDocumentor\Guides\RstTheme\Twig;
1515

1616
use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
17+
use phpDocumentor\Guides\Nodes\Inline\InlineNodeInterface;
18+
use phpDocumentor\Guides\Nodes\InlineCompoundNode;
1719
use phpDocumentor\Guides\Nodes\Table\TableColumn;
1820
use phpDocumentor\Guides\Nodes\Table\TableRow;
1921
use phpDocumentor\Guides\Nodes\TableNode;
@@ -57,14 +59,24 @@ public function getFunctions(): array
5759
public function getFilters(): array
5860
{
5961
return [
60-
new TwigFilter('clean_content', [$this, 'cleanContent']),
62+
new TwigFilter('clean_content', $this->cleanContent(...)),
63+
new TwigFilter('plaintext', $this->plaintext(...)),
6164
];
6265
}
6366

67+
public function plaintext(InlineNodeInterface $node): string
68+
{
69+
if ($node instanceof InlineCompoundNode) {
70+
return implode('', array_map($this->plaintext(...), $node->getChildren()));
71+
}
72+
73+
return $node->toString();
74+
}
75+
6476
public function cleanContent(string $content): string
6577
{
6678
$lines = explode("\n", $content);
67-
$lines = array_map('rtrim', $lines);
79+
$lines = array_map(rtrim(...), $lines);
6880
$content = implode("\n", $lines);
6981

7082
$content = preg_replace('/(\n){2,}/', "\n\n", $content);

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

+18-6
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@
1616
use Doctrine\Deprecations\Deprecation;
1717
use phpDocumentor\Guides\Nodes\InlineCompoundNode;
1818

19+
use function func_get_arg;
20+
use function func_num_args;
21+
use function is_string;
22+
1923
abstract class AbstractLinkInlineNode extends InlineCompoundNode implements LinkInlineNode
2024
{
2125
use BCInlineNodeBehavior;
@@ -26,16 +30,24 @@ abstract class AbstractLinkInlineNode extends InlineCompoundNode implements Link
2630
public function __construct(
2731
private readonly string $type,
2832
private readonly string $targetReference,
29-
string $value = '',
30-
array $children = [],
33+
string|array $children = [],
3134
) {
32-
if (empty($children)) {
35+
if (is_string($children)) {
3336
Deprecation::trigger(
3437
'phpdocumentor/guides',
3538
'https://github.com/phpDocumentor/guides/issues/1161',
36-
'Please provide the children as an array of InlineNodeInterface instances instead of a string.',
39+
'Passing the content of %s as string is deprecated, pass an array of InlineNodeInterface instances instead. New signature: string $type, string $targetReference, array $children',
40+
static::class,
3741
);
38-
$children = [new PlainTextInlineNode($value)];
42+
43+
if (func_num_args() < 4) {
44+
// compat with (string $type, string $targetReference, string $value) signature
45+
$children = $children === '' ? [] : [new PlainTextInlineNode($children)];
46+
} else {
47+
// compat with (string $type, string $targetReference, string $value, array $children = []) signature
48+
/** @var InlineNodeInterface[] $children */
49+
$children = func_get_arg(3);
50+
}
3951
}
4052

4153
parent::__construct($children);
@@ -62,7 +74,7 @@ public function getDebugInformation(): array
6274
return [
6375
'type' => $this->getType(),
6476
'targetReference' => $this->getTargetReference(),
65-
'value' => $this->getValue(),
77+
'value' => $this->toString(),
6678
];
6779
}
6880

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

+5-3
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ public function getValue(): string
2424
Deprecation::trigger(
2525
'phpdocumentor/guides',
2626
'https://github.com/phpDocumentor/guides/issues/1161',
27-
'Use getChildren to access the value of this node.',
27+
'Use getChildren to access the value of %s.',
28+
static::class,
2829
);
2930

3031
return $this->toString();
@@ -34,12 +35,13 @@ public function getValue(): string
3435
public function setValue(mixed $value): void
3536
{
3637
if (is_string($value)) {
37-
$value = [new PlainTextInlineNode($value)];
38+
$value = $value === '' ? [] : [new PlainTextInlineNode($value)];
3839

3940
Deprecation::trigger(
4041
'phpdocumentor/guides',
4142
'https://github.com/phpDocumentor/guides/issues/1161',
42-
'Please provide the children as an array of InlineNodeInterface instances instead of a string.',
43+
'Passing a string to %s is deprecated, pass an array of InlineNodeInterface instances instead.',
44+
__METHOD__,
4345
);
4446
}
4547

0 commit comments

Comments
 (0)