Merge pull request #362 from hydephp/351-allow-site-output-directory-…

…to-be-customized

Allow site output directory to be customized

config/hyde.php

@@ -222,8 +222,26 @@
     |
     */
 
+    /**
+     * @deprecated version 0.25.0, will be renamed to documentationOutputPath
+     */
     'docsDirectory' => 'docs',
 
+    /*
+    |--------------------------------------------------------------------------
+    | Site Output Directory (Experimental 🧪)
+    |--------------------------------------------------------------------------
+    |
+    | If you want to store your compiled website in a different directory than
+    | the default `_pages`, you can change the path here. The Hyde::path()
+    | helper ensures the path is relative to your Hyde project. While
+    | you can set the path to an absolute path outside the project,
+    | this is not officially supported and may be unstable.
+    |
+    */
+
+    'siteOutputPath' => Hyde\Framework\Hyde::path('_site'),
+
     /*
     |--------------------------------------------------------------------------
     | Documentation Sidebar Page Order

src/Commands/HydeBuildStaticSiteCommand.php

@@ -21,6 +21,8 @@
  * Hyde Command to run the Build Process.
  *
  * @see \Tests\Feature\Commands\BuildStaticSiteCommandTest
+ *
+ * @todo #361 Rename --pretty option to --run-prettier to distinguish it better
  */
 class HydeBuildStaticSiteCommand extends Command
 {
@@ -119,21 +121,21 @@ protected function printFinishMessage(float $time_start): void
         $this->info('Congratulations! 🎉 Your static site has been built!');
         $this->line(
             'Your new homepage is stored here -> '.
-                DiscoveryService::createClickableFilepath(Hyde::path('_site/index.html'))
+                DiscoveryService::createClickableFilepath(Hyde::getSiteOutputPath('index.html'))
         );
     }
 
     /**
-     * Clear the entire _site directory before running the build.
+     * Clear the entire output directory before running the build.
      *
      * @return void
      */
     public function purge(): void
     {
         $this->warn('Removing all files from build directory.');
 
-        File::deleteDirectory(Hyde::path('_site'));
-        mkdir(Hyde::path('_site'));
+        File::deleteDirectory(Hyde::getSiteOutputPath());
+        mkdir(Hyde::getSiteOutputPath());
 
         $this->line('<fg=gray> > Directory purged');
 
@@ -146,13 +148,15 @@ public function purge(): void
     /**
      * Run any post-build actions.
      *
+     * @todo #363 Add unit test for prettier command (can work by comparing compiled baseline to output to see if it was prettified);
+     *
      * @return void
      */
     public function postBuildActions(): void
     {
         if ($this->option('pretty')) {
             $this->runNodeCommand(
-                'npx prettier _site/ --write --bracket-same-line',
+                'npx prettier '.Hyde::pathToRelative(Hyde::getSiteOutputPath($path)).'/ --write --bracket-same-line',
                 'Prettifying code!',
                 'prettify code'
             );

src/Commands/HydeRebuildStaticSiteCommand.php

@@ -97,10 +97,11 @@ public function sanitizePathString(string $path): string
      */
     public function validate(): void
     {
-        if (! (str_starts_with($this->path, '_docs') ||
-            str_starts_with($this->path, '_posts') ||
-            str_starts_with($this->path, '_pages') ||
-            str_starts_with($this->path, '_pages')
+        if (! (
+            str_starts_with($this->path, Hyde::pathToRelative(Hyde::getDocumentationPagePath())) ||
+            str_starts_with($this->path, Hyde::pathToRelative(Hyde::getMarkdownPostPath())) ||
+            str_starts_with($this->path, Hyde::pathToRelative(Hyde::getBladePagePath())) ||
+            str_starts_with($this->path, Hyde::pathToRelative(Hyde::getMarkdownPostPath()))
         )) {
             throw new Exception("Path [$this->path] is not in a valid source directory.", 400);
         }
@@ -126,6 +127,9 @@ public function handleException(Exception $exception): int
 
     /**
      * Get the output path for the given source file path.
+     * Will fall back to the input path when using non-standard source paths.
+     *
+     * @deprecated, reimplementing path information in StaticPageBuilder
      *
      * @param  string  $path
      * @return string

src/Concerns/InteractsWithDirectories.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Hyde\Framework\Concerns;
+
+/**
+ * @see \Tests\Unit\InteractsWithDirectoriesConcernTest
+ */
+trait InteractsWithDirectories
+{
+    /**
+     * Ensure the supplied directory exist by creating it if it does not.
+     *
+     * @param  string  $directory  absolute file path to the directory
+     */
+    public function needsDirectory(string $directory): void
+    {
+        if (! file_exists($directory)) {
+            mkdir($directory, recursive: true);
+        }
+    }
+
+    /**
+     * Ensure the supplied directories exist by creating them if they don't.
+     *
+     * @param  array  $directories  array with absolute file paths to the directories
+     */
+    public function needsDirectories(array $directories): void
+    {
+        foreach ($directories as $directory) {
+            $this->needsDirectory($directory);
+        }
+    }
+}

src/Concerns/Internal/FileHelpers.php

@@ -15,6 +15,12 @@ trait FileHelpers
     /**
      * Get the subdirectory compiled documentation files are stored in.
      *
+     * @deprecated will be renamed to be more distinct from other path helpers.
+     *              Naming suggestion is `getDocumentationOutputPath()`.
+     *              The configuration is deprecated as well and will be renamed.
+     *
+     * @todo Test and if needed add support for storing documentation files in the site root
+     *
      * @return string
      */
     public static function docsDirectory(): string
@@ -101,7 +107,7 @@ public static function pageLink(string $destination): string
      *
      * @see \Tests\Unit\FileHelperRelativeLinkTest
      *
-     * @param  string  $destination  relative to `_site` directory on compiled site
+     * @param  string  $destination  relative to output directory on compiled site
      * @param  string  $current  the current URI path relative to the same root
      * @return string
      */

src/Concerns/Internal/SourcePathHelpers.php → src/Concerns/Internal/FluentPathHelpers.php

@@ -7,6 +7,7 @@
 use Hyde\Framework\Models\MarkdownPage;
 use Hyde\Framework\Models\MarkdownPost;
 use Hyde\Framework\Services\DiscoveryService;
+use Hyde\Framework\StaticPageBuilder;
 
 /**
  * Offloads file helper methods for the Hyde Facade.
@@ -18,10 +19,21 @@
  * Hyde::path('_pages/foo') becomes Hyde::getBladePagePath('foo')
  *
  * @see \Hyde\Framework\Hyde
- * @see \Tests\Unit\SourcePathHelpersTest
+ * @see \Tests\Unit\FluentPathHelpersTest
  */
-trait SourcePathHelpers
+trait FluentPathHelpers
 {
+    public static function getModelSourcePath(string $model, string $path = ''): string
+    {
+        if (empty($path)) {
+            return static::path(DiscoveryService::getFilePathForModelClassFiles($model));
+        }
+
+        $path = trim($path, '/\\');
+
+        return static::path(DiscoveryService::getFilePathForModelClassFiles($model).DIRECTORY_SEPARATOR.$path);
+    }
+
     public static function getBladePagePath(string $path = ''): string
     {
         return static::getModelSourcePath(BladePage::class, $path);
@@ -42,14 +54,27 @@ public static function getDocumentationPagePath(string $path = ''): string
         return static::getModelSourcePath(DocumentationPage::class, $path);
     }
 
-    public static function getModelSourcePath(string $model, string $path = ''): string
+    /**
+     * Get the absolute path to the compiled site directory, or a file within it.
+     */
+    public static function getSiteOutputPath(string $path = ''): string
     {
         if (empty($path)) {
-            return static::path(DiscoveryService::getFilePathForModelClassFiles($model));
+            return StaticPageBuilder::$outputPath;
         }
 
         $path = trim($path, '/\\');
 
-        return static::path(DiscoveryService::getFilePathForModelClassFiles($model).DIRECTORY_SEPARATOR.$path);
+        return StaticPageBuilder::$outputPath.DIRECTORY_SEPARATOR.$path;
+    }
+
+    /**
+     * Decode an absolute path created with a Hyde::path() helper into its relative counterpart.
+     */
+    public static function pathToRelative(string $path): string
+    {
+        return str_starts_with($path, static::path()) ? trim(str_replace(
+            static::path(), '', $path), '/\\'
+        ) : $path;
     }
 }

src/Concerns/Internal/TransfersMediaAssetsForBuildCommands.php

@@ -2,6 +2,7 @@
 
 namespace Hyde\Framework\Concerns\Internal;
 
+use Hyde\Framework\Concerns\InteractsWithDirectories;
 use Hyde\Framework\Hyde;
 use Hyde\Framework\Services\CollectionService;
 
@@ -16,16 +17,19 @@
 trait TransfersMediaAssetsForBuildCommands
 {
     use BuildActionRunner;
+    use InteractsWithDirectories;
 
     /** @internal */
     protected function transferMediaAssets(): void
     {
+        $this->needsDirectory(Hyde::getSiteOutputPath('media'));
+
         $collection = CollectionService::getMediaAssetFiles();
         if ($this->canRunBuildAction($collection, 'Media Assets', 'Transferring')) {
             $this->withProgressBar(
                 $collection,
                 function ($filepath) {
-                    copy($filepath, Hyde::path('_site/media/'.basename($filepath)));
+                    copy($filepath, Hyde::getSiteOutputPath('media/'.basename($filepath)));
                 }
             );
             $this->newLine(2);

src/Hyde.php

@@ -5,7 +5,7 @@
 use Composer\InstalledVersions;
 use Hyde\Framework\Concerns\Internal\AssetManager;
 use Hyde\Framework\Concerns\Internal\FileHelpers;
-use Hyde\Framework\Concerns\Internal\SourcePathHelpers;
+use Hyde\Framework\Concerns\Internal\FluentPathHelpers;
 use Hyde\Framework\Services\CollectionService;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Str;
@@ -23,7 +23,7 @@ class Hyde
 {
     use FileHelpers;
     use AssetManager;
-    use SourcePathHelpers;
+    use FluentPathHelpers;
 
     protected static string $basePath;
 

src/HydeServiceProvider.php

@@ -54,6 +54,10 @@ function () {
 
         $this->discoverBladeViewsIn('_pages');
 
+        $this->storeCompiledSiteIn(config(
+            'hyde.siteOutputPath', Hyde::path('_site')
+        ));
+
         $this->commands([
             Commands\HydePublishHomepageCommand::class,
             Commands\HydeUpdateConfigsCommand::class,
@@ -111,4 +115,12 @@ protected function discoverBladeViewsIn(string $directory): void
             [base_path($directory)]
         )]);
     }
+
+    /**
+     * The absolute path to the directory when the compiled site is stored.
+     */
+    protected function storeCompiledSiteIn(string $directory): void
+    {
+        StaticPageBuilder::$outputPath = $directory;
+    }
 }

src/StaticPageBuilder.php

@@ -3,6 +3,7 @@
 namespace Hyde\Framework;
 
 use Hyde\Framework\Actions\MarkdownConverter;
+use Hyde\Framework\Concerns\InteractsWithDirectories;
 use Hyde\Framework\Models\BladePage;
 use Hyde\Framework\Models\DocumentationPage;
 use Hyde\Framework\Models\MarkdownDocument;
@@ -11,12 +12,16 @@
 
 /**
  * Converts a Page Model into a static HTML page.
- *
- * @todo Create the required directories if they don't exist.
- *          Can be done using a trait where an array of the required directories is passed.
  */
 class StaticPageBuilder
 {
+    use InteractsWithDirectories;
+
+    /**
+     * @var string Absolute path to the directory to place compiled files in.
+     */
+    public static string $outputPath;
+
     /**
      * Construct the class.
      *
@@ -28,6 +33,8 @@ public function __construct(protected MarkdownDocument|BladePage $page, bool $se
         if ($selfInvoke) {
             $this->__invoke();
         }
+
+        $this->needsDirectory(static::$outputPath);
     }
 
     /**
@@ -42,6 +49,8 @@ public function __invoke()
         }
 
         if ($this->page instanceof MarkdownPost) {
+            $this->needsDirectory(Hyde::getSiteOutputPath('posts'));
+
             return $this->save('posts/'.$this->page->slug, $this->compilePost());
         }
 
@@ -50,7 +59,7 @@ public function __invoke()
         }
 
         if ($this->page instanceof DocumentationPage) {
-            $this->makeSureDocsDirectoryExists();
+            $this->needsDirectory(Hyde::getSiteOutputPath(Hyde::docsDirectory()));
 
             return $this->save(Hyde::docsDirectory().'/'.$this->page->slug, $this->compileDocs());
         }
@@ -59,12 +68,12 @@ public function __invoke()
     /**
      * Save the compiled HTML to file.
      *
-     * @param  string  $location  of the output file relative to _site/
+     * @param  string  $location  of the output file relative to the site output directory
      * @param  string  $contents  to save to the file
      */
     private function save(string $location, string $contents): bool|int
     {
-        $path = Hyde::path("_site/$location.html");
+        $path = Hyde::getSiteOutputPath("$location.html");
 
         return file_put_contents($path, $contents);
     }
@@ -124,17 +133,4 @@ private function compileDocs(): string
             'currentPage' => Hyde::docsDirectory().'/'.$this->page->slug,
         ])->render();
     }
-
-    /**
-     * Make sure the config defined directory for outputting the
-     * documentation files exists by creating it if it doesn't.
-     *
-     * @return void
-     */
-    protected function makeSureDocsDirectoryExists(): void
-    {
-        if (! file_exists(Hyde::path('_site/'.Hyde::docsDirectory()))) {
-            mkdir(Hyde::path('_site/'.Hyde::docsDirectory()), recursive: true);
-        }
-    }
 }