Refactor Kernel to extract related code into Foundation classes

RELEASE_NOTES.md

@@ -13,13 +13,13 @@ This serves two purposes:
 - for new features.
 
 ### Changed
-- for changes in existing functionality.
+- internal: The HydeKernel has been refactored to move related logic to service classes. This does not change the end usage as the Hyde facade still works the same
 
 ### Deprecated
 - for soon-to-be removed features.
 
 ### Removed
-- for now removed features.
+- Remove deprecated Hyde::uriPath() helper
 
 ### Fixed
 - for any bug fixes.

packages/framework/src/Foundation/Filesystem.php

@@ -0,0 +1,154 @@
+<?php
+
+namespace Hyde\Framework\Foundation;
+
+use Hyde\Framework\Contracts\HydeKernelContract;
+use Hyde\Framework\Models\Pages\BladePage;
+use Hyde\Framework\Models\Pages\DocumentationPage;
+use Hyde\Framework\Models\Pages\MarkdownPage;
+use Hyde\Framework\Models\Pages\MarkdownPost;
+use Hyde\Framework\Services\DiscoveryService;
+use Hyde\Framework\StaticPageBuilder;
+
+/**
+ * File helper methods, bound to the HydeKernel instance, and is an integral part of the framework.
+ *
+ * If a method uses the name `path` it refers to an internal file path.
+ * if a method uses the name `link` it refers to a web link used in Blade templates.
+ *
+ * @see \Hyde\Framework\Testing\Feature\Foundation\FilesystemTest
+ */
+class Filesystem
+{
+    protected HydeKernelContract $kernel;
+
+    public function __construct(HydeKernelContract $kernel)
+    {
+        $this->kernel = $kernel;
+    }
+
+    public function getBasePath(): string
+    {
+        return $this->kernel->getBasePath();
+    }
+
+    /**
+     * Get an absolute file path from a supplied relative path.
+     *
+     * The function returns the fully qualified path to your site's root directory.
+     *
+     * You may also use the function to generate a fully qualified path to a given file
+     * relative to the project root directory when supplying the path argument.
+     *
+     * @param  string  $path
+     * @return string
+     */
+    public function path(string $path = ''): string
+    {
+        if (empty($path)) {
+            return $this->getBasePath();
+        }
+
+        $path = unslash($path);
+
+        return $this->getBasePath().DIRECTORY_SEPARATOR.$path;
+    }
+
+    /**
+     * Works similarly to the path() function, but returns a file in the Framework package.
+     *
+     * @param  string  $path
+     * @return string
+     */
+    public function vendorPath(string $path = ''): string
+    {
+        return $this->path('vendor/hyde/framework/'.unslash($path));
+    }
+
+    /**
+     * Wrapper for the copy function, but allows choosing if files may be overwritten.
+     *
+     * @param  string  $from  The source file path.
+     * @param  string  $to  The destination file path.
+     * @param  bool  $force  If true, existing files will be overwritten.
+     * @return bool|int Returns true|false on copy() success|failure, or an error code on failure
+     */
+    public function copy(string $from, string $to, bool $force = false): bool|int
+    {
+        if (! file_exists($from)) {
+            return 404;
+        }
+
+        if (file_exists($to) && ! $force) {
+            return 409;
+        }
+
+        return copy($from, $to);
+    }
+
+    /**
+     * Fluent file helper methods.
+     *
+     * Provides a more fluent way of getting either the absolute path
+     * to a model's source directory, or an absolute path to a file within it.
+     *
+     * These are intended to be used as a dynamic alternative to legacy code
+     * Hyde::path('_pages/foo') becomes Hyde::getBladePagePath('foo')
+     */
+    public function getModelSourcePath(string $model, string $path = ''): string
+    {
+        if (empty($path)) {
+            return $this->path(DiscoveryService::getFilePathForModelClassFiles($model));
+        }
+
+        $path = unslash($path);
+
+        return $this->path(DiscoveryService::getFilePathForModelClassFiles($model).DIRECTORY_SEPARATOR.$path);
+    }
+
+    public function getBladePagePath(string $path = ''): string
+    {
+        return $this->getModelSourcePath(BladePage::class, $path);
+    }
+
+    public function getMarkdownPagePath(string $path = ''): string
+    {
+        return $this->getModelSourcePath(MarkdownPage::class, $path);
+    }
+
+    public function getMarkdownPostPath(string $path = ''): string
+    {
+        return $this->getModelSourcePath(MarkdownPost::class, $path);
+    }
+
+    public function getDocumentationPagePath(string $path = ''): string
+    {
+        return $this->getModelSourcePath(DocumentationPage::class, $path);
+    }
+
+    /**
+     * Get the absolute path to the compiled site directory, or a file within it.
+     */
+    public function getSiteOutputPath(string $path = ''): string
+    {
+        if (empty($path)) {
+            return StaticPageBuilder::$outputPath;
+        }
+
+        $path = unslash($path);
+
+        return StaticPageBuilder::$outputPath.DIRECTORY_SEPARATOR.$path;
+    }
+
+    /**
+     * Decode an absolute path created with a Hyde::path() helper into its relative counterpart.
+     */
+    public function pathToRelative(string $path): string
+    {
+        return str_starts_with($path, $this->path()) ? unslash(str_replace(
+            $this->path(),
+            '',
+            $path
+        )) : $path;
+    }
+}

packages/framework/src/Foundation/Hyperlinks.php

