From e662325a067ca449639174661e04bae3d98deddb Mon Sep 17 00:00:00 2001
From: Philippe SEGATORI <tigitz@users.noreply.github.com>
Date: Wed, 14 Aug 2024 13:53:22 +0200
Subject: [PATCH] Support internal link in documentation menu

---
 resources/views/docs/section.blade.php        | 17 +++--
 src/Controller/DocumentationController.php    |  2 +-
 .../DocumentationMenuFactory.php              | 67 ++++++++++++-------
 src/Documentation/DocumentationMenuItem.php   | 30 +++++++++
 .../DocumentationMenuItemFactory.php          | 45 +++++++++++++
 src/ValueObject/DocumentationSection.php      | 33 ---------
 .../DocumentationMenuFactoryTest.php          | 15 ++++-
 7 files changed, 140 insertions(+), 69 deletions(-)
 create mode 100644 src/Documentation/DocumentationMenuItem.php
 create mode 100644 src/Documentation/DocumentationMenuItemFactory.php
 delete mode 100644 src/ValueObject/DocumentationSection.php

diff --git a/resources/views/docs/section.blade.php b/resources/views/docs/section.blade.php
index f82b9aeeb..0493de59c 100644
--- a/resources/views/docs/section.blade.php
+++ b/resources/views/docs/section.blade.php
@@ -12,33 +12,32 @@
             <ul class="mt-3">
                 <li>
                     <a
-                            href="{{ action(\App\Controller\DocumentationController::class) }}"
+                        href="{{ action(\App\Controller\DocumentationController::class) }}"
                     >Introduction</a>
                 </li>
             </ul>
 
-            @foreach ($documentations_sections_by_category as $category => $documentation_sections)
+            @foreach ($documentation_menu_categories as $category => $documentation_menu_items)
                 <hr class="border-line">
 
                 <h4 class="mt-4 mb-3">{{ $category }}</h4>
 
                 <ul>
-                    @foreach ($documentation_sections as $documentation_section)
+                    @foreach ($documentation_menu_items as $documentation_menu_item)
                         @php
-                            /** @var $documentation_section \App\ValueObject\DocumentationSection */
+                            /** @var $documentation_menu_item \App\Documentation\DocumentationMenuItem */
                         @endphp
 
                         <li>
-                            @if ($documentation_section->isNew())
+                            @if ($documentation_menu_item->isNew())
                                 <div class="badge text-white bg-danger">NEW</div>
                                 &nbsp;
                             @endif
 
-                            <a href="{{ action(\App\Controller\DocumentationController::class, ['section' => $documentation_section->getSlug()]) }}"
-                               class="{{ $documentation_section->isNew() ? 'text-bold' : '' }}"
+                            <a href="{{ $documentation_menu_item->getHref() }}"
+                               class="{{ $documentation_menu_item->isNew() ? 'text-bold' : '' }}"
                             >
-                                {{ $documentation_section->getName() }}
-
+                                {{ $documentation_menu_item->getLabel() }}
 
                             </a>
                         </li>
diff --git a/src/Controller/DocumentationController.php b/src/Controller/DocumentationController.php
index fa12a9359..c56c3754c 100644
--- a/src/Controller/DocumentationController.php
+++ b/src/Controller/DocumentationController.php
@@ -23,7 +23,7 @@ public function __invoke(string $section = 'introduction'): View
         return \view('docs/section', [
             'section_title' => $this->documentationMenuFactory->createSectionTitle($section),
             'section_markdown_contents' => $markdownContents,
-            'documentations_sections_by_category' => $this->documentationMenuFactory->create(),
+            'documentation_menu_categories' => $this->documentationMenuFactory->create(),
         ]);
     }
 }
diff --git a/src/Documentation/DocumentationMenuFactory.php b/src/Documentation/DocumentationMenuFactory.php
index 5ec2dd063..eaf5c5268 100644
--- a/src/Documentation/DocumentationMenuFactory.php
+++ b/src/Documentation/DocumentationMenuFactory.php
@@ -4,47 +4,68 @@
 
 namespace App\Documentation;
 
