Refactor util methods into separate classes

resources/views/components/badges/http-method.blade.php

@@ -1,5 +1,5 @@
 @component('scribe::components.badges.base', [
-    'colour' => \Knuckles\Scribe\Tools\Utils::$httpMethodToCssColour[$method],
+    'colour' => \Knuckles\Scribe\Tools\WritingUtils::$httpMethodToCssColour[$method],
     'text' => $method,
     ])
 @endcomponent

resources/views/partials/example-requests/bash.blade.php

@@ -1,6 +1,6 @@
 ```bash
 curl -X {{$route['methods'][0]}} \
-    {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($route['boundUri'], '/') }}@if(count($route['cleanQueryParameters']))?{!! \Knuckles\Scribe\Tools\Utils::printQueryParamsAsString($route['cleanQueryParameters']) !!}@endif" @if(count($route['headers']))\
+    {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($route['boundUri'], '/') }}@if(count($route['cleanQueryParameters']))?{!! \Knuckles\Scribe\Tools\WritingUtils::printQueryParamsAsString($route['cleanQueryParameters']) !!}@endif" @if(count($route['headers']))\
 @foreach($route['headers'] as $header => $value)
     -H "{{$header}}: {{ addslashes($value) }}"@if(! ($loop->last) || ($loop->last && count($route['bodyParameters']))) \
 @endif

resources/views/partials/example-requests/javascript.blade.php

@@ -4,7 +4,7 @@ const url = new URL(
 );
 @if(count($route['cleanQueryParameters']))
 
-let params = {!! \Knuckles\Scribe\Tools\Utils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "\"", ":", 4, "{}") !!};
+let params = {!! \Knuckles\Scribe\Tools\WritingUtils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "\"", ":", 4, "{}") !!};
 Object.keys(params)
     .forEach(key => url.searchParams.append(key, params[key]));
 @endif

resources/views/partials/example-requests/php.blade.php

@@ -6,13 +6,13 @@ $response = $client->{{ strtolower($route['methods'][0]) }}(
     '{{ rtrim($baseUrl, '/') . '/' . ltrim($route['boundUri'], '/') }}',
     [
 @if(!empty($route['headers']))
-        'headers' => {!! \Knuckles\Scribe\Tools\Utils::printPhpValue($route['headers'], 8) !!},
+        'headers' => {!! \Knuckles\Scribe\Tools\WritingUtils::printPhpArray($route['headers'], 8) !!},
 @endif
 @if(!empty($route['cleanQueryParameters']))
-        'query' => {!! \Knuckles\Scribe\Tools\Utils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "'", "=>", 12, "[]", 8) !!},
+        'query' => {!! \Knuckles\Scribe\Tools\WritingUtils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "'", "=>", 12, "[]", 8) !!},
 @endif
 @if(!empty($route['cleanBodyParameters']))
-        'json' => {!! \Knuckles\Scribe\Tools\Utils::printPhpValue($route['cleanBodyParameters'], 8) !!},
+        'json' => {!! \Knuckles\Scribe\Tools\WritingUtils::printPhpArray($route['cleanBodyParameters'], 8) !!},
 @endif
     ]
 );

resources/views/partials/example-requests/python.blade.php

@@ -7,7 +7,7 @@ url = '{{ rtrim($baseUrl, '/') }}/{{ ltrim($route['boundUri'], '/') }}'
 payload = {!! json_encode($route['cleanBodyParameters'], JSON_PRETTY_PRINT) !!}
 @endif
 @if(count($route['cleanQueryParameters']))
-params = {!! \Knuckles\Scribe\Tools\Utils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "'", ":", 2, "{}") !!}
+params = {!! \Knuckles\Scribe\Tools\WritingUtils::printQueryParamsAsKeyValue($route['cleanQueryParameters'], "'", ":", 2, "{}") !!}
 @endif
 @if(!empty($route['headers']))
 headers = {

src/Commands/GenerateDocumentation.php

@@ -64,8 +64,7 @@ class GenerateDocumentation extends Command
 
         $routes = $routeMatcher->getRoutes($this->docConfig->get('routes'), $this->docConfig->get('router'));
 
-        $generator = new Generator($this->docConfig);
-        $parsedRoutes = $this->processRoutes($generator, $routes);
+        $parsedRoutes = $this->processRoutes($routes);
 
         $groupedRoutes = collect($parsedRoutes)
             ->groupBy('metadata.groupName')
@@ -82,15 +81,15 @@ class GenerateDocumentation extends Command
     }
 
     /**
-     * @param \Knuckles\Scribe\Extracting\Generator $generator
      * @param Match[] $routes
      *
      * @return array
      *@throws \ReflectionException
      *
      */
-    private function processRoutes(Generator $generator, array $routes)
+    private function processRoutes(array $routes)
     {
+        $generator = new Generator($this->docConfig);
         $parsedRoutes = [];
         foreach ($routes as $routeItem) {
             $route = $routeItem->getRoute();
@@ -110,7 +109,7 @@ class GenerateDocumentation extends Command
                 continue;
             }
 
-            if (! $this->isRouteVisibleForDocumentation($routeControllerAndMethod)) {
+            if ($this->isRouteHiddenFromDocumentation($routeControllerAndMethod)) {
                 $this->clara->warn(sprintf($messageFormat, 'Skipping', $routeMethods, $routePath) . ': @hideFromAPIDocumentation was specified.');
                 continue;
             }
@@ -170,7 +169,7 @@ class GenerateDocumentation extends Command
      *
      * @return bool
      */
-    private function isRouteVisibleForDocumentation(array $routeControllerAndMethod)
+    private function isRouteHiddenFromDocumentation(array $routeControllerAndMethod)
     {
         $comment = Utils::reflectRouteMethod($routeControllerAndMethod)->getDocComment();
 

src/Extracting/Strategies/BodyParameters/GetFromFormRequest.php

@@ -14,6 +14,7 @@ use Knuckles\Scribe\Extracting\ParamHelpers;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
 use Knuckles\Scribe\Extracting\ValidationRuleDescriptionParser as Description;
 use Knuckles\Scribe\Tools\Utils;
+use Knuckles\Scribe\Tools\WritingUtils;
 use ReflectionClass;
 use ReflectionException;
 use ReflectionFunctionAbstract;
@@ -320,7 +321,7 @@ class GetFromFormRequest extends Strategy
              */
             case 'in':
                 // Not using the rule description here because it only says "The attribute is invalid"
-                $description = 'The value must be one of '.Utils::getArrayAsFriendlyMarkdownString($arguments);
+                $description = 'The value must be one of '.WritingUtils::getListOfValuesAsFriendlyHtmlString($arguments);
                 $parameterData['description'] .= $description.' ';
                 $parameterData['value'] = Arr::random($arguments);
                 break;

src/Extracting/Strategies/Responses/ResponseCalls.php

@@ -13,6 +13,7 @@ use Illuminate\Support\Str;
 use Knuckles\Scribe\Extracting\DatabaseTransactionHelpers;
 use Knuckles\Scribe\Extracting\ParamHelpers;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
+use Knuckles\Scribe\Tools\ErrorHandlingUtils;
 use Knuckles\Scribe\Tools\Flags;
 use Knuckles\Scribe\Tools\Utils;
 use ReflectionClass;
@@ -71,7 +72,7 @@ class ResponseCalls extends Strategy
         } catch (Exception $e) {
             clara('knuckleswtf/scribe')->warn('Exception thrown during response call for [' . implode(',', $route->methods) . "] {$route->uri}.");
             if (Flags::$shouldBeVerbose) {
-                Utils::dumpException($e);
+                ErrorHandlingUtils::dumpException($e);
             } else {
                 clara('knuckleswtf/scribe')->warn("Run this again with the --verbose flag to see the exception.");
             }

src/Extracting/Strategies/Responses/UseApiResourceTags.php

@@ -16,6 +16,7 @@ use Knuckles\Scribe\Extracting\DatabaseTransactionHelpers;
 use Knuckles\Scribe\Extracting\RouteDocBlocker;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
 use Knuckles\Scribe\Tools\AnnotationParser;
+use Knuckles\Scribe\Tools\ErrorHandlingUtils;
 use Knuckles\Scribe\Tools\Flags;
 use Knuckles\Scribe\Tools\Utils;
 use League\Fractal\Resource\Collection;
@@ -53,7 +54,7 @@ class UseApiResourceTags extends Strategy
         } catch (Exception $e) {
             clara('knuckleswtf/scribe')->warn('Exception thrown when fetching Eloquent API resource response for [' . implode(',', $route->methods) . "] {$route->uri}.");
             if (Flags::$shouldBeVerbose) {
-                Utils::dumpException($e);
+                ErrorHandlingUtils::dumpException($e);
             } else {
                 clara('knuckleswtf/scribe')->warn("Run this again with the --verbose flag to see the exception.");
             }

src/Extracting/Strategies/Responses/UseTransformerTags.php

@@ -11,6 +11,7 @@ use Knuckles\Scribe\Extracting\DatabaseTransactionHelpers;
 use Knuckles\Scribe\Extracting\RouteDocBlocker;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
 use Knuckles\Scribe\Tools\AnnotationParser;
+use Knuckles\Scribe\Tools\ErrorHandlingUtils;
 use Knuckles\Scribe\Tools\Flags;
 use Knuckles\Scribe\Tools\Utils;
 use League\Fractal\Manager;
@@ -50,7 +51,7 @@ class UseTransformerTags extends Strategy
         } catch (Exception $e) {
             clara('knuckleswtf/scribe')->warn('Exception thrown when fetching transformer response for [' . implode(',', $route->methods) . "] {$route->uri}.");
             if (Flags::$shouldBeVerbose) {
-                Utils::dumpException($e);
+                ErrorHandlingUtils::dumpException($e);
             } else {
                 clara('knuckleswtf/scribe')->warn("Run this again with the --verbose flag to see the exception.");
             }

src/Tools/ErrorHandlingUtils.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Knuckles\Scribe\Tools;
+
+use Symfony\Component\Console\Output\ConsoleOutput;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class ErrorHandlingUtils
+{
+    public static function dumpException(\Throwable $e): void
+    {
+        if (!class_exists(\NunoMaduro\Collision\Handler::class)) {
+            dump($e);
+            ConsoleOutputUtils::info("You can get better exception output by installing the library nunomaduro/collision.");
+            return;
+        }
+
+        $output = new ConsoleOutput(OutputInterface::VERBOSITY_VERBOSE);
+        try {
+            $handler = new \NunoMaduro\Collision\Handler(new \NunoMaduro\Collision\Writer(null, $output));
+        } catch (\Exception $e) {
+            // Version 3 used a different API
+            $handler = new \NunoMaduro\Collision\Handler(new \NunoMaduro\Collision\Writer($output));
+        }
+        $handler->setInspector(new \Whoops\Exception\Inspector($e));
+        $handler->setException($e);
+        $handler->handle();
+
+    }
+}

src/Tools/Utils.php

@@ -87,20 +87,6 @@ class Utils
         return $uri;
     }
 
-    public static function dumpException(Exception $e)
-    {
-        if (class_exists(\NunoMaduro\Collision\Handler::class)) {
-            $output = new ConsoleOutput(OutputInterface::VERBOSITY_VERBOSE);
-            $handler = new \NunoMaduro\Collision\Handler(new \NunoMaduro\Collision\Writer($output));
-            $handler->setInspector(new \Whoops\Exception\Inspector($e));
-            $handler->setException($e);
-            $handler->handle();
-        } else {
-            dump($e);
-            clara('knuckleswtf/scribe')->info("You can get better exception output by installing the library nunomaduro/collision.");
-        }
-    }
-
     public static function deleteDirectoryAndContents($dir, $base = null)
     {
         $dir = ltrim($dir, '/');
@@ -109,83 +95,6 @@ class Utils
         $fs->deleteDir($dir);
     }
 
-    /**
-     * @param mixed $value
-     * @param int $indentationLevel
-     *
-     * @return string
-     * @throws \Symfony\Component\VarExporter\Exception\ExceptionInterface
-     *
-     */
-    public static function printPhpValue($value, int $indentationLevel = 0): string
-    {
-        $output = VarExporter::export($value);
-        // Padding with x spaces so they align
-        $split = explode("\n", $output);
-        $result = '';
-        $padWith = str_repeat(' ', $indentationLevel);
-        foreach ($split as $index => $line) {
-            $result .= ($index == 0 ? '' : "\n$padWith") . $line;
-        }
-
-        return $result;
-    }
-
-    public static function printQueryParamsAsString(array $cleanQueryParams): string
-    {
-        $qs = '';
-        foreach ($cleanQueryParams as $parameter => $value) {
-            $paramName = urlencode($parameter);
-
-            if (!is_array($value)) {
-                $qs .= "$paramName=" . urlencode($value) . "&";
-            } else {
-                if (array_keys($value)[0] === 0) {
-                    // List query param (eg filter[]=haha should become "filter[]": "haha")
-                    $qs .= "$paramName" . '[]=' . urlencode($value[0]) . '&';
-                } else {
-                    // Hash query param (eg filter[name]=john should become "filter[name]": "john")
-                    foreach ($value as $item => $itemValue) {
-                        $qs .= "$paramName" . '[' . urlencode($item) . ']=' . urlencode($itemValue) . '&';
-                    }
-                }
-            }
-        }
-
-        return rtrim($qs, '&');
-    }
-
-    public static function printQueryParamsAsKeyValue(
-        array $cleanQueryParams,
-        string $quote = "\"",
-        string $delimiter = ":",
-        int $spacesIndentation = 4,
-        string $braces = "{}",
-        int $closingBraceIndentation = 0
-    ): string {
-        $output = "{$braces[0]}\n";
-        foreach ($cleanQueryParams as $parameter => $value) {
-            if (!is_array($value)) {
-                $output .= str_repeat(" ", $spacesIndentation);
-                $output .= "$quote$parameter$quote$delimiter $quote$value$quote,\n";
-            } else {
-                if (array_keys($value)[0] === 0) {
-                    // List query param (eg filter[]=haha should become "filter[]": "haha")
-                    $output .= str_repeat(" ", $spacesIndentation);
-                    $output .= "$quote$parameter" . "[]$quote$delimiter $quote$value[0]$quote,\n";
-                } else {
-                    // Hash query param (eg filter[name]=john should become "filter[name]": "john")
-                    foreach ($value as $item => $itemValue) {
-                        $output .= str_repeat(" ", $spacesIndentation);
-                        $output .= "$quote$parameter" . "[$item]$quote$delimiter $quote$itemValue$quote,\n";
-                    }
-                }
-            }
-        }
-
-        return $output . str_repeat(" ", $closingBraceIndentation) . "{$braces[1]}";
-    }
-
     /**
      * @param mixed $value
      *
@@ -214,28 +123,4 @@ class Utils
         return (new ReflectionClass($class))->getMethod($method);
     }
 
-    public static $httpMethodToCssColour = [
-        'GET' => 'green',
-        'HEAD' => 'darkgreen',
-        'POST' => 'black',
-        'PUT' => 'darkblue',
-        'PATCH' => 'purple',
-        'DELETE' => 'red',
-    ];
-
-    public static function getArrayAsFriendlyMarkdownString(array $list = []): string
-    {
-        switch (count($list)) {
-            case 1:
-                return "`{$list[0]}`";
-
-            case 2:
-                return "`{$list[0]}` or `{$list[1]}`";
-
-            default:
-                return "`"
-                    . implode('`, `', array_slice($list, 0, -1))
-                    . "`, or `" . end($list) . "`";
-        }
-    }
 }

