Merge pull request #660 from hydephp/customizable-source-roots

Add an easy configuration option to store all source directories in a subfolder
hydephp · Nov 12, 2022 · f4f5f57 · f4f5f57
2 parents 604c70d + f641cb7
commit f4f5f57
Show file tree

Hide file tree

Showing 15 changed files with 302 additions and 22 deletions.
diff --git a/config/hyde.php b/config/hyde.php
@@ -30,6 +30,19 @@
         'port' => env('SERVER_PORT', 8080),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Source Root Directory
+    |--------------------------------------------------------------------------
+    |
+    | HydePHP will by default look for the underscored source directories in the
+    | root of your project. For example, you might want everything in a 'src'
+    | subdirectory. That's easy enough, just set the value below to "src"!
+    |
+    */
+
+    'source_root' => '',
+
     /*
     |--------------------------------------------------------------------------
     | Global Site Meta Tags

diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php
@@ -30,6 +30,19 @@
         'port' => env('SERVER_PORT', 8080),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Source Root Directory
+    |--------------------------------------------------------------------------
+    |
+    | HydePHP will by default look for the underscored source directories in the
+    | root of your project. For example, you might want everything in a 'src'
+    | subdirectory. That's easy enough, just set the value below to "src"!
+    |
+    */
+
+    'source_root' => '',
+
     /*
     |--------------------------------------------------------------------------
     | Global Site Meta Tags

diff --git a/packages/framework/src/Foundation/Concerns/ManagesHydeKernel.php b/packages/framework/src/Foundation/Concerns/ManagesHydeKernel.php
@@ -44,4 +44,14 @@ public function getBasePath(): string
     {
         return $this->basePath;
     }
+
+    public function setSourceRoot(string $sourceRoot): void
+    {
+        $this->sourceRoot = rtrim($sourceRoot, '/\\');
+    }
+
+    public function getSourceRoot(): string
+    {
+        return $this->sourceRoot;
+    }
 }
diff --git a/packages/framework/src/Foundation/HydeKernel.php b/packages/framework/src/Foundation/HydeKernel.php
@@ -46,6 +46,7 @@ class HydeKernel implements Arrayable, JsonSerializable
     protected static HydeKernel $instance;
 
     protected string $basePath;
+    protected string $sourceRoot;
 
     protected Filesystem $filesystem;
     protected Hyperlinks $hyperlinks;
@@ -58,9 +59,10 @@ class HydeKernel implements Arrayable, JsonSerializable
 
     public const VERSION = '1.0.0-dev';
 
-    public function __construct(?string $basePath = null)
+    public function __construct(?string $basePath = null, string $sourceRoot = '')
     {
         $this->setBasePath($basePath ?? getcwd());
+        $this->setSourceRoot($sourceRoot);
         $this->filesystem = new Filesystem($this);
         $this->hyperlinks = new Hyperlinks($this);
     }

diff --git a/packages/framework/src/Framework/Actions/PublishesHydeViews.php b/packages/framework/src/Framework/Actions/PublishesHydeViews.php
@@ -7,11 +7,11 @@
 use Hyde\Hyde;
 use Illuminate\Support\Facades\File;
 
-/*
-* Publish one or more of the Hyde Blade views.
-*
-* @see \Hyde\Framework\Testing\Feature\Actions\PublishesHomepageViewTest
-*/
+/**
+ * Publish one or more of the Hyde Blade views.
+ *
+ * @see \Hyde\Framework\Testing\Feature\Actions\PublishesHomepageViewTest
+ */
 class PublishesHydeViews
 {
     public static array $options = [

diff --git a/packages/framework/src/Framework/Concerns/RegistersFileLocations.php b/packages/framework/src/Framework/Concerns/RegistersFileLocations.php
@@ -5,6 +5,7 @@
 namespace Hyde\Framework\Concerns;
 
 use Hyde\Facades\Site;
+use Hyde\Hyde;
 use Hyde\Pages\Concerns\HydePage;
 
 /**
@@ -20,7 +21,8 @@ trait RegistersFileLocations
 {
     /**
      * Register the default source directories for the given page classes.
-     * Location string should be relative to the root of the application.
+     * Location string should be relative to the source root, which is
+     * usually the root of the project.
      *
      * @example registerSourceDirectories([HydePage::class => '_pages'])
      *
@@ -30,7 +32,7 @@ protected function registerSourceDirectories(array $directoryMapping): void
     {
         foreach ($directoryMapping as $class => $location) {
             /** @var HydePage $class */
-            $class::$sourceDirectory = unslash($location);
+            $class::$sourceDirectory = unslash(Hyde::getSourceRoot().'/'.unslash($location));
         }
     }
 