-use App\ValueObject\DocumentationSection;
+use App\Controller\FilterRectorController;
 
 /**
  * @see \App\Tests\Documentation\DocumentationMenuFactoryTest
  */
 final class DocumentationMenuFactory
 {
+    public function __construct(
+        private DocumentationMenuItemFactory $documentationMenuItemFactory
+    ) {
+    }
+
     /**
-     * @return array<string, DocumentationSection[]>
+     * @return array<string, DocumentationMenuItem[]>
      */
     public function create(): array
     {
         return [
             'First Steps' => [
-                new DocumentationSection('integration-to-new-project', 'New Project', true),
-                new DocumentationSection('define-paths', 'Define Paths'),
-                new DocumentationSection('set-lists', 'Set Lists'),
-                new DocumentationSection('ignoring-rules-or-paths', 'Ignoring Rules or Paths'),
-                new DocumentationSection('import-names', 'Import Names'),
-                new DocumentationSection('configured-rules', 'Configured Rules'),
+                $this->documentationMenuItemFactory->createSection('integration-to-new-project', 'New Project', true),
+                $this->documentationMenuItemFactory->createSection('define-paths', 'Define Paths'),
+                $this->documentationMenuItemFactory->createSection('set-lists', 'Set Lists'),
+                $this->documentationMenuItemFactory->createInternalLink(FilterRectorController::class, 'Find Rules'),
+                $this->documentationMenuItemFactory->createSection(
+                    'ignoring-rules-or-paths',
+                    'Ignoring Rules or Paths'
+                ),
+                $this->documentationMenuItemFactory->createSection('import-names', 'Import Names'),
+                $this->documentationMenuItemFactory->createSection('configured-rules', 'Configured Rules'),
             ],
             'Configuration' => [
-                new DocumentationSection('static-reflection-and-autoload', 'Static Reflection And Autoload'),
-                new DocumentationSection('config-configuration', 'Config Configuration'),
-                new DocumentationSection('php-version-features', 'PHP Version Features'),
-                new DocumentationSection('commands', 'Commands', true),
-                new DocumentationSection('team-tools', 'Team Tools', true),
+                $this->documentationMenuItemFactory->createSection(
+                    'static-reflection-and-autoload',
+                    'Static Reflection And Autoload'
+                ),
+                $this->documentationMenuItemFactory->createSection('config-configuration', 'Config Configuration'),
+                $this->documentationMenuItemFactory->createSection('php-version-features', 'PHP Version Features'),
+                $this->documentationMenuItemFactory->createSection('commands', 'Commands', true),
+                $this->documentationMenuItemFactory->createSection('team-tools', 'Team Tools', true),
             ],
             'Testing and CI' => [
-                new DocumentationSection('cache-in-ci', 'Cache in CI'),
-                new DocumentationSection('debugging', 'Debugging'),
-                new DocumentationSection('troubleshooting-parallel', 'Troubleshooting Parallel'),
-                new DocumentationSection('reporting-issue-with-rector', 'Reporting Issue With Rector'),
+                $this->documentationMenuItemFactory->createSection('cache-in-ci', 'Cache in CI'),
+                $this->documentationMenuItemFactory->createSection('debugging', 'Debugging'),
+                $this->documentationMenuItemFactory->createSection(
+                    'troubleshooting-parallel',
+                    'Troubleshooting Parallel'
+                ),
+                $this->documentationMenuItemFactory->createSection(
+                    'reporting-issue-with-rector',
+                    'Reporting Issue With Rector'
+                ),
             ],
             'Advanced' => [
-                new DocumentationSection('how-rector-works', 'How Rector Works'),
-                new DocumentationSection('custom-rule', 'Custom Rule'),
-                new DocumentationSection('writing-tests-for-custom-rule', 'Writing Tests For Custom Rule'),
-                new DocumentationSection('rules-overview', 'Rules Overview'),
-                new DocumentationSection('creating-a-node-visitor', 'Creating Node Visitor'),
-                new DocumentationSection('how-to-run-on-php-53', 'Run on PHP 5.3', true),
+                $this->documentationMenuItemFactory->createSection('how-rector-works', 'How Rector Works'),
+                $this->documentationMenuItemFactory->createSection('custom-rule', 'Custom Rule'),
+                $this->documentationMenuItemFactory->createSection(
+                    'writing-tests-for-custom-rule',
+                    'Writing Tests For Custom Rule'
+                ),
+                $this->documentationMenuItemFactory->createSection('rules-overview', 'Rules Overview'),
+                $this->documentationMenuItemFactory->createSection('creating-a-node-visitor', 'Creating Node Visitor'),
+                $this->documentationMenuItemFactory->createSection('how-to-run-on-php-53', 'Run on PHP 5.3', true),
             ],
         ];
     }
diff --git a/src/Documentation/DocumentationMenuItem.php b/src/Documentation/DocumentationMenuItem.php
new file mode 100644
index 000000000..92d6af3ad
--- /dev/null
+++ b/src/Documentation/DocumentationMenuItem.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Documentation;
+
+class DocumentationMenuItem
+{
+    public function __construct(
+        private string $href,
+        private string $label,
+        private bool $isNew = false,
+    ) {
+    }
+
+    public function getHref(): string
+    {
+        return $this->href;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->label;
+    }
+
+    public function isNew(): bool
+    {
+        return $this->isNew;
+    }
+}
diff --git a/src/Documentation/DocumentationMenuItemFactory.php b/src/Documentation/DocumentationMenuItemFactory.php
new file mode 100644
index 000000000..e3f8c6e7b
--- /dev/null
+++ b/src/Documentation/DocumentationMenuItemFactory.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Documentation;
+
+use App\Controller\DocumentationController;
+use Illuminate\Contracts\Routing\UrlGenerator;
+use Illuminate\Routing\Controller;
+
+final class DocumentationMenuItemFactory
+{
+    public function __construct(
+        private UrlGenerator $urlGenerator
+    ) {
+    }
+
+    public function createSection(string $slug, string $name, bool $isNew = false): DocumentationMenuItem
+    {
+        return new DocumentationMenuItem(
+            $this->urlGenerator->action(DocumentationController::class, [
+                'section' => $slug,
+            ]),
+            $name,
+            $isNew
+        );
+
+    }
+
+    /**
+     * @param class-string<Controller>|list<class-string<Controller>|string> $actionController
+     */
+    public function createInternalLink(
+        string|array $actionController,
+        string $label,
+        mixed $actionParameters = null,
+        bool $isNew = false,
+    ): DocumentationMenuItem {
+        return new DocumentationMenuItem(
+            $this->urlGenerator->action($actionController, $actionParameters),
+            $label,
+            $isNew,
+        );
+    }
+}
diff --git a/src/ValueObject/DocumentationSection.php b/src/ValueObject/DocumentationSection.php
deleted file mode 100644
index a6b0238bf..000000000
--- a/src/ValueObject/DocumentationSection.php
+++ /dev/null
@@ -1,33 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\ValueObject;
-
-/**
- * @api used in the templates
- */
-final class DocumentationSection
-{
-    public function __construct(
-        private readonly string $slug,
-        private readonly string $name,
-        private readonly bool $isNew = false,
-    ) {
-    }
-
-    public function getSlug(): string
-    {
-        return $this->slug;
-    }
-
-    public function getName(): string
-    {
-        return $this->name;
-    }
-
-    public function isNew(): bool
-    {
-        return $this->isNew;
-    }
-}
diff --git a/tests/Documentation/DocumentationMenuFactoryTest.php b/tests/Documentation/DocumentationMenuFactoryTest.php
index d6627c73d..806b5d412 100644
--- a/tests/Documentation/DocumentationMenuFactoryTest.php
+++ b/tests/Documentation/DocumentationMenuFactoryTest.php
@@ -5,7 +5,9 @@
 namespace App\Tests\Documentation;
 
 use App\Documentation\DocumentationMenuFactory;
-use App\ValueObject\DocumentationSection;
+use App\Documentation\DocumentationMenuItem;
+use App\Documentation\DocumentationMenuItemFactory;
+use Illuminate\Contracts\Routing\UrlGenerator;
 use PHPUnit\Framework\TestCase;
 
 final class DocumentationMenuFactoryTest extends TestCase
@@ -14,7 +16,14 @@ final class DocumentationMenuFactoryTest extends TestCase
 
     protected function setUp(): void
     {
-        $this->documentationMenuFactory = new DocumentationMenuFactory();
+        $urlGenerator = $this->createMock(UrlGenerator::class);
+        $urlGenerator->expects($this->any())
+            ->method('action')
+            ->willReturn('/index.html');
+
+        $this->documentationMenuFactory = new DocumentationMenuFactory(
+            new DocumentationMenuItemFactory($urlGenerator)
+        );
     }
 
     public function testSectionTitle(): void
@@ -29,7 +38,7 @@ public function testCategory(): void
 
         foreach ($documentationSectionsByCategory as $category => $documentationSections) {
             $this->assertIsString($category);
-            $this->assertContainsOnlyInstancesOf(DocumentationSection::class, $documentationSections);
+            $this->assertContainsOnlyInstancesOf(DocumentationMenuItem::class, $documentationSections);
         }
     }
 }