src/Tools/WritingUtils.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Knuckles\Scribe\Tools;
+
+use Closure;
+use Exception;
+use Illuminate\Routing\Route;
+use League\Flysystem\Adapter\Local;
+use League\Flysystem\Filesystem;
+use ReflectionClass;
+use ReflectionException;
+use ReflectionFunction;
+use ReflectionFunctionAbstract;
+use Symfony\Component\Console\Output\ConsoleOutput;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\VarExporter\VarExporter;
+
+class WritingUtils
+{
+    /**
+     * @param array $value
+     * @param int $indentationLevel
+     *
+     * @return string
+     * @throws \Symfony\Component\VarExporter\Exception\ExceptionInterface
+     *
+     */
+    public static function printPhpArray(array $value, int $indentationLevel = 0): string
+    {
+        $output = VarExporter::export($value);
+        // Padding with x spaces so they align
+        $split = explode("\n", $output);
+        $result = '';
+        $padWith = str_repeat(' ', $indentationLevel);
+        foreach ($split as $index => $line) {
+            $result .= ($index == 0 ? '' : "\n$padWith") . $line;
+        }
+
+        return $result;
+    }
+
+    public static function printQueryParamsAsString(array $cleanQueryParams): string
+    {
+        $qs = '';
+        foreach ($cleanQueryParams as $parameter => $value) {
+            $paramName = urlencode($parameter);
+
+            if (!is_array($value)) {
+                $qs .= "$paramName=" . urlencode($value) . "&";
+            } else {
+                if (array_keys($value)[0] === 0) {
+                    // List query param (eg filter[]=haha should become "filter[]": "haha")
+                    $qs .= "$paramName" . '[]=' . urlencode($value[0]) . '&';
+                } else {
+                    // Hash query param (eg filter[name]=john should become "filter[name]": "john")
+                    foreach ($value as $item => $itemValue) {
+                        $qs .= "$paramName" . '[' . urlencode($item) . ']=' . urlencode($itemValue) . '&';
+                    }
+                }
+            }
+        }
+
+        return rtrim($qs, '&');
+    }
+
+    public static function printQueryParamsAsKeyValue(
+        array $cleanQueryParams,
+        string $quote = "\"",
+        string $delimiter = ":",
+        int $spacesIndentation = 4,
+        string $braces = "{}",
+        int $closingBraceIndentation = 0
+    ): string {
+        $output = "{$braces[0]}\n";
+        foreach ($cleanQueryParams as $parameter => $value) {
+            if (!is_array($value)) {
+                $output .= str_repeat(" ", $spacesIndentation);
+                $output .= "$quote$parameter$quote$delimiter $quote$value$quote,\n";
+            } else {
+                if (array_keys($value)[0] === 0) {
+                    // List query param (eg filter[]=haha should become "filter[]": "haha")
+                    $output .= str_repeat(" ", $spacesIndentation);
+                    $output .= "$quote$parameter" . "[]$quote$delimiter $quote$value[0]$quote,\n";
+                } else {
+                    // Hash query param (eg filter[name]=john should become "filter[name]": "john")
+                    foreach ($value as $item => $itemValue) {
+                        $output .= str_repeat(" ", $spacesIndentation);
+                        $output .= "$quote$parameter" . "[$item]$quote$delimiter $quote$itemValue$quote,\n";
+                    }
+                }
+            }
+        }
+
+        return $output . str_repeat(" ", $closingBraceIndentation) . "{$braces[1]}";
+    }
+
+    public static $httpMethodToCssColour = [
+        'GET' => 'green',
+        'HEAD' => 'darkgreen',
+        'POST' => 'black',
+        'PUT' => 'darkblue',
+        'PATCH' => 'purple',
+        'DELETE' => 'red',
+    ];
+
+    /**
+     * Convert a list of possible values to a friendly string:
+     * [1, 2, 3] -> "1, 2, or 3"
+     * [1, 2] -> "1 or 2"
+     * [1] -> "1"
+     * Each value is wrapped in HTML <code> tags, so you actually get "<code>1</code>, <code>2</code>, or <code>3</code>"
+     *
+     * @param array $list
+     *
+     * @return string
+     */
+    public static function getListOfValuesAsFriendlyHtmlString(array $list = []): string
+    {
+        switch (count($list)) {
+            case 1:
+                return "<code>{$list[0]}</code>";
+
+            case 2:
+                return "<code>{$list[0]}</code> or <code>{$list[1]}</code>";
+
+            default:
+                return "<code>"
+                    . implode('</code>, <code>', array_slice($list, 0, -1))
+                    . "</code>, or <code>" . end($list) . "</code>";
+        }
+    }
+}