Merge pull request #959 from phpDocumentor/backport/1.x/pr-932

[1.x] [BUGFIX] Make links to special objects prefixable

Author: phpdoc-bot

packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig

@@ -1,5 +1,5 @@
 <dl class="confval">
-    <dt id="{{ node.id }}">
+    <dt id="{{ node.anchor }}">
         <code class="sig-name descname"><span class="pre">{{ node.plainContent }}</span></code></dt>
     <dd>
         <div class="line-block">

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

@@ -44,7 +44,7 @@ public function __construct(
     ) {
         parent::__construct($startingRule);
 
-        $genericLinkProvider->addGenericLink(self::NAME, ConfvalNode::LINK_TYPE);
+        $genericLinkProvider->addGenericLink(self::NAME, ConfvalNode::LINK_TYPE, ConfvalNode::LINK_PREFIX);
     }
 
     public function getName(): string

packages/guides-restructured-text/src/RestructuredText/Nodes/ConfvalNode.php

@@ -15,8 +15,8 @@
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
-use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 
 /**
  * The confval directive configuration values.
@@ -25,9 +25,10 @@
  *
  * @extends CompoundNode<Node>
  */
-final class ConfvalNode extends CompoundNode implements LinkTargetNode
+final class ConfvalNode extends CompoundNode implements PrefixedLinkTargetNode
 {
     public const LINK_TYPE = 'std:confval';
+    public const LINK_PREFIX = 'confval-';
 
     /**
      * @param list<Node> $value
@@ -60,6 +61,11 @@ public function getId(): string
         return $this->id;
     }
 
+    public function getAnchor(): string
+    {
+        return self::LINK_PREFIX . $this->id;
+    }
+
     public function getLinkText(): string
     {
         return $this->plainContent;
@@ -85,4 +91,9 @@ public function getAdditionalOptions(): array
     {
         return $this->additionalOptions;
     }
+
+    public function getPrefix(): string
+    {
+        return self::LINK_PREFIX;
+    }
 }

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

@@ -30,10 +30,13 @@ final class GenericLinkProvider
     private array $textRoleLinkTypeMapping = [
         'ref' => SectionNode::STD_LABEL,
     ];
+    /** @var array<string, string> */
+    private array $prefixLinkTypeMapping = ['ref' => ''];
 
-    public function addGenericLink(string $textRole, string $linkType): void
+    public function addGenericLink(string $textRole, string $linkType, string $prefix = ''): void
     {
         $this->textRoleLinkTypeMapping[$textRole] = $linkType;
+        $this->prefixLinkTypeMapping[$textRole] = $prefix;
     }
 
     /** @return string[] */
@@ -46,4 +49,9 @@ public function getLinkType(string $textRole): string
     {
         return $this->textRoleLinkTypeMapping[$textRole] ?? SectionNode::STD_LABEL;
     }
+
+    public function getLinkPrefix(string $textRole): string
+    {
+        return $this->prefixLinkTypeMapping[$textRole] ?? '';
+    }
 }

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

@@ -46,7 +46,8 @@ protected function createNode(string $referenceTarget, string|null $referenceNam
         $linkType = $this->genericLinkProvider->getLinkType($role);
         $interlinkData = $this->interlinkParser->extractInterlink($referenceTarget);
         $reference = $this->anchorReducer->reduceAnchor($interlinkData->reference);
+        $prefix = $this->genericLinkProvider->getLinkPrefix($role);
 
-        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType);
+        return new ReferenceNode($reference, $referenceName ?? '', $interlinkData->interlink, $linkType, $prefix);
     }
 }

packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php

@@ -21,6 +21,7 @@
 use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\MultipleLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
 use Psr\Log\LoggerInterface;
@@ -97,13 +98,19 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
             $currentDocument = $this->documentStack->top();
             Assert::notNull($currentDocument);
             $anchor = $this->anchorReducer->reduceAnchor($node->getId());
+            $prefix = '';
+            if ($node instanceof PrefixedLinkTargetNode) {
+                $prefix = $node->getPrefix();
+            }
+
             $this->addLinkTargetToProject(
                 $compilerContext,
                 new InternalTarget(
                     $currentDocument->getFilePath(),
                     $anchor,
                     $node->getLinkText(),
                     $node->getLinkType(),
+                    $prefix,
                 ),
             );
             if ($node instanceof MultipleLinkTargetsNode) {

packages/guides/src/Meta/InternalTarget.php

@@ -24,6 +24,7 @@ public function __construct(
         protected string $anchorName,
         private readonly string|null $title = null,
         private readonly string $linkType = SectionNode::STD_LABEL,
+        private readonly string $prefix = '',
     ) {
     }
 
@@ -63,4 +64,9 @@ public function getLinkType(): string
     {
         return $this->linkType;
     }
+
+    public function getPrefix(): string
+    {
+        return $this->prefix;
+    }
 }

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

@@ -37,6 +37,7 @@ public function __construct(
         string $value = '',
         private readonly string $interlinkDomain = '',
         private readonly string $linkType = SectionNode::STD_LABEL,
+        private readonly string $prefix = '',
     ) {
         parent::__construct(self::TYPE, $targetReference, $value);
     }
@@ -62,6 +63,11 @@ public function getDebugInformation(): array
 
     public function getInterlinkGroup(): string
     {
-        return 'std:label';
+        return $this->linkType;
+    }
+
+    public function getPrefix(): string
+    {
+        return $this->prefix;
     }
 }

packages/guides/src/Nodes/PrefixedLinkTargetNode.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Nodes;
+
+interface PrefixedLinkTargetNode extends LinkTargetNode
+{
+    public function getPrefix(): string;
+}

packages/guides/src/ReferenceResolvers/AnchorReferenceResolver.php

@@ -46,7 +46,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
             return false;
         }
 
-        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getAnchor()));
+        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getPrefix() . $target->getAnchor()));
         if ($node->getValue() === '') {
             $node->setValue($target->getTitle() ?? '');
         }