Add _includes directory for quickly adding automatic snippets

RELEASE_NOTES.md

@@ -7,6 +7,7 @@ This update makes breaking changes to the configuration. You will need to update
 ### Added
 - Added a new configuration file, `config/site.php`, see below
 - Added RSS feed configuration stubs to `config/site.php`
+- Added an `Includes` facade that can quickly import partials.
 
 ### Changed
 - internal: Refactor navigation menu components and improve link helpers

packages/framework/src/Contracts/IncludeFacadeContract.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Hyde\Framework\Contracts;
+
+interface IncludeFacadeContract
+{
+    /**
+     * Return the path to the includes directory, or a partial within it, if requested.
+     *
+     * @param  string|null  $filename  The partial to return, or null to return the directory.
+     * @return string Absolute Hyde::path() to the partial, or the includes directory.
+     */
+    public static function path(?string $filename = null): string;
+
+    /**
+     * Get the raw contents of a partial file in the includes directory.
+     *
+     * @param  string  $filename  The name of the partial file, including the extension.
+     * @param  string|null  $default  The default value to return if the partial is not found.
+     * @return string|null The contents of the partial file, or the default value if not found.
+     */
+    public static function get(string $filename, ?string $default = null): ?string;
+
+    /**
+     * Get the rendered Markdown of a partial file in the includes directory.
+     *
+     * @param  string  $filename  The name of the partial file, without the extension.
+     * @param  string|null  $default  The default value to return if the partial is not found.
+     * @return string|null The contents of the partial file, or the default value if not found.
+     */
+    public static function markdown(string $filename, ?string $default = null): ?string;
+
+    /**
+     * Get the rendered Blade of a partial file in the includes directory.
+     *
+     * @param  string  $filename  The name of the partial file, without the extension.
+     * @param  string|null  $default  The default value to return if the partial is not found.
+     * @return string|null The contents of the partial file, or the default value if not found.
+     */
+    public static function blade(string $filename, ?string $default = null): ?string;
+}

packages/framework/src/Facades/Includes.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Hyde\Framework\Facades;
+
+use Hyde\Framework\Actions\MarkdownConverter;
+use Hyde\Framework\Contracts\IncludeFacadeContract;
+use Hyde\Framework\Hyde;
+use Illuminate\Support\Facades\Blade;
+
+class Includes implements IncludeFacadeContract
+{
+    protected static string $includesDirectory = 'resources/_includes';
+
+    public static function path(?string $filename = null): string
+    {
+        static::needsDirectory(static::$includesDirectory);
+
+        return $filename === null
+            ? Hyde::path(static::$includesDirectory)
+            : Hyde::path(static::$includesDirectory.'/'.$filename);
+    }
+
+    /** @inheritDoc */
+    public static function get(string $filename, ?string $default = null): ?string
+    {
+        $path = static::path($filename);
+
+        if (! file_exists($path)) {
+            return $default;
+        }
+
+        return file_get_contents($path);
+    }
+
+    /** @inheritDoc */
+    public static function markdown(string $filename, ?string $default = null): ?string
+    {
+        $path = static::path(basename($filename, '.md').'.md');
+
+        if (! file_exists($path)) {
+            return $default;
+        }
+
+        return MarkdownConverter::parse(file_get_contents($path));
+    }
+
+    /** @inheritDoc */
+    public static function blade(string $filename, ?string $default = null): ?string
+    {
+        $path = static::path(basename($filename, '.blade.php').'.blade.php');
+
+        if (! file_exists($path)) {
+            return $default;
+        }
+
+        return Blade::render(file_get_contents($path));
+    }
+
+    protected static function needsDirectory(string $directory): void
+    {
+        if (! file_exists($directory)) {
+            mkdir($directory, recursive: true);
+        }
+    }
+}

packages/framework/tests/Feature/IncludesFacadeTest.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace Hyde\Framework\Testing\Feature;
+
+use Hyde\Framework\Facades\Includes;
+use Hyde\Framework\Hyde;
+use Hyde\Testing\TestCase;
+use Illuminate\Support\Facades\File;
+
+/**
+ * @covers \Hyde\Framework\Facades\Includes
+ */
+class IncludesFacadeTest extends TestCase
+{
+    public function test_path_returns_the_includes_directory()
+    {
+        $this->assertEquals(
+            Hyde::path('resources/_includes'),
+            Includes::path()
+        );
+    }
+
+    public function test_path_returns_a_partial_within_the_includes_directory()
+    {
+        $this->assertEquals(
+            Hyde::path('resources/_includes/partial.html'),
+            Includes::path('partial.html')
+        );
+    }
+
+    public function test_path_creates_directory_if_it_does_not_exist()
+    {
+        $path = Includes::path();
+        File::deleteDirectory($path);
+        $this->assertFalse(File::exists($path));
+        $this->assertTrue(File::exists(Includes::path()));
+    }
+
+    public function test_get_returns_partial()
+    {
+        $expected = 'foo bar';
+        file_put_contents(Hyde::path('resources/_includes/foo.txt'), $expected);
+        $this->assertEquals($expected, Includes::get('foo.txt'));
+        unlink(Hyde::path('resources/_includes/foo.txt'));
+    }
+
+    public function test_get_returns_default_value_when_not_found()
+    {
+        $this->assertNull(Includes::get('foo.txt'));
+        $this->assertEquals('default', Includes::get('foo.txt', 'default'));
+    }
+
+    public function test_markdown_returns_rendered_partial()
+    {
+        $expected = "<h1>foo bar</h1>\n";
+        file_put_contents(Hyde::path('resources/_includes/foo.md'), '# foo bar');
+        $this->assertEquals($expected, Includes::markdown('foo.md'));
+        unlink(Hyde::path('resources/_includes/foo.md'));
+    }
+
+    public function test_markdown_returns_default_value_when_not_found()
+    {
+        $this->assertNull(Includes::markdown('foo.md'));
+        $this->assertEquals('default', Includes::markdown('foo.md', 'default'));
+    }
+
+    public function test_blade_returns_rendered_partial()
+    {
+        $expected = 'foo bar';
+        file_put_contents(Hyde::path('resources/_includes/foo.blade.php'), '{{ "foo bar" }}');
+        $this->assertEquals($expected, Includes::blade('foo.blade.php'));
+        unlink(Hyde::path('resources/_includes/foo.blade.php'));
+    }
+
+    public function test_blade_returns_default_value_when_not_found()
+    {
+        $this->assertNull(Includes::blade('foo.blade.php'));
+        $this->assertEquals('default', Includes::blade('foo.blade.php', 'default'));
+    }
+}