Theme: split classes and exceptions in namespace summary (#919)

ApiGen · Jul 2, 2017 · 24d3745 · 24d3745
1 parent 479b9ea
commit 24d3745
Show file tree

Hide file tree

Showing 19 changed files with 307 additions and 2 deletions.
diff --git a/packages/Element/src/ReflectionCollector/NamespaceReflectionCollector.php b/packages/Element/src/ReflectionCollector/NamespaceReflectionCollector.php
@@ -10,6 +10,7 @@
 use ApiGen\Reflection\Contract\Reflection\Partial\InNamespaceInterface;
 use ApiGen\Reflection\Contract\Reflection\Trait_\TraitReflectionInterface;
 use ApiGen\Reflection\Helper\ReflectionAnalyzer;
+use Throwable;
 
 final class NamespaceReflectionCollector implements BasicReflectionCollectorInterface
 {
@@ -40,6 +41,10 @@ public function processReflection(AbstractReflectionInterface $reflection): void
         $reflectionInterface = ReflectionAnalyzer::getReflectionInterfaceFromReflection($reflection);
         $namespace = $reflection->getNamespaceName() ?: self::NO_NAMESPACE;
 
+        if ($reflectionInterface === ClassReflectionInterface::class) {
+            $reflectionInterface = ($reflection->implementsInterface(Throwable::class)) ? 'exception' : 'class';
+        }
+
         $this->collectedReflections[$namespace][$reflectionInterface][$reflection->getName()] = $reflection;
     }
 
@@ -48,7 +53,15 @@ public function processReflection(AbstractReflectionInterface $reflection): void
      */
     public function getClassReflections(string $namespace): array
     {
-        return $this->collectedReflections[$namespace][ClassReflectionInterface::class] ?? [];
+        return $this->collectedReflections[$namespace]['class'] ?? [];
+    }
+
+    /**
+     * @return ClassReflectionInterface[]
+     */
+    public function getExceptionReflections(string $namespace): array
+    {
+        return $this->collectedReflections[$namespace]['exception'] ?? [];
     }
 
     /**

diff --git a/packages/Reflection/src/ReflectionStorage.php b/packages/Reflection/src/ReflectionStorage.php
@@ -6,6 +6,7 @@
 use ApiGen\Reflection\Contract\Reflection\Function_\FunctionReflectionInterface;
 use ApiGen\Reflection\Contract\Reflection\Interface_\InterfaceReflectionInterface;
 use ApiGen\Reflection\Contract\Reflection\Trait_\TraitReflectionInterface;
+use Throwable;
 
 final class ReflectionStorage
 {
@@ -14,6 +15,11 @@ final class ReflectionStorage
      */
     private $classReflections = [];
 
+    /**
+     * @var ClassReflectionInterface[]
+     */
+    private $exceptionReflections = [];
+
     /**
      * @var InterfaceReflectionInterface[]
      */
@@ -37,6 +43,14 @@ public function getClassReflections(): array
         return $this->classReflections;
     }
 
+    /**
+     * @return ClassReflectionInterface[]
+     */
+    public function getExceptionReflections(): array
+    {
+        return $this->exceptionReflections;
+    }
+
     /**
      * @param ClassReflectionInterface[] $classReflections
      */
@@ -46,7 +60,11 @@ public function addClassReflections(array $classReflections): void
         });
         sort($classReflections);
         foreach ($classReflections as $classReflection) {
-            $this->classReflections[$classReflection->getName()] = $classReflection;
+            if ($classReflection->implementsInterface(Throwable::class)) {
+                $this->exceptionReflections[$classReflection->getName()] = $classReflection;
+            } else {
+                $this->classReflections[$classReflection->getName()] = $classReflection;
+            }
         }
     }
 

diff --git a/packages/StringRouting/src/Route/ReflectionRoute.php b/packages/StringRouting/src/Route/ReflectionRoute.php
@@ -17,6 +17,7 @@
 use ApiGen\Reflection\Contract\Reflection\Trait_\TraitReflectionInterface;
 use ApiGen\StringRouting\Contract\Route\RouteInterface;
 use ApiGen\Utils\NamingHelper;
