[FEATURE] Support directive image with target

resolves #911

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

@@ -14,12 +14,21 @@
 namespace phpDocumentor\Guides\RestructuredText\Directives;
 
 use phpDocumentor\Guides\Nodes\ImageNode;
+use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
+use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 
 use function dirname;
+use function filter_var;
+use function preg_match;
+
+use const FILTER_VALIDATE_EMAIL;
+use const FILTER_VALIDATE_URL;
 
 /**
  * Renders an image, example :
@@ -30,6 +39,12 @@
  */
 final class ImageDirective extends BaseDirective
 {
+    /** @see https://regex101.com/r/9dUrzu/3 */
+    public const REFERENCE_REGEX = '/^([a-zA-Z0-9-_]+)_$/';
+
+    /** @see https://regex101.com/r/6vPoiA/2 */
+    public const REFERENCE_ESCAPED_REGEX = '/^`([^`]+)`_$/';
+
     public function __construct(
         private readonly DocumentNameResolverInterface $documentNameResolver,
     ) {
@@ -45,11 +60,38 @@ public function processNode(
         BlockContext $blockContext,
         Directive $directive,
     ): Node {
-        return new ImageNode(
+        $node = new ImageNode(
             $this->documentNameResolver->absoluteUrl(
                 dirname($blockContext->getDocumentParserContext()->getContext()->getCurrentAbsolutePath()),
                 $directive->getData(),
             ),
         );
+        if ($directive->hasOption('target')) {
+            $targetReference = (string) $directive->getOption('target')->getValue();
+            $node->setTarget($this->resolveLinkTarget($targetReference));
+        }
+
+        return $node;
+    }
+
+    private function resolveLinkTarget(string $targetReference): LinkInlineNode
+    {
+        if (filter_var($targetReference, FILTER_VALIDATE_EMAIL)) {
+            return new HyperLinkNode('', $targetReference);
+        }
+
+        if (filter_var($targetReference, FILTER_VALIDATE_URL)) {
+            return new HyperLinkNode('', $targetReference);
+        }
+
+        if (preg_match(self::REFERENCE_REGEX, $targetReference, $matches)) {
+            return new ReferenceNode($matches[1], '');
+        }
+
+        if (preg_match(self::REFERENCE_ESCAPED_REGEX, $targetReference, $matches)) {
+            return new ReferenceNode($matches[1], '');
+        }
+
+        return new DocReferenceNode($targetReference, '');
     }
 }

packages/guides/resources/config/guides.php

@@ -28,6 +28,7 @@
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\ReferenceResolvers\EmailReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ExternalReferenceResolver;
+use phpDocumentor\Guides\ReferenceResolvers\ImageReferenceResolverPreRender;
 use phpDocumentor\Guides\ReferenceResolvers\Interlink\DefaultInventoryLoader;
 use phpDocumentor\Guides\ReferenceResolvers\Interlink\DefaultInventoryRepository;
 use phpDocumentor\Guides\ReferenceResolvers\Interlink\InventoryLoader;
@@ -192,6 +193,8 @@
 
         ->set(ReferenceResolverPreRender::class)
         ->tag('phpdoc.guides.prerenderer')
+        ->set(ImageReferenceResolverPreRender::class)
+        ->tag('phpdoc.guides.prerenderer')
 
         ->set(InMemoryRendererFactory::class)
         ->arg('$renderSets', tagged_iterator('phpdoc.renderer.typerenderer', 'format'))

packages/guides/resources/template/html/body/image.html.twig

@@ -1,3 +1,4 @@
+{% if node.target %}<a href="{{ node.target.url }}">{% endif %}
 <img
     src="{%- if node.value is external_target -%} {{ node.value }} {%- else -%} {{ asset(node.value) }} {%- endif -%}"
     {% if node.hasOption('width') %}width="{{ node.option('width') }}"{% endif%}
@@ -7,3 +8,4 @@
     {% if node.hasOption('title') %}title="{{ node.option('title') }}"{% endif%}
     {% if node.classesString %}class="{{ node.classesString }}"{% endif%}
 />
+{% if node.target %}</a>{% endif %}

packages/guides/src/Nodes/ImageNode.php

@@ -13,6 +13,19 @@
 
 namespace phpDocumentor\Guides\Nodes;
 
+use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+
 final class ImageNode extends TextNode
 {
+    public LinkInlineNode|null $target = null;
+
+    public function getTarget(): LinkInlineNode|null
+    {
+        return $this->target;
+    }
+
+    public function setTarget(LinkInlineNode|null $target): void
+    {
+        $this->target = $target;
+    }
 }

packages/guides/src/ReferenceResolvers/ImageReferenceResolverPreRender.php

@@ -0,0 +1,62 @@
+<?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\ReferenceResolvers;
+
+use phpDocumentor\Guides\NodeRenderers\PreRenderers\PreNodeRenderer;
+use phpDocumentor\Guides\Nodes\ImageNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\RenderContext;
+use Psr\Log\LoggerInterface;
+use Webmozart\Assert\Assert;
+
+use function array_merge;
+use function sprintf;
+
+final class ImageReferenceResolverPreRender implements PreNodeRenderer
+{
+    public function __construct(
+        private readonly DelegatingReferenceResolver $referenceResolver,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function supports(Node $node): bool
+    {
+        return $node instanceof ImageNode;
+    }
+
+    public function execute(Node $node, RenderContext $renderContext): Node
+    {
+        Assert::isInstanceOf($node, ImageNode::class);
+        if ($node->getTarget() === null) {
+            return $node;
+        }
+
+        $referenceLinkNode = $node->getTarget();
+        $messages = new Messages();
+        $resolved = $this->referenceResolver->resolve($referenceLinkNode, $renderContext, $messages);
+        if (!$resolved) {
+            $this->logger->warning(
+                $messages->getLastWarning()?->getMessage() ?? sprintf(
+                    'Target %s of image could not be resolved in %s',
+                    $referenceLinkNode->getTargetReference(),
+                    $renderContext->getCurrentFileName(),
+                ),
+                array_merge($renderContext->getLoggerInformation(), $messages->getLastWarning()?->getDebugInfo() ?? []),
+            );
+        }
+
+        return $node;
+    }
+}