@@ -73,6 +75,6 @@ protected function discoverBladeViewsIn(string $directory): void
      */
     protected function storeCompiledSiteIn(string $directory): void
     {
-        Site::$outputPath = $directory;
+        Site::$outputPath = unslash($directory);
     }
 }
diff --git a/packages/framework/src/Framework/HydeServiceProvider.php b/packages/framework/src/Framework/HydeServiceProvider.php
@@ -16,6 +16,7 @@
 use Hyde\Markdown\MarkdownConverter;
 use Hyde\Pages\BladePage;
 use Hyde\Pages\DocumentationPage;
+use Hyde\Pages\HtmlPage;
 use Hyde\Pages\MarkdownPage;
 use Hyde\Pages\MarkdownPost;
 use Illuminate\Support\Facades\Blade;
@@ -41,21 +42,25 @@ public function register(): void
             return new MarkdownConverter();
         });
 
+        Hyde::setSourceRoot(config('hyde.source_root', ''));
+
         $this->registerSourceDirectories([
+            HtmlPage::class => '_pages',
             BladePage::class => '_pages',
             MarkdownPage::class => '_pages',
             MarkdownPost::class => '_posts',
             DocumentationPage::class => '_docs',
         ]);
 
         $this->registerOutputDirectories([
+            HtmlPage::class => '',
             BladePage::class => '',
             MarkdownPage::class => '',
             MarkdownPost::class => 'posts',
-            DocumentationPage::class => unslash(config('docs.output_directory', 'docs')),
+            DocumentationPage::class => config('docs.output_directory', 'docs'),
         ]);
 
-        $this->storeCompiledSiteIn(unslash(config('site.output_directory', '_site')));
+        $this->storeCompiledSiteIn(config('site.output_directory', '_site'));
 
         $this->discoverBladeViewsIn(BladePage::sourceDirectory());
 

diff --git a/packages/framework/src/Framework/Services/ValidationService.php b/packages/framework/src/Framework/Services/ValidationService.php
@@ -6,6 +6,9 @@
 
 use Hyde\Facades\Features;
 use Hyde\Hyde;
