Merge pull request #603 from phpDocumentor/feat/plantuml-rendering

Feat: Add plantuml server rendering

composer.json

@@ -28,6 +28,7 @@
         "ext-json": "*",
         "ext-mbstring": "*",
         "doctrine/lexer": "^3.0",
+        "jawira/plantuml-encoding": "^1.1",
         "league/commonmark": "^2.4",
         "league/flysystem": "^1.0.5",
         "league/tactician": "^1.1",

packages/guides-cli/src/DependencyInjection/ContainerFactory.php

@@ -43,7 +43,7 @@ public function __construct(array $defaultExtensions = [])
         $this->configLoader = new XmlFileLoader(new FileLocator());
 
         foreach ([new GuidesExtension(), new ReStructuredTextExtension(), ...$defaultExtensions] as $extension) {
-            $this->registerExtension($extension);
+            $this->registerExtension($extension, []);
         }
     }
 
@@ -54,7 +54,7 @@ public function loadExtensionConfig(string $extension, array $config): void
 
         $extensionAlias = $this->registeredExtensions[$extensionFqcn] ?? false;
         if (!$extensionAlias) {
-            $this->registerExtension(new $extensionFqcn());
+            $this->registerExtension(new $extensionFqcn(), $config);
 
             return;
         }
@@ -79,10 +79,11 @@ public function create(string $vendorDir): Container
         return $this->container;
     }
 
-    private function registerExtension(ExtensionInterface $extension): void
+    /** @param array<mixed> $config */
+    private function registerExtension(ExtensionInterface $extension, array $config): void
     {
         $this->container->registerExtension($extension);
-        $this->container->loadFromExtension($extension->getAlias());
+        $this->container->loadFromExtension($extension->getAlias(), $config);
 
         $this->registeredExtensions[$extension::class] = $extension->getAlias();
     }

packages/guides-graphs/composer.json

@@ -24,7 +24,11 @@
         "php": "^8.1",
         "phpdocumentor/guides": "self.version",
         "phpdocumentor/guides-restructured-text": "self.version",
+        "jawira/plantuml-encoding": "^1.0",
         "symfony/process": "^5.4 || ^6.3",
         "twig/twig": "~2.0 || ^3.0"
+    },
+    "suggest": {
+        "jawira/plantuml": "To render graphs locally using plant uml"
     }
 }

packages/guides-graphs/resources/config/guides-graphs.php

@@ -3,15 +3,37 @@
 declare(strict_types=1);
 
 use phpDocumentor\Guides\Graphs\Directives\UmlDirective;
-use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
+use phpDocumentor\Guides\Graphs\Nodes\UmlNode;
+use phpDocumentor\Guides\Graphs\Renderer\DiagramRenderer;
+use phpDocumentor\Guides\Graphs\Renderer\PlantumlRenderer;
+use phpDocumentor\Guides\Graphs\Renderer\PlantumlServerRenderer;
+use phpDocumentor\Guides\Graphs\Twig\UmlExtension;
+use phpDocumentor\Guides\NodeRenderers\TemplateNodeRenderer;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
 return static function (ContainerConfigurator $container): void {
     $container->services()
         ->defaults()
         ->autowire()
         ->autoconfigure()
-        ->instanceof(BaseDirective::class)
+        ->set(UmlDirective::class)
         ->tag('phpdoc.guides.directive')
-        ->set(UmlDirective::class);
+
+        ->set('phpdoc.guides.', TemplateNodeRenderer::class)
+        ->tag('phpdoc.guides.noderenderer.html')
+        ->arg('$template', 'body/uml.html.twig')
+        ->arg('$nodeClass', UmlNode::class)
+
+        ->set(PlantumlRenderer::class)
+        ->arg('$plantUmlBinaryPath', '%guides.graphs.plantuml_binary%')
+
+        ->set(PlantumlServerRenderer::class)
+        ->arg(
+            '$plantumlServerUrl',
+            '%guides.graphs.plantuml_server%',
+        )
+        ->alias(DiagramRenderer::class, PlantumlServerRenderer::class)
+
+        ->set(UmlExtension::class)
+        ->tag('twig.extension');
 };

packages/guides-graphs/src/Graphs/DependencyInjection/Configuration.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Graphs\DependencyInjection;
+
+use Symfony\Component\Config\Definition\Builder\ArrayNodeDefinition;
+use Symfony\Component\Config\Definition\Builder\TreeBuilder;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+use function assert;
+
+class Configuration implements ConfigurationInterface
+{
+    public function getConfigTreeBuilder(): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('Graphs');
+        $rootNode = $treeBuilder->getRootNode();
+        assert($rootNode instanceof ArrayNodeDefinition);
+
+        $rootNode->children()
+            ->scalarNode('renderer')
+            ->defaultValue('plantuml-server')
+            ->info('Render engine to use for generating graphs')
+            ->end()
+            ->scalarNode('plantuml_server')
+            ->defaultValue('https://www.plantuml.com/plantuml')
+            ->info('URL of the PlantUML server to use')
+            ->end()
+            ->scalarNode('plantuml_binary')
+            ->defaultValue('plantuml')
+            ->info('Path to your local PlantUML binary')
+            ->end();
+
+        return $treeBuilder;
+    }
+}