+use Throwable;
 
 final class ReflectionRoute implements RouteInterface
 {
@@ -35,6 +36,10 @@ public function match(string $name): bool
      */
     public function constructUrl($reflection): string
     {
+        if ($reflection instanceof ClassReflectionInterface && $reflection->implementsInterface(Throwable::class)) {
+            return 'exception-' . NamingHelper::nameToFilePath($reflection->getName()) . '.html';
+        }
+
         if ($reflection instanceof ClassReflectionInterface) {
             return 'class-' . NamingHelper::nameToFilePath($reflection->getName()) . '.html';
         }

diff --git a/packages/StringRouting/src/Route/SourceCodeRoute.php b/packages/StringRouting/src/Route/SourceCodeRoute.php
@@ -14,6 +14,7 @@
 use ApiGen\StringRouting\Contract\Route\RouteInterface;
 use ApiGen\Utils\NamingHelper;
 use ApiGen\Utils\RelativePathResolver;
+use Throwable;
 
 final class SourceCodeRoute implements RouteInterface
 {
@@ -43,6 +44,10 @@ public function match(string $name): bool
     public function constructUrl($reflection): string
     {
         # todo: allow Github links, based on configuration
+        if ($reflection instanceof ClassReflectionInterface && $reflection->implementsInterface(Throwable::class)) {
+            return 'source-exception-' . NamingHelper::nameToFilePath($reflection->getName()) . '.html';
+        }
+
         if ($reflection instanceof ClassReflectionInterface) {
             return 'source-class-' . NamingHelper::nameToFilePath($reflection->getName()) . '.html';
         }

diff --git a/packages/StringRouting/tests/Route/ReflectionRouteTest.php b/packages/StringRouting/tests/Route/ReflectionRouteTest.php
@@ -16,6 +16,7 @@
 use ApiGen\StringRouting\Route\ReflectionRoute;
 use ApiGen\StringRouting\StringRouter;
 use ApiGen\Tests\AbstractContainerAwareTestCase;
+use Throwable;
 
 final class ReflectionRouteTest extends AbstractContainerAwareTestCase
 {
@@ -68,6 +69,21 @@ public function provideDataForBuildRoute(): array
         ];
     }
 
+    public function testExceptionReflection(): void
+    {
+        $reflectionExceptionMock = $this->createMock(ClassReflectionInterface::class);
+        $reflectionExceptionMock->method('implementsInterface')
+            ->with(Throwable::class)
+            ->willReturn(true);
+        $reflectionExceptionMock->method('getName')
+            ->willReturn('SomeException');
+
+        $this->assertSame(
+            'exception-SomeException.html',
+            $this->stringRouter->buildRoute(ReflectionRoute::NAME, $reflectionExceptionMock)
+        );
+    }
+
     public function testFunctionUrl(): void
     {
         $reflectionFunctionMock = $this->createMock(FunctionReflectionInterface::class);

diff --git a/packages/ThemeDefault/src/@elementlist.latte b/packages/ThemeDefault/src/@elementlist.latte
@@ -36,3 +36,10 @@
         {include elements, elements => $allFunctions}
     </table>
 {/if}
+
+{if $exceptions}
+    <table class="summary table table-responsive table-bordered table-striped" id="exceptions">
+        <tr><th colspan="2">Exceptions Summary</th></tr>
+        {include elements, elements => $exceptions}
+    </table>
+{/if}
diff --git a/packages/ThemeDefault/src/exceptions.latte b/packages/ThemeDefault/src/exceptions.latte
@@ -0,0 +1,17 @@
+{layout '@layout.latte'}
+
+{block title}{$pageTitle}{/block}
+
+{block content}
+    <h1>{$pageTitle}</h1>
+
+    <table class="summary table table-bordered table-responsive table-striped">
+        {foreach $exceptions as $exception}
+            <tr>
+                <td class="name">
+                    <a href="{$exception|linkReflection}">{$exception->getName()}</a>
+                </td>
+            </tr>
+        {/foreach}
+    </table>
+{/block}
diff --git a/packages/ThemeDefault/src/index.latte b/packages/ThemeDefault/src/index.latte
@@ -19,6 +19,7 @@
     {if count($allNamespaces) <= 1}
         {include '@elementlist.latte',
             "classes" => $allClasses,
+            "exceptions" => $allExceptions,
             "interfaces" => $allInterfaces,
             "traits" => $allTraits,
             "functions" => $allFunctions

diff --git a/packages/ThemeDefault/src/namespace.latte b/packages/ThemeDefault/src/namespace.latte
@@ -27,6 +27,7 @@
 
     {include '@elementlist.latte',
         "classes" => $classes,
+        "exceptions" => $exceptions,
         "intefaces" => $interfaces,
         "traits" => $traits,
         "functions" => $functions

diff --git a/packages/ThemeDefault/src/partial/menu.latte b/packages/ThemeDefault/src/partial/menu.latte
@@ -34,6 +34,12 @@
                             </li>
                         {/if}
 
+                        {if count($allExceptions)}
+                            <li>
+                                <a n:class="$activePage === exceptions ? active" href="exceptions.html">Exceptions</a>
+                            </li>
+                        {/if}
+
                         {foreach $annotationGroups as $annotationGroup}
                             <li class="separator"></li>
                             <li>

diff --git a/src/Console/Progress/StepCounter.php b/src/Console/Progress/StepCounter.php
@@ -30,6 +30,7 @@ public function getStepCount(): int
         return $this->getSourceCodeStepCount()
             + count($this->namespaceReflectionCollector->getNamespaces())
             + count($this->reflectionStorage->getClassReflections())
+            + count($this->reflectionStorage->getExceptionReflections())
             + count($this->reflectionStorage->getTraitReflections())
             + count($this->reflectionStorage->getInterfaceReflections())
             + count($this->reflectionStorage->getFunctionReflections())
@@ -39,6 +40,7 @@ public function getStepCount(): int
     private function getSourceCodeStepCount(): int
     {
         return count($this->reflectionStorage->getClassReflections())
+            + count($this->reflectionStorage->getExceptionReflections())
             + count($this->reflectionStorage->getInterfaceReflections())
             + count($this->reflectionStorage->getTraitReflections())
             + count($this->reflectionStorage->getFunctionReflections());
@@ -51,6 +53,10 @@ private function getOverviewPagesCount(): int
             $count++; // classes.html
         }
 
+        if (count($this->reflectionStorage->getExceptionReflections())) {
+            $count++; // exceptions.html
+        }
+
         if (count($this->reflectionStorage->getInterfaceReflections())) {
             $count++; // interfaces.html
         }

diff --git a/src/EventSubscriber/ElementsTemplateVariablesEventSubscriber.php b/src/EventSubscriber/ElementsTemplateVariablesEventSubscriber.php
@@ -53,6 +53,7 @@ public function loadTemplateVariables(CreateTemplateEvent $createTemplateEvent):
         $parameterBag->addParameters([
             'allNamespaces' => $this->namespaceReflectionCollector->getNamespaces(),
             'allClasses' => $this->reflectionStorage->getClassReflections(),
+            'allExceptions' => $this->reflectionStorage->getExceptionReflections(),
             'allInterfaces' => $this->reflectionStorage->getInterfaceReflections(),
             'allTraits' => $this->reflectionStorage->getTraitReflections(),
             'allFunctions' => $this->reflectionStorage->getFunctionReflections()

diff --git a/src/Generator/EmptyNamespaceGenerator.php b/src/Generator/EmptyNamespaceGenerator.php
@@ -66,6 +66,7 @@ private function generateForNamespace(string $namespace): void
                 'activeNamespace' => $namespace,
                 'childNamespaces' => $this->resolveChildNamespaces($namespace),
                 'classes' => [],
+                'exceptions' => [],
                 'interfaces' => [],
                 'traits' => [],
                 'functions' => [],

diff --git a/src/Generator/ExceptionGenerator.php b/src/Generator/ExceptionGenerator.php
@@ -0,0 +1,82 @@
+<?php declare(strict_types=1);
+
+namespace ApiGen\Generator;
+
+use ApiGen\Configuration\Configuration;
+use ApiGen\Contract\Generator\GeneratorInterface;
+use ApiGen\Reflection\Contract\Reflection\Class_\ClassReflectionInterface;
+use ApiGen\Reflection\ReflectionStorage;
+use ApiGen\SourceCodeHighlighter\SourceCodeHighlighter;
+use ApiGen\Templating\TemplateRenderer;
+
+final class ExceptionGenerator implements GeneratorInterface
+{
+    /**
+     * @var ReflectionStorage
+     */
+    private $reflectionStorage;
+
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    /**
+     * @var SourceCodeHighlighter
+     */
+    private $sourceCodeHighlighter;
+
+    /**
+     * @var TemplateRenderer
+     */
+    private $templateRenderer;
+
+    public function __construct(
+        ReflectionStorage $reflectionStorage,
+        Configuration $configuration,
+        SourceCodeHighlighter $sourceCodeHighlighter,
+        TemplateRenderer $templateRenderer
+    ) {
+        $this->reflectionStorage = $reflectionStorage;
+        $this->configuration = $configuration;
+        $this->sourceCodeHighlighter = $sourceCodeHighlighter;
+        $this->templateRenderer = $templateRenderer;
+    }
+
+    public function generate(): void
+    {
+        foreach ($this->reflectionStorage->getExceptionReflections() as $exceptionReflection) {
+            $this->generateForException($exceptionReflection);
+            $this->generateSourceCodeForException($exceptionReflection);
+        }
+    }
+
+    private function generateForException(ClassReflectionInterface $exceptionReflection): void
+    {
+        $this->templateRenderer->renderToFile(
+            $this->configuration->getTemplateByName('class'),
+            $this->configuration->getDestinationWithPrefixName('exception-', $exceptionReflection->getName()),
+            [
+                'activePage' => 'exception',
+                'class' => $exceptionReflection,
+            ]
+        );
+    }
+
+    private function generateSourceCodeForException(ClassReflectionInterface $exceptionReflection): void
+    {
+        $content = file_get_contents($exceptionReflection->getFileName());
+        $highlightedContent = $this->sourceCodeHighlighter->highlightAndAddLineNumbers($content);
+
+        $this->templateRenderer->renderToFile(
+            $this->configuration->getTemplateByName('source'),
+            $this->configuration->getDestinationWithPrefixName('source-exception-', $exceptionReflection->getName()),
+            [
+                'activePage' => 'class',
+                'activeClass' => $exceptionReflection,
+                'fileName' => $exceptionReflection->getFileName(),
+                'source' => $highlightedContent
+            ]
+        );
+    }
+}
diff --git a/src/Generator/ExceptionsGenerator.php b/src/Generator/ExceptionsGenerator.php
@@ -0,0 +1,58 @@
+<?php declare(strict_types=1);
+
+namespace ApiGen\Generator;
+
+use ApiGen\Configuration\Configuration;
+use ApiGen\Contract\Generator\GeneratorInterface;
+use ApiGen\Reflection\ReflectionStorage;
+use ApiGen\Templating\TemplateRenderer;
+
+final class ExceptionsGenerator implements GeneratorInterface
+{
+    /**
+     * @var string
+     */
+    private const NAME = 'exceptions';
+
+    /**
+     * @var Configuration
+     */
+    private $configuration;
+
+    /**
+     * @var TemplateRenderer
+     */
+    private $templateRenderer;
+
+    /**
+     * @var ReflectionStorage
+     */
+    private $reflectionStorage;
+
+    public function __construct(
+        ReflectionStorage $reflectionStorage,
+        Configuration $configuration,
+        TemplateRenderer $templateRenderer
+    ) {
+        $this->configuration = $configuration;
+        $this->templateRenderer = $templateRenderer;
+        $this->reflectionStorage = $reflectionStorage;
+    }
+
+    public function generate(): void
+    {
+        if (count($this->reflectionStorage->getExceptionReflections()) < 1) {
+            return;
+        }
+
+        $this->templateRenderer->renderToFile(
+            $this->configuration->getTemplateByName(self::NAME),
+            $this->configuration->getDestinationWithName(self::NAME),
+            [
+                'activePage' => self::NAME,
+                'pageTitle' => ucfirst(self::NAME),
+                self::NAME => $this->reflectionStorage->getExceptionReflections()
+            ]
+        );
+    }
+}