Add direction to VisualizerTask (#12)

* Add direction to VisualizerTask * Update documentation * Rename constants
phingofficial · Apr 30, 2021 · e0b801c · e0b801c
1 parent 864e8d1
commit e0b801c
Show file tree

Hide file tree

Showing 7 changed files with 106 additions and 30 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -9,7 +9,13 @@ insert_final_newline     = true
 trim_trailing_whitespace = true
 
 [*.{php, xml, rng}]
-indent_size = 4
+indent_size     = 4
+max_line_length = 120
 
 [*.{md, txt}]
 trim_trailing_whitespace = false
+
+[.editorconfig]
+ij_editorconfig_align_group_field_declarations     = true
+ij_editorconfig_space_after_comma                  = true
+ij_editorconfig_spaces_around_assignment_operators = true
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,4 @@
 /composer.lock
 /custom.task.properties
 /custom.type.properties
+/docs/guide.html
diff --git a/build.png b/build.png
diff --git a/build.xml b/build.xml
@@ -5,18 +5,18 @@
     <target name="setup" depends="composer:install"
             description="Prepare project for development"/>
     <target name="qa" description="Check code quality"
-            depends="composer:validate, composer:normalize, phpstan:analyse"/>
+            depends="composer:normalize,composer:validate,phpstan:analyse"/>
+
+    <target name="visualizer" description="Create buildfile diagram">
+        <visualizer format="png"/>
+    </target>
 
     <target name="help" depends="visualizer">
         <exec executable="xdg-open" spawn="true">
             <arg path="build.png"/>
         </exec>
     </target>
 
-    <target name="visualizer" description="Create buildfile diagram">
-        <visualizer format="png"/>
-    </target>
-
     <target name="composer:normalize" description="Normalize composer.json content">
         <composer command="normalize"/>
     </target>
@@ -44,4 +44,15 @@
         </exec>
     </target>
 
+    <target name="guide:parse" description="Generate doc (dev only)">
+        <!-- I use this Target to have a documentation preview -->
+        <exec executable="xsltproc" passthru="true" checkreturn="true">
+            <arg value="--output"/>
+            <arg value="docs/guide.html"/>
+            <arg value="--xinclude"/>
+            <arg file="/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl"/>
+            <arg file="docs/guide.xml"/>
+        </exec>
+    </target>
+
 </project>
diff --git a/docs/guide.xml b/docs/guide.xml
@@ -1,12 +1,11 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?xml-model xlink:href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng"
-    schematypens="http://relaxng.org/ns/structure/1.0"?>
+<?xml version="1.0" encoding="UTF-8"?><?xml-model xlink:href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng"schematypens="http://relaxng.org/ns/structure/1.0"?>
 
 <sect1 role="taskdef" xml:id="VisualizerTask" xmlns="http://docbook.org/ns/docbook"
        xmlns:xlink="http://www.w3.org/1999/xlink">
     <title>VisualizerTask</title>
-    <para>The <literal>VisualizerTask</literal> generates a graphical representation of your current buildfile.
-        This allows you to see all available targets but also the calls and dependencies among targets.
+    <para>
+        The <literal>VisualizerTask</literal> generates a graphical representation of your current buildfile. This
+        allows you to see all available targets but also the calls and dependencies among targets.
     </para>
     <para>
         <literal>VisualizerTask</literal> is able to represent:
@@ -80,31 +79,52 @@
                     </entry>
                     <entry>no</entry>
                 </row>
+                <row>
+                    <entry>
+                        <literal>direction</literal>
+                    </entry>
+                    <entry>
+                        <literal role="type">String</literal>
+                    </entry>
+                    <entry>
+                        Use this to change the diagram's layout. Valid values are:
+                        <literal>horizontal</literal>
+                        and <literal>vertical</literal>.
+                    </entry>
+                    <entry>
+                        <literal>vertical</literal>
+                    </entry>
+                    <entry>no</entry>
+                </row>
                 <row>
                     <entry>
                         <literal>server</literal>
                     </entry>
                     <entry>
                         <literal role="type">String</literal>
                     </entry>
-                    <entry>PlantUML server.</entry>
+                    <entry>
+                        PlantUML server. Needed by all formats except <literal>puml</literal>.
+                    </entry>
                     <entry>http://www.plantuml.com/plantuml</entry>
                     <entry>no</entry>
                 </row>
             </tbody>
         </tgroup>
     </table>
-    <para>If you have network connectivity issues, you should try <literal>puml</literal> format. This format
-        doesn't needs Internet connection to generate a diagram.
+    <para>
+        If you have network connectivity issues, you should try <literal>puml</literal> format. This format doesn't
+        require a PlantUML server (and therefore an internet connection) to generate a diagram.
     </para>
     <sect2>
         <title>Examples</title>
         <para>Using <literal>VisualizerTask</literal> with default values:
         </para>
         <programlisting language="xml">&lt;visualizer/&gt;</programlisting>
-        <para>Setting diagram's format to <literal>svg</literal>:
+        <para>
+            Setting diagram's format to <literal>svg</literal> with <literal>horizontal</literal> arrows:
         </para>
-        <programlisting language="xml">&lt;visualizer format="svg"/&gt;</programlisting>
+        <programlisting language="xml">&lt;visualizer format="svg" direction="horizontal"/&gt;</programlisting>
         <para>Save diagram into <filename>resources/images/</filename> directory:
         </para>
         <programlisting language="xml">&lt;visualizer destination="resources/images/"/&gt;</programlisting>
@@ -246,8 +266,8 @@
                         <literal>config</literal>
                     </para>
                     <para>Holds additional config data. See
-                        <link xlink:href="http://docs.guzzlephp.org/en/stable/request-options.html"
-                              role="extern">Guzzle documentation
+                        <link xlink:href="http://docs.guzzlephp.org/en/stable/request-options.html" role="extern">Guzzle
+                            documentation
                         </link>
                         for supported values.
                     </para>

diff --git a/src/VisualizerTask.php b/src/VisualizerTask.php
@@ -45,16 +45,18 @@
  */
 class VisualizerTask extends HttpTask
 {
-    public const FORMAT_EPS  = 'eps';
-    public const FORMAT_PNG  = 'png';
-    public const FORMAT_PUML = 'puml';
-    public const FORMAT_SVG  = 'svg';
-    public const SERVER      = 'http://www.plantuml.com/plantuml';
-    public const STATUS_OK   = 200;
-    public const XSL_CALLS   = __DIR__ . '/calls.xsl';
-    public const XSL_FOOTER  = __DIR__ . '/footer.xsl';
-    public const XSL_HEADER  = __DIR__ . '/header.xsl';
-    public const XSL_TARGETS = __DIR__ . '/targets.xsl';
+    protected const ARROWS_HORIZONTAL = 'horizontal';
+    protected const ARROWS_VERTICAL   = 'vertical';
+    protected const FORMAT_EPS        = 'eps';
+    protected const FORMAT_PNG        = 'png';
+    protected const FORMAT_PUML       = 'puml';
+    protected const FORMAT_SVG        = 'svg';
+    protected const SERVER            = 'http://www.plantuml.com/plantuml';
+    protected const STATUS_OK         = 200;
+    protected const XSL_CALLS         = __DIR__ . '/calls.xsl';
+    protected const XSL_FOOTER        = __DIR__ . '/footer.xsl';
+    protected const XSL_HEADER        = __DIR__ . '/header.xsl';
+    protected const XSL_TARGETS       = __DIR__ . '/targets.xsl';
 
     /**
      * @var string Diagram format
@@ -71,6 +73,11 @@ class VisualizerTask extends HttpTask
      */
     protected $server;
 
+    /**
+     * @var string Arrows' direction
+     */
+    protected $direction;
+
     /**
      * Setting some default values and checking requirements
      */
@@ -92,6 +99,7 @@ public function init(): void
         }
         $this->setFormat(VisualizerTask::FORMAT_PNG);
         $this->setServer(VisualizerTask::SERVER);
+        $this->setDirection(VisualizerTask::ARROWS_VERTICAL);
     }
 
     /**
@@ -170,6 +178,7 @@ protected function transformToPuml(File $buildfile, string $xslFile): string
         $xsl = $this->loadXmlFile($xslFile);
 
         $processor = new XSLTProcessor();
+        $processor->setParameter('', 'direction', $this->getDirection());
         $processor->importStylesheet($xsl);
 
         return $processor->transformToXml($xml) . PHP_EOL;
@@ -259,7 +268,7 @@ public function getDestination(): ?string
      *
      * @return \Phing\Task\Ext\VisualizerTask
      */
