fix: doc generation on windows

resolve #8

Author: Mohammad-Alavi

Tasks/RenderApidocJsonTask.php

@@ -2,16 +2,15 @@
 
 namespace App\Containers\Vendor\Documentation\Tasks;
 
-use App\Containers\Vendor\Documentation\Traits\DocsGeneratorTrait;
 use Apiato\Core\Abstracts\Tasks\Task as AbstractTask;
+use App\Containers\Vendor\Documentation\Traits\DocsGeneratorTrait;
 
 class RenderApidocJsonTask extends AbstractTask
 {
     use DocsGeneratorTrait;
 
     private string $templatePath;
     private string $outputPath;
-    // ['templateKey' => value]
     private array $replaceArray;
 
     public function __construct(string $docType)
@@ -39,22 +38,24 @@ private function prepareUrlPrefix(): string
 
     /**
      * Read the markdown header template and fill it with some real data from the .env file.
+     *
+     * @throws \JsonException
      */
     public function run(): string
     {
         // read the template file
         $jsonContent = file_get_contents($this->templatePath);
 
-        //Decode the JSON data into a PHP array.
-        $contentsDecoded = json_decode($jsonContent, true);
+        // decode the JSON data into a PHP array.
+        $contentsDecoded = json_decode($jsonContent, true, 512, JSON_THROW_ON_ERROR);
 
-        //Modify the variables.
+        // modify the variables.
         foreach ($this->replaceArray as $key => $value) {
             $contentsDecoded[$key] = $value;
         }
 
-        //Encode the array back into a JSON string.
-        $jsonContent = json_encode($contentsDecoded);
+        // encode the array back into a JSON string.
+        $jsonContent = json_encode($contentsDecoded, JSON_THROW_ON_ERROR);
 
         // this is what the apidoc.json file will point to, to load the header.md
         // write the actual file
@@ -63,17 +64,24 @@ public function run(): string
         return $this->outputPath;
     }
 
-    // File put contents fails if you try to put a file in a directory that doesn't exist.
-    // This creates the directory.
-    private function fileForceContents($dir, $contents): void
+    // file_put_contents() fails if you try to put a file in a directory that doesn't exist.
+    // this creates the directory if it doesn't exist.
+    private function fileForceContents(string $dir, string $contents): void
     {
         $parts = explode('/', $dir);
         $file = array_pop($parts);
         $dir = '';
 
-        foreach ($parts as $part)
-            if (!is_dir($dir .= "/$part")) mkdir($dir);
+        foreach ($parts as $key => $part) {
+            if ($key === 0) {
+                continue;
+            }
 
-        file_put_contents("$dir/$file", $contents);
+            $dir .= "/{$part}";
+            if (!is_dir($dir) && !mkdir($dir)) {
+                throw new \RuntimeException(sprintf('Directory "%s" was not created', $dir));
+            }
+        }
+        file_put_contents("{$dir}/{$file}", $contents);
     }
 }

Traits/DocsGeneratorTrait.php

@@ -4,24 +4,22 @@
 
 trait DocsGeneratorTrait
 {
-    private function getFullDocsUrl($type): string
+    private function getFullDocsUrl(string $type): string
     {
         return '> ' . $this->getAppUrl() . '/' . $this->getUrl($type);
     }
 
-    private function getAppUrl()
+    private function getAppUrl(): string
     {
         return config('app.url');
     }
 
-    private function getUrl($type)
+    private function getUrl(string $type): string
     {
-        $configs = $this->getTypeConfigs();
-
-        return $configs[$type]['url'];
+        return $this->getTypeConfigs()[$type]['url'];
     }
 
-    private function getTypeConfigs()
+    private function getTypeConfigs(): array
     {
         return config($this->getConfigFile() . '.types');
     }
@@ -31,24 +29,22 @@ private function getConfigFile(): string
         return 'vendor-documentation';
     }
 
-    private function getDocumentationPath($type): string
+    private function getDocumentationPath(string $type): string
     {
         return $this->getHtmlPath() . $this->getFolderName($type);
     }
 
-    private function getHtmlPath()
+    private function getHtmlPath(): string
     {
         return config("{$this->getConfigFile()}.html_files");
     }
 
-    private function getFolderName($type)
+    private function getFolderName(string $type): string
     {
-        $configs = $this->getTypeConfigs();
-
-        return $configs[$type]['folder-name'];
+        return $this->getTypeConfigs()[$type]['folder-name'];
     }
 
-    private function getJsonFilePath($type): string
+    private function getJsonFilePath(string $type): string
     {
         return $this->getApiDocJsConfigsPath() . '/' . $this->getJsonFileName($type);
     }
@@ -63,23 +59,20 @@ private function getPathInDocumentationContainer(string $path): string
         return app_path('Containers/' . config('vendor-documentation.section_name') . '/Documentation' . $path);
     }
 
-    private function getJsonFileName($type): string
+    private function getJsonFileName(string $type): string
     {
         return 'apidoc.' . $type . '.json';
     }
 
-    private function getExecutable()
+    private function getExecutable(): string
     {
         return config($this->getConfigFile() . '.executable');
     }
 
-    private function getEndpointFiles($type): array
+    private function getEndpointFiles(string $type): array
     {
-        $configs = $this->getTypeConfigs();
-
-        // what files types needs to be included
         $routeFilesCommand = [];
-        $routes = $configs[$type]['routes'];
+        $routes = $this->getTypeConfigs()[$type]['routes'];
 
         foreach ($routes as $route) {
             $routeFilesCommand[] = '-f';