@@ -0,0 +1,115 @@
+<?php
+
+namespace Hyde\Framework\Foundation;
+
+use Hyde\Framework\Exceptions\BaseUrlNotSetException;
+use Hyde\Framework\HydeKernel;
+use Hyde\Framework\Models\Pages\DocumentationPage;
+
+/**
+ * Contains helpers and logic for resolving web paths for compiled files.
+ *
+ * It's bound to the HydeKernel instance, and is an integral part of the framework.
+ *
+ * @see \Hyde\Framework\Testing\Feature\Foundation\HyperlinksTest
+ */
+class Hyperlinks
+{
+    protected HydeKernel $kernel;
+
+    public function __construct(HydeKernel $kernel)
+    {
+        $this->kernel = $kernel;
+    }
+
+    /**
+     * Format a link to an HTML file, allowing for pretty URLs, if enabled.
+     *
+     * @see \Hyde\Framework\Testing\Unit\Foundation\HyperlinkFormatHtmlPathTest
+     */
+    public function formatHtmlPath(string $destination): string
+    {
+        if (config('site.pretty_urls', false) === true) {
+            if (str_ends_with($destination, '.html')) {
+                if ($destination === 'index.html') {
+                    return '/';
+                }
+                if ($destination === DocumentationPage::getOutputDirectory().'/index.html') {
+                    return DocumentationPage::getOutputDirectory().'/';
+                }
+
+                return substr($destination, 0, -5);
+            }
+        }
+
+        return $destination;
+    }
+
+    /**
+     * Inject the proper number of `../` before the links in Blade templates.
+     *
+     * @param  string  $destination  relative to output directory on compiled site
+     * @return string
+     *
+     * @see \Hyde\Framework\Testing\Unit\Foundation\HyperlinkFileHelperRelativeLinkTest
+     */
+    public function relativeLink(string $destination): string
+    {
+        if (str_starts_with($destination, '../')) {
+            return $destination;
+        }
+
+        $nestCount = substr_count($this->kernel->currentPage(), '/');
+        $route = '';
+        if ($nestCount > 0) {
+            $route .= str_repeat('../', $nestCount);
+        }
+        $route .= $this->formatHtmlPath($destination);
+
+        return str_replace('//', '/', $route);
+    }
+
+    /**
+     * Gets a relative web link to the given image stored in the _site/media folder.
+     */
+    public function image(string $name): string
+    {
+        if (str_starts_with($name, 'http')) {
+            return $name;
+        }
+
+        return $this->relativeLink('media/'.basename($name));
+    }
+
+    /**
+     * Check if a site base URL has been set in config (or .env).
+     */
+    public function hasSiteUrl(): bool
+    {
+        return ! blank(config('site.url'));
+    }
+
+    /**
+     * Return a qualified URI path to the supplied path if a base URL is set.
+     *
+     * @param  string  $path  optional relative path suffix. Omit to return base url.
+     * @param  string|null  $default  optional default value to return if no site url is set.
+     * @return string
+     *
+     * @throws BaseUrlNotSetException If no site URL is set and no default is provided
+     */
+    public function url(string $path = '', ?string $default = null): string
+    {
+        $path = $this->formatHtmlPath(trim($path, '/'));
+
+        if ($this->hasSiteUrl()) {
+            return rtrim(rtrim(config('site.url'), '/').'/'.($path ?? ''), '/');
+        }
+
+        if ($default !== null) {
+            return $default.'/'.($path ?? '');
+        }
+
+        throw new BaseUrlNotSetException();
+    }
+}

packages/framework/src/Hyde.php

@@ -2,6 +2,7 @@
 
 namespace Hyde\Framework;
 
+use Hyde\Framework\Contracts\HydeKernelContract;
 use Hyde\Framework\Contracts\RouteContract;
 use Hyde\Framework\Helpers\Features;
 use Illuminate\Support\Facades\Facade;
@@ -20,29 +21,30 @@
  * @method static string vendorPath(string $path = '')
  * @method static string getMarkdownPagePath(string $path = '')
  * @method static string getSiteOutputPath(string $path = '')
- * @method static string formatHtmlPath(string $destination)
  * @method static string getBladePagePath(string $path = '')
  * @method static string pathToRelative(string $path)
- * @method static string path(string $path = '')
  * @method static Features features()
  * @method static bool hasFeature(string $feature)
+ * @method static string path(string $path = '')
  * @method static string relativeLink(string $destination)
  * @method static string getMarkdownPostPath(string $path = '')
  * @method static bool|int copy(string $from, string $to, bool $force = false)
  * @method static string getModelSourcePath(string $model, string $path = '')
  * @method static string image(string $name)
- * @method static void macro(string $name, callable|object $macro)
  * @method static RouteContract|null currentRoute()
  * @method static string currentPage()
- * @method static false|string uriPath(null|string $path = '')
- * @method static bool hasSiteUrl()
- * @method static string url(string $path = '', ?string $default = null)
- * @method static void setBasePath($basePath)
+ * @method static string url(string $path = '', null|string $default = null)
+ * @method static void setBasePath(string $basePath)
  * @method static void mixin(object $mixin, bool $replace = true)
+ * @method static string formatHtmlPath(string $destination)
  * @method static string makeTitle(string $slug)
+ * @method static bool hasSiteUrl()
  * @method static string getBasePath()
- * @method static HydeKernel getInstance()
+ * @method static HydeKernelContract getInstance()
  * @method static string getDocumentationPagePath(string $path = '')
+ * @method static bool hasMacro(string $name)
+ * @method static void macro(string $name, callable|object $macro)
+ * @method static void flushMacros()
  */
 class Hyde extends Facade
 {