packages/guides-graphs/src/Graphs/DependencyInjection/GraphsExtension.php

@@ -7,20 +7,37 @@
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Extension\Extension;
+use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 
 use function dirname;
 
-class GraphsExtension extends Extension
+class GraphsExtension extends Extension implements PrependExtensionInterface
 {
     /** @param mixed[] $configs */
     public function load(array $configs, ContainerBuilder $container): void
     {
+        $config = $this->processConfiguration(
+            $this->getConfiguration($configs, $container),
+            $configs,
+        );
+
+        $container->setParameter('guides.graphs.renderer', $config['renderer']);
+        $container->setParameter('guides.graphs.plantuml_binary', $config['plantuml_binary']);
+        $container->setParameter('guides.graphs.plantuml_server', $config['plantuml_server']);
+
         $loader = new PhpFileLoader(
             $container,
             new FileLocator(dirname(__DIR__, 3) . '/resources/config'),
         );
 
         $loader->load('guides-graphs.php');
     }
+
+    public function prepend(ContainerBuilder $container): void
+    {
+        $container->prependExtensionConfig('guides', [
+            'base_template_paths' => [dirname(__DIR__, 3) . '/resources/template/html'],
+        ]);
+    }
 }

packages/guides-graphs/src/Graphs/Renderer/PlantumlServerRenderer.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\Graphs\Renderer;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+use function Jawira\PlantUml\encodep;
+
+final class PlantumlServerRenderer implements DiagramRenderer
+{
+    public function __construct(
+        private readonly HttpClientInterface $httpClient,
+        private readonly string $plantumlServerUrl,
+        private readonly LoggerInterface $logger,
+    ) {
+    }
+
+    public function render(string $diagram): string|null
+    {
+        $encodedDiagram = encodep($diagram);
+
+        $response = $this->httpClient->request(
+            'GET',
+            $this->plantumlServerUrl . '/svg/' . $encodedDiagram,
+        );
+
+        if ($response->getStatusCode() !== 200) {
+            $this->logger->error('Failed to render diagram using server:' . $this->plantumlServerUrl);
+
+            return null;
+        }
+
+        return $response->getContent();
+    }
+}

tests/Integration/tests/graphs/plantuml-inline/expected/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>Uml Directive</title>
+
+</head>
+<body>
+<div class="section" id="uml-directive">
+    <h1>Uml Directive</h1>
+
+    <figure
+            class="uml-diagram"
+    ><?xml version="1.0" encoding="us-ascii" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentStyleType="text/css" height="120px" preserveAspectRatio="none" style="width:163px;height:120px;background:#FFFFFF;" version="1.1" viewBox="0 0 163 120" width="163px" zoomAndPan="magnify"><defs/><g><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="29" x2="29" y1="36.2969" y2="85.4297"/><line style="stroke:#181818;stroke-width:0.5;stroke-dasharray:5.0,5.0;" x1="112" x2="112" y1="36.2969" y2="85.4297"/><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="48" x="5" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="34" x="12" y="24.9951">class</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="48" x="5" y="84.4297"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="34" x="12" y="104.4248">class</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="90" x="67" y="5"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="76" x="74" y="24.9951">otherClass</text><rect fill="#E2E2F0" height="30.2969" rx="2.5" ry="2.5" style="stroke:#181818;stroke-width:0.5;" width="90" x="67" y="84.4297"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="76" x="74" y="104.4248">otherClass</text><polygon fill="#181818" points="100,63.4297,110,67.4297,100,71.4297,104,67.4297" style="stroke:#181818;stroke-width:1.0;"/><line style="stroke:#181818;stroke-width:1.0;" x1="29" x2="106" y1="67.4297" y2="67.4297"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="59" x="36" y="62.3638">message</text><!--SRC=[Iyv9B2vMqBLJo2_9I2ro1lEi579JYuiJqrC1]--></g></svg></figure>
+</div>
+
+</body>
+</html>

tests/Integration/tests/graphs/plantuml-inline/input/guides.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd">
+    <extension class="phpDocumentor\Guides\Graphs">
+        <renderer>plantuml-server</renderer>
+        <plantuml-binary>/usr/bin/plantuml</plantuml-binary>
+    </extension>
+</guides>

tests/Integration/tests/graphs/plantuml-inline/input/index.rst

@@ -0,0 +1,7 @@
+==============
+Uml Directive
+==============
+
+..  uml::
+
+    class -> otherClass : message