-    public function setDestination(?string $destination): VisualizerTask
+    public function setDestination(?string $destination): self
     {
         $this->destination = $destination;
 
@@ -354,7 +363,7 @@ public function getServer(): string
      *
      * @return \Phing\Task\Ext\VisualizerTask
      */
-    public function setServer(string $server): VisualizerTask
+    public function setServer(string $server): self
     {
         if (!filter_var($server, FILTER_VALIDATE_URL)) {
             $exceptionMessage = 'Invalid PlantUml server';
@@ -366,6 +375,26 @@ public function setServer(string $server): VisualizerTask
         return $this;
     }
 
+    /**
+     * @return string
+     */
+    public function getDirection(): string
+    {
+        return $this->direction;
+    }
+
+    /**
+     * @param string $direction
+     *
+     * @return \Phing\Task\Ext\VisualizerTask
+     */
+    public function setDirection(string $direction): self
+    {
+        $this->direction = $direction === self::ARROWS_HORIZONTAL ? self::ARROWS_HORIZONTAL : self::ARROWS_VERTICAL;
+
+        return $this;
+    }
+
     /**
      * Receive server's response
      *

diff --git a/src/header.xsl b/src/header.xsl
@@ -1,10 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:param name="direction"/>
 <xsl:output method="text" encoding="UTF-8" indent="no"/>
 <xsl:template match="/project">@startuml
 <xsl:variable name="name" select="@name"/>
 title <xsl:value-of select="$name"/>
+<xsl:choose>
+<xsl:when test="'horizontal' = $direction">
+left to right direction
+</xsl:when>
+<xsl:otherwise>
+top to bottom direction
+</xsl:otherwise>
+</xsl:choose>
 skinparam ArrowFontColor Black
 skinparam ArrowThickness 2
 skinparam UseCaseBackgroundColor #FFFECC