Clean up

camel/Camel.php

@@ -13,14 +13,14 @@
 
 class Camel
 {
-    public static function cacheDir(PathConfig $pathConfiguration): string
+    public static function cacheDir(PathConfig $paths): string
     {
-        return $pathConfiguration->getTemporaryDirectoryPath('endpoints.cache');
+        return $paths->intermediateOutputPath('endpoints.cache');
     }
 
-    public static function camelDir(PathConfig $pathConfiguration): string
+    public static function camelDir(PathConfig $paths): string
     {
-        return $pathConfiguration->getTemporaryDirectoryPath('endpoints');
+        return $paths->intermediateOutputPath('endpoints');
     }
 
     /**

src/Commands/GenerateDocumentation.php

@@ -25,7 +25,7 @@ class GenerateDocumentation extends Command
                             {--no-extraction : Skip extraction of route and API info and just transform the YAML and Markdown files into HTML}
                             {--no-upgrade-check : Skip checking for config file upgrades. Won't make things faster, but can be helpful if the command is buggy}
                             {--config=scribe : choose which config file to use}
-                            {--cache-directory= : choose which cache directory to use}
+                            {--cache-dir= : choose which cache directory to use}
     ";
 
     protected $description = 'Generate API documentation from your Laravel/Dingo routes.';
@@ -36,8 +36,7 @@ class GenerateDocumentation extends Command
 
     protected bool $forcing;
 
-    /** @var PathConfig  */
-    protected PathConfig $pathConfiguration;
+    protected PathConfig $paths;
 
     public function handle(RouteMatcherInterface $routeMatcher, GroupedEndpointsFactory $groupedEndpointsFactory): void
     {
@@ -50,9 +49,9 @@ public function handle(RouteMatcherInterface $routeMatcher, GroupedEndpointsFact
         }
 
         // Extraction stage - extract endpoint info either from app or existing Camel files (previously extracted data)
-        $groupedEndpointsInstance = $groupedEndpointsFactory->make($this, $routeMatcher, $this->pathConfiguration);
+        $groupedEndpointsInstance = $groupedEndpointsFactory->make($this, $routeMatcher, $this->paths);
         $extractedEndpoints = $groupedEndpointsInstance->get();
-        $userDefinedEndpoints = Camel::loadUserDefinedEndpoints(Camel::camelDir($this->pathConfiguration));
+        $userDefinedEndpoints = Camel::loadUserDefinedEndpoints(Camel::camelDir($this->paths));
         $groupedEndpoints = $this->mergeUserDefinedEndpoints($extractedEndpoints, $userDefinedEndpoints);
 
         // Output stage
@@ -64,7 +63,7 @@ public function handle(RouteMatcherInterface $routeMatcher, GroupedEndpointsFact
             $this->writeExampleCustomEndpoint();
         }
 
-        $writer = new Writer($this->docConfig, $this->pathConfiguration);
+        $writer = new Writer($this->docConfig, $this->paths);
         $writer->writeDocs($groupedEndpoints);
 
         $this->upgradeConfigFileIfNeeded();
@@ -106,12 +105,14 @@ public function bootstrap(): void
             throw new \InvalidArgumentException("The specified config (config/{$configName}.php) doesn't exist.");
         }
 
-        $this->pathConfiguration = new PathConfig($configName, $configName, true);
-        if ($this->hasOption('cache-directory') && !empty($this->option('cache-directory'))) {
-            $this->pathConfiguration = new PathConfig($this->option('cache-directory'), $configName, false);
+        $this->paths = new PathConfig(configName: $configName);
+        if ($this->hasOption('cache-dir') && !empty($this->option('cache-dir'))) {
+            $this->paths = new PathConfig(
+                configName: $configName, cacheDir: $this->option('cache-dir')
+            );
         }
 
-        $this->docConfig = new DocumentationConfig(config($this->pathConfiguration->getScribeConfigurationPath()));
+        $this->docConfig = new DocumentationConfig(config($this->paths->configName));
 
         // Force root URL so it works in Postman collection
         $baseUrl = $this->docConfig->get('base_url') ?? config('app.url');
@@ -154,7 +155,7 @@ protected function mergeUserDefinedEndpoints(array $groupedEndpoints, array $use
     protected function writeExampleCustomEndpoint(): void
     {
         // We add an example to guide users in case they need to add a custom endpoint.
-        copy(__DIR__ . '/../../resources/example_custom_endpoint.yaml', Camel::camelDir($this->pathConfiguration) . '/custom.0.yaml');
+        copy(__DIR__ . '/../../resources/example_custom_endpoint.yaml', Camel::camelDir($this->paths) . '/custom.0.yaml');
     }
 
     protected function upgradeConfigFileIfNeeded(): void
@@ -163,12 +164,18 @@ protected function upgradeConfigFileIfNeeded(): void
 
         $this->info("Checking for any pending upgrades to your config file...");
         try {
-            if (! $this->laravel['files']->exists($this->laravel->configPath($this->pathConfiguration->getScribeConfigurationPath('php', '.')))) {
+            if (!$this->laravel['files']->exists(
+                $this->laravel->configPath($this->paths->configFileName())
+            )
+            ) {
                 $this->info("No config file to upgrade.");
                 return;
             }
 
-            $upgrader = Upgrader::ofConfigFile("config/" . $this->pathConfiguration->getScribeConfigurationPath('php', '.'), __DIR__ . '/../../config/scribe.php')
+            $upgrader = Upgrader::ofConfigFile(
+                userOldConfigRelativePath: "config/{$this->paths->configFileName()}",
+                sampleNewConfigAbsolutePath: __DIR__ . '/../../config/scribe.php'
+            )
                 ->dontTouch(
                     'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware',
                     'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source'

src/Commands/Upgrade.php

@@ -103,7 +103,7 @@ protected function migrateToConfigFileSort()
         $this->info("We'll automatically import your current sorting into the config item `groups.order`.");
 
         $defaultGroup = config($this->configName.".default_group");
-        $pathConfig = new PathConfig($this->configName, $this->configName, true);
+        $pathConfig = new PathConfig($this->configName);
         $extractedEndpoints = GroupedEndpointsFactory::fromCamelDir($pathConfig)->get();
 
         $order = array_map(function (array $group) {

src/Configuration/PathConfig.php

@@ -3,62 +3,43 @@
 namespace Knuckles\Scribe\Configuration;
 
 /**
- * A home for path configurations.
+ * A home for path configurations. The important paths Scribe depends on.
  */
 class PathConfig
 {
-    /** @var string */
-    private string $scribeConfig;
-
-    /** @var string */
-    private string $cacheDir;
-
-    /** @var bool */
-    private bool $isHidden;
-
-    /**
-     * @param string $cacheDir
-     * @param string $scribeConfig
-     * @param bool $isHidden
-     */
-    public function __construct(string $cacheDir, string $scribeConfig, bool $isHidden = true)
+    public function __construct(
+        public string     $configName = 'scribe',
+        protected ?string $cacheDir = null
+    )
     {
-        $this->cacheDir = $cacheDir;
-        $this->scribeConfig = $scribeConfig;
-        $this->isHidden = $isHidden;
+        if (is_null($this->cacheDir)) {
+            $this->cacheDir = ".{$this->configName}";
+        }
     }
 
-    /**
-     * Path to the scribe.php (default) or otherwise named configuration file.
-     *
-     * @param string|null $resolvePath
-     * @param string $separator
-     * @return string
-     */
-    public function getScribeConfigurationPath(string $resolvePath = null, string $separator = '/'): string
+    public function outputPath(string $resolvePath = null, string $separator = '/'): string
     {
         if (is_null($resolvePath)) {
-            return $this->scribeConfig;
+            return $this->configName;
         }
-        // Separate the path with a / (default) or an override via $separator
-        return sprintf("%s%s%s", $this->scribeConfig, $separator, $resolvePath);
+
+        return "{$this->configName}{$separator}{$resolvePath}";
+    }
+
+    public function configFileName(): string
+    {
+        return "{$this->configName}.php";
     }
 
     /**
-     * Get the path to the .scribe (default) or otherwise named temporary file path.
-     *
-     * @param string|null $resolvePath
-     * @param string $separator
-     * @return string
+     * The directory where Scribe writes its intermediate output (default is .<config> ie .scribe)
      */
-    public function getTemporaryDirectoryPath(string $resolvePath = null, string $separator = '/'): string
+    public function intermediateOutputPath(string $resolvePath = null, string $separator = '/'): string
     {
-        $path = ($this->isHidden ? '.' : '') . $this->cacheDir;
         if (is_null($resolvePath)) {
-            return $path;
+            return $this->cacheDir;
         }
-        // Separate the path with a / (default) or an override via $separator
-        return sprintf("%s%s%s", $path, $separator, $resolvePath);
 
+        return "{$this->cacheDir}{$separator}{$resolvePath}";
     }
 }

src/Extracting/ApiDetails.php

@@ -24,19 +24,14 @@ class ApiDetails
 
     private array $lastKnownFileContentHashes = [];
 
-    /**
-     * @param PathConfig $pathConfig
-     * @param DocumentationConfig|null $config
-     * @param bool $preserveUserChanges
-     */
     public function __construct(
-        PathConfig          $pathConfig,
+        PathConfig          $paths,
         DocumentationConfig $config = null,
         bool                $preserveUserChanges = true
     ) {
-        $this->markdownOutputPath = $pathConfig->getTemporaryDirectoryPath(); //.scribe by default
+        $this->markdownOutputPath = $paths->intermediateOutputPath(); //.scribe by default
         // If no config is injected, pull from global. Makes testing easier.
-        $this->config = $config ?: new DocumentationConfig(config($pathConfig->getScribeConfigurationPath()));
+        $this->config = $config ?: new DocumentationConfig(config($paths->configName));
         $this->baseUrl = $this->config->get('base_url') ?? config('app.url');
         $this->preserveUserChanges = $preserveUserChanges;
 

src/GroupedEndpoints/GroupedEndpointsFactory.php

@@ -8,50 +8,43 @@
 
 class GroupedEndpointsFactory
 {
-    /**
-     * @param GenerateDocumentation $command
-     * @param RouteMatcherInterface $routeMatcher
-     * @param PathConfig $pathConfig
-     * @return GroupedEndpointsContract
-     */
     public function make(
         GenerateDocumentation $command,
         RouteMatcherInterface $routeMatcher,
-        PathConfig $pathConfig
+        PathConfig $paths
     ): GroupedEndpointsContract {
         if ($command->isForcing()) {
-            return static::fromApp($command, $routeMatcher, false, $pathConfig);
+            return static::fromApp(
+                command: $command,
+                routeMatcher: $routeMatcher,
+                preserveUserChanges: false,
+                paths: $paths
+            );
         }
 
         if ($command->shouldExtract()) {
-            return static::fromApp($command, $routeMatcher, true, $pathConfig);
+            return static::fromApp(
+                command: $command,
+                routeMatcher: $routeMatcher,
+                preserveUserChanges: true,
+                paths: $paths
+            );
         }
 
-        return static::fromCamelDir($pathConfig);
+        return static::fromCamelDir($paths);
     }
 
-    /**
-     * @param GenerateDocumentation $command
-     * @param RouteMatcherInterface $routeMatcher
-     * @param bool $preserveUserChanges
-     * @param PathConfig $pathConfig
-     * @return GroupedEndpointsFromApp
-     */
     public static function fromApp(
         GenerateDocumentation $command,
         RouteMatcherInterface $routeMatcher,
         bool $preserveUserChanges,
-        PathConfig $pathConfig
+        PathConfig $paths
     ): GroupedEndpointsFromApp {
-        return new GroupedEndpointsFromApp($command, $routeMatcher, $pathConfig, $preserveUserChanges);
+        return new GroupedEndpointsFromApp($command, $routeMatcher, $paths, $preserveUserChanges);
     }
 
-    /**
-     * @param PathConfig $pathConfig
-     * @return GroupedEndpointsFromCamelDir
-     */
-    public static function fromCamelDir(PathConfig $pathConfig): GroupedEndpointsFromCamelDir
+    public static function fromCamelDir(PathConfig $paths): GroupedEndpointsFromCamelDir
     {
-        return new GroupedEndpointsFromCamelDir($pathConfig);
+        return new GroupedEndpointsFromCamelDir($paths);
     }
 }

src/GroupedEndpoints/GroupedEndpointsFromApp.php

@@ -34,22 +34,16 @@ class GroupedEndpointsFromApp implements GroupedEndpointsContract
     public static string $camelDir;
     public static string $cacheDir;
 
-    /**
-     * @param GenerateDocumentation $command
-     * @param RouteMatcherInterface $routeMatcher
-     * @param PathConfig $pathConfiguration
-     * @param bool $preserveUserChanges
-     */
     public function __construct(
         private GenerateDocumentation $command,
         private RouteMatcherInterface $routeMatcher,
-        protected PathConfig $pathConfiguration,
+        protected PathConfig $paths,
         private bool $preserveUserChanges = true
     ) {
         $this->docConfig = $command->getDocConfig();
 
-        static::$camelDir = Camel::camelDir($this->pathConfiguration);
-        static::$cacheDir = Camel::cacheDir($this->pathConfiguration);
+        static::$camelDir = Camel::camelDir($this->paths);
+        static::$cacheDir = Camel::cacheDir($this->paths);
     }
 
     public function get(): array
@@ -290,7 +284,7 @@ protected function extractAndWriteApiDetailsToDisk(): void
 
     protected function makeApiDetails(): ApiDetails
     {
-        return new ApiDetails($this->pathConfiguration, $this->docConfig, !$this->command->option('force'));
+        return new ApiDetails($this->paths, $this->docConfig, !$this->command->option('force'));
     }
 
     /**

src/GroupedEndpoints/GroupedEndpointsFromCamelDir.php

@@ -7,22 +7,20 @@
 
 class GroupedEndpointsFromCamelDir implements GroupedEndpointsContract
 {
-    protected PathConfig $pathConfig;
 
-    public function __construct(PathConfig $pathConfig)
+    public function __construct(protected PathConfig $paths)
     {
-        $this->pathConfig = $pathConfig;
     }
 
     public function get(): array
     {
-        if (!is_dir(Camel::camelDir($this->pathConfig))) {
+        if (!is_dir(Camel::camelDir($this->paths))) {
             throw new \InvalidArgumentException(
-                "Can't use --no-extraction because there are no endpoints in the " . Camel::camelDir($this->pathConfig) . " directory."
+                "Can't use --no-extraction because there are no endpoints in the " . Camel::camelDir($this->paths) . " directory."
             );
         }
 
-        return Camel::loadEndpointsIntoGroups(Camel::camelDir($this->pathConfig));
+        return Camel::loadEndpointsIntoGroups(Camel::camelDir($this->paths));
     }
 
     public function hasEncounteredErrors(): bool