Cleanup inline node constructors signature

wouterj · wouterj · commit 11a5bc2892dd · 2024-11-30T14:09:33.000+01:00
The `string $content` parameter is a legacy from before Markdown. It is
redundant and replaced by `array $children`.
diff --git a/packages/guides/src/Nodes/Inline/AbstractLinkInlineNode.php b/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);
diff --git a/packages/guides/src/Nodes/Inline/BCInlineNodeBehavior.php b/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__,
             );
         }
 
diff --git a/packages/guides/src/Nodes/Inline/DocReferenceNode.php b/packages/guides/src/Nodes/Inline/DocReferenceNode.php
@@ -13,7 +13,10 @@
 
 namespace phpDocumentor\Guides\Nodes\Inline;
 
+use Doctrine\Deprecations\Deprecation;
+
 use function array_merge;
+use function is_string;
 
 /**
  * Represents a link to document
@@ -29,12 +32,24 @@ final class DocReferenceNode extends AbstractLinkInlineNode implements CrossRefe
 {
     final public const TYPE = 'doc';
 
+    /** @param InlineNodeInterface[] $children */
     public function __construct(
         string $targetDocument,
-        string $value = '',
+        string|array $children = [],
         private readonly string $interlinkDomain = '',
     ) {
-        parent::__construct(self::TYPE, $targetDocument, $value);
+        if (is_string($children)) {
+            Deprecation::trigger(
+                'phpdocumentor/guides',
+                'https://github.com/phpDocumentor/guides/issues/1161',
+                'Passing the content of %s as string is deprecated, pass an array of InlineNodeInterface instances instead. New signature: string $targetDocument, array $children, string $interlinkDomain',
+                static::class,
+            );
+
+            $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+        }
+
+        parent::__construct(self::TYPE, $targetDocument, $children);
     }
 
     public function getInterlinkDomain(): string
diff --git a/packages/guides/src/Nodes/Inline/EmphasisInlineNode.php b/packages/guides/src/Nodes/Inline/EmphasisInlineNode.php
@@ -16,22 +16,35 @@
 use Doctrine\Deprecations\Deprecation;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 
+use function func_get_arg;
+use function func_num_args;
+use function is_string;
+
 final class EmphasisInlineNode extends InlineCompoundNode
 {
     use BCInlineNodeBehavior;
 
     public const TYPE = 'emphasis';
 
     /** @param InlineNodeInterface[] $children */
-    public function __construct(string $value, array $children = [])
+    public function __construct(string|array $children = [])
     {
-        if (empty($children)) {
-            $children = [new PlainTextInlineNode($value)];
+        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: array $children',
+                static::class,
             );
+
+            if (func_num_args() < 2) {
+                // compat with (string $value) signature
+                $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+            } else {
+                // compat with (string $value, array $children = []) signature
+                /** @var InlineNodeInterface[] $children */
+                $children = func_get_arg(1);
+            }
         }
 
         parent::__construct($children);
diff --git a/packages/guides/src/Nodes/Inline/HyperLinkNode.php b/packages/guides/src/Nodes/Inline/HyperLinkNode.php
@@ -13,14 +13,38 @@
 
 namespace phpDocumentor\Guides\Nodes\Inline;
 
+use Doctrine\Deprecations\Deprecation;
+
+use function func_get_arg;
+use function func_num_args;
+use function is_string;
+
 /**
  * Represents a link to an external source or email
  */
 final class HyperLinkNode extends AbstractLinkInlineNode
 {
     /** @param InlineNodeInterface[] $children */
-    public function __construct(string $value, string $targetReference, array $children = [])
+    public function __construct(string|array $children, string $targetReference)
     {
-        parent::__construct('link', $targetReference, $value, $children);
+        if (is_string($children)) {
+            Deprecation::trigger(
+                'phpdocumentor/guides',
+                'https://github.com/phpDocumentor/guides/issues/1161',
+                'Passing the content of %s as string is deprecated, pass an array of InlineNodeInterface instances instead. New signature: array $children, string $targetReference',
+                static::class,
+            );
+
+            if (func_num_args() < 3) {
+                // compat with (string $value, string $targetReference) signature
+                $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+            } else {
+                // compat with (string $value, string $targetReference, array $children = []) signature
+                /** @var InlineNodeInterface[] $children */
+                $children = func_get_arg(2);
+            }
+        }
+
+        parent::__construct('link', $targetReference, $children);
     }
 }
diff --git a/packages/guides/src/Nodes/Inline/ReferenceNode.php b/packages/guides/src/Nodes/Inline/ReferenceNode.php
@@ -13,9 +13,11 @@
 
 namespace phpDocumentor\Guides\Nodes\Inline;
 
+use Doctrine\Deprecations\Deprecation;
 use phpDocumentor\Guides\Nodes\SectionNode;
 
 use function array_merge;
+use function is_string;
 
 /**
  * CrossReferences are references outside a document. As parsing is file based normal references are in document,
@@ -32,14 +34,26 @@ final class ReferenceNode extends AbstractLinkInlineNode implements CrossReferen
 {
     final public const TYPE = 'ref';
 
+    /** @param InlineNodeInterface[] $children */
     public function __construct(
         string $targetReference,
-        string $value = '',
+        string|array $children = [],
         private readonly string $interlinkDomain = '',
         private readonly string $linkType = SectionNode::STD_LABEL,
         private readonly string $prefix = '',
     ) {
-        parent::__construct(self::TYPE, $targetReference, $value);
+        if (is_string($children)) {
+            Deprecation::trigger(
+                'phpdocumentor/guides',
+                'https://github.com/phpDocumentor/guides/issues/1161',
+                'Passing the content of %s as string is deprecated, pass an array of InlineNodeInterface instances instead. New signature: string $targetReference, $children, string $interlinkDomain, string $linkType, string $prefix',
+                static::class,
+            );
+
+            $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+        }
+
+        parent::__construct(self::TYPE, $targetReference, $children);
     }
 
     public function getLinkType(): string
diff --git a/packages/guides/src/Nodes/Inline/StrongInlineNode.php b/packages/guides/src/Nodes/Inline/StrongInlineNode.php
@@ -16,22 +16,35 @@
 use Doctrine\Deprecations\Deprecation;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 
+use function func_get_arg;
+use function func_num_args;
+use function is_string;
+
 final class StrongInlineNode extends InlineCompoundNode
 {
     use BCInlineNodeBehavior;
 
     public const TYPE = 'strong';
 
     /** @param InlineNodeInterface[] $children */
-    public function __construct(string $value, array $children = [])
+    public function __construct(string|array $children = [])
     {
-        if (empty($children)) {
-            $children = [new PlainTextInlineNode($value)];
+        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: array $children',
+                static::class,
             );
+
+            if (func_num_args() < 2) {
+                // compat with (string $value) signature
+                $children = $children === '' ? [] : [new PlainTextInlineNode($children)];
+            } else {
+                // compat with (string $value, array $children = []) signature
+                /** @var InlineNodeInterface[] $children */
+                $children = func_get_arg(1);
+            }
         }
 
         parent::__construct($children);