+use Hyde\Pages\BladePage;
+use Hyde\Pages\DocumentationPage;
+use Hyde\Pages\MarkdownPage;
 use Hyde\Support\Models\ValidationResult as Result;
 
 /**
@@ -42,8 +45,8 @@ public function check_validators_can_run(Result $result): Result
 
     public function check_site_has_a_404_page(Result $result): Result
     {
-        if (file_exists(Hyde::path('_pages/404.md'))
-            || file_exists(Hyde::path('_pages/404.blade.php'))
+        if (file_exists(MarkdownPage::path('404.md'))
+            || file_exists(BladePage::path('404.blade.php'))
         ) {
             return $result->pass('Your site has a 404 page');
         }
@@ -54,8 +57,9 @@ public function check_site_has_a_404_page(Result $result): Result
 
     public function check_site_has_an_index_page(Result $result): Result
     {
-        if (file_exists(Hyde::path('_pages/index.md'))
-            || file_exists('_pages/index.blade.php')) {
+        if (file_exists(MarkdownPage::path('index.md'))
+            || file_exists(BladePage::path('index.blade.php'))
+        ) {
             return $result->pass('Your site has an index page');
         }
 
@@ -75,11 +79,11 @@ public function check_documentation_site_has_an_index_page(Result $result): Resu
                 ->withTip('Skipped because: There are no documentation pages');
         }
 
-        if (file_exists('_docs/index.md')) {
+        if (file_exists(DocumentationPage::path('index.md'))) {
             return $result->pass('Your documentation site has an index page');
         }
 
-        if (file_exists('_docs/README.md')) {
+        if (file_exists(DocumentationPage::path('README.md'))) {
             return $result->fail('Could not find an index.md file in the _docs directory!')
                 ->withTip('However, a _docs/readme.md file was found. A suggestion would be to copy the _docs/readme.md to _docs/index.md.');
         }
@@ -89,7 +93,7 @@ public function check_documentation_site_has_an_index_page(Result $result): Resu
 
     public function check_site_has_an_app_css_stylesheet(Result $result): Result
     {
-        if (file_exists(Hyde::path('_site/media/app.css')) || file_exists(Hyde::path('_media/app.css'))) {
+        if (file_exists(Hyde::sitePath('media/app.css')) || file_exists(Hyde::path('_media/app.css'))) {
             return $result->pass('Your site has an app.css stylesheet');
         }
 

diff --git a/packages/framework/src/Hyde.php b/packages/framework/src/Hyde.php
@@ -38,6 +38,7 @@
  * @method static string makeTitle(string $slug)
  * @method static string currentPage()
  * @method static string getBasePath()
+ * @method static string getSourceRoot()
  * @method static Features features()
  * @method static FileCollection files()
  * @method static PageCollection pages()
@@ -51,6 +52,7 @@
  * @method static bool unlink(array|string $path)
  * @method static void setInstance(HydeKernel $instance)
  * @method static void setBasePath(string $basePath)
+ * @method static void setSourceRoot(string $sourceRoot)
  * @method static void shareViewData(HydePage $page)
  * @method static array toArray()
  * @method static void boot()

diff --git a/packages/framework/src/Pages/Concerns/HydePage.php b/packages/framework/src/Pages/Concerns/HydePage.php
@@ -17,6 +17,7 @@
 use Hyde\Markdown\Models\FrontMatter;
 use Hyde\Support\Models\Route;
 use Hyde\Support\Models\RouteKey;
+use function unslash;
 
 /**
  * The base class for all Hyde pages.
@@ -149,6 +150,14 @@ public static function outputPath(string $identifier): string
         return RouteKey::fromPage(static::class, $identifier).'.html';
     }
 
+    /**
+     * Get an absolute file path to the page's source directory, or a file within it.
+     */
+    public static function path(string $path = ''): string
+    {
+        return Hyde::path(unslash(static::sourceDirectory().'/'.unslash($path)));
+    }
+
     /**
      * Compile the page into static HTML.
      *

diff --git a/packages/framework/tests/ConfigurableSourceRootsFeatureTest.php b/packages/framework/tests/ConfigurableSourceRootsFeatureTest.php
@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Testing;
+
+use function app;
+use function config;
+use function file_put_contents;
+use Hyde\Framework\HydeServiceProvider;
+use Hyde\Hyde;
+use Hyde\Pages\MarkdownPage;
+use Hyde\Testing\TestCase;
+use Illuminate\Support\Facades\File;
+use function mkdir;
+
+/**
+ * Test the overall functionality of the configurable source roots feature.
+ *
+ * Also see these tests which cover specific implementation details:
+ *
+ * @see \Hyde\Framework\Testing\Feature\HydeKernelTest
+ * @see \Hyde\Framework\Testing\Unit\HydeServiceProviderTest
+ */
+class ConfigurableSourceRootsFeatureTest extends TestCase
+{
+    public function test_default_config_value_is_empty_string()
+    {
+        $this->assertSame('', config('hyde.source_root'));
+    }
+
+    public function test_files_in_custom_source_root_can_be_discovered()
+    {
+        $this->setupCustomSourceRoot();
+
+        $this->assertCount(1, MarkdownPage::files());
+        $this->assertCount(1, MarkdownPage::all());
+
+        File::deleteDirectory(Hyde::path('custom'));
+    }
+
+    public function test_files_in_custom_source_root_can_be_compiled()
+    {
+        $this->setupCustomSourceRoot();
+
+        $this->artisan('build');
+
+        $this->assertFileExists(Hyde::path('_site/markdown.html'));
+
+        File::deleteDirectory(Hyde::path('custom'));
+        File::deleteDirectory(Hyde::path('_site'));
+    }
+
+    public function test_hyde_page_path_method_supports_custom_source_roots()
+    {
+        config(['hyde.source_root' => 'custom']);
+        (new HydeServiceProvider(app()))->register();
+
+        $this->assertSame(
+            Hyde::path('custom/_pages/foo.md'), MarkdownPage::path('foo.md')
+        );
+    }
+
+    protected function setupCustomSourceRoot(): void
+    {
+        mkdir(Hyde::path('custom'));
+        mkdir(Hyde::path('custom/_pages'));
+
+        config(['hyde.source_root' => 'custom']);
+        (new HydeServiceProvider(app()))->register();
+
+        file_put_contents(Hyde::path('custom/_pages/markdown.md'), 'Hello, world!');
+    }
+}
diff --git a/packages/framework/tests/Feature/HydeKernelTest.php b/packages/framework/tests/Feature/HydeKernelTest.php
@@ -247,4 +247,15 @@ public function test_version_method_returns_version_constant()
     {
         $this->assertSame(HydeKernel::VERSION, Hyde::version());
     }
+
+    public function test_can_get_source_root()
+    {
+        $this->assertEquals('', Hyde::getSourceRoot());
+    }
+
+    public function test_can_set_source_root()
+    {
+        Hyde::setSourceRoot('foo');
+        $this->assertEquals('foo', Hyde::getSourceRoot());
+    }
 }