Change internal page data structure to use new front matter schema traits

RELEASE_NOTES.md

@@ -7,26 +7,29 @@ This update contains **breaking changes** to the internal API regarding page mod
 ### Added
 - Added `compile()` method to `Facades\Markdown`, replacing the `parse()` method of the same class
 - Adds a new action, PageModelConstructor, to dynamically construct page model data
+- Adds new actions to handle complex dynamic constructors
+- Adds new front matter schema traits
 
 ### Changed
 - Breaking: Rename AbstractMarkdownPage constructor parameter `slug` to `identifier`
 - Breaking: Rename AbstractPage property `slug` to `identifier`
 - Breaking: Change `AbstractMarkdownPage` constructor argument positions, putting `identifier` first
 - Breaking: Splits Markdown data from MarkdownDocument into new Markdown model class
 - Breaking: The default `config/hyde.php` file now uses `Models\Author` instead of `Helpers\Author`
+- Major: Restructure internal page data to use new front matter schema traits 
 - Begin changing references to slugs to identifiers, see motivation below
 - Makes some helpers in SourceFileParser public static allowing them to be used outside the class
 
 ### Deprecated
 - Deprecated `Facades\Markdown::parse()`, use `Facades\Markdown::render()` instead
 - Deprecated `Facades\Markdown.php`, will be merged into `Models\Markdown.php` 
-- Deprecate `$title` property in AbstractMarkdownPage, (access through front matter instead)
 
 ### Removed
 - Removed `Facades\Markdown.php`, merged into `Models\Markdown.php`
 - Removed `body()` method from `MarkdownDocumentContract` interface and all its implementations. Use `markdown()->body()` (or cast to string) instead
 - Removed `body` property from Markdown pages. Use `markdown()->body()` (or cast to string) instead
 - Removed deprecated `Helpers\Author` (fully merged into `Models\Author`, simply swap namespace to upgrade)
+- Several internal single-use helper traits have been merged into their respective classes
 
 ### Fixed
 - for any bug fixes.

packages/framework/src/Actions/Constructors/ConfiguresFeaturedImageForPost.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Hyde\Framework\Actions\Constructors;
+
+use Hyde\Framework\Models\Image;
+use Hyde\Framework\Models\Pages\MarkdownPost;
+
+/**
+ * @internal
+ *
+ * @see \Hyde\Framework\Testing\Unit\ConfiguresFeaturedImageForPostTest
+ */
+class ConfiguresFeaturedImageForPost
+{
+    public static function run(MarkdownPost $page): Image|null
+    {
+        return (new static($page))->constructImage();
+    }
+
+    protected function __construct(protected MarkdownPost $page)
+    {
+    }
+
+    private function constructImage(): Image|null
+    {
+        if ($this->page->matter('image') !== null) {
+            if (is_string($this->page->matter('image'))) {
+                return $this->constructBaseImage($this->page->matter('image'));
+            }
+            if (is_array($this->page->matter('image'))) {
+                return new Image($this->page->matter('image'));
+            }
+        }
+
+        return null;
+    }
+
+    private function constructBaseImage(string $image): Image
+    {
+        return str_starts_with($image, 'http')
+            ? new Image(['uri' => $image])
+            : new Image(['path' => $image]);
+    }
+}

packages/framework/src/Actions/Constructors/FindsAuthorForPost.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Hyde\Framework\Actions\Constructors;
+
+use Hyde\Framework\Models\Author;
+use Hyde\Framework\Models\Pages\MarkdownPost;
+
+/**
+ * @internal
+ */
+class FindsAuthorForPost
+{
+    public static function run(MarkdownPost $page): Author|null
+    {
+        return (new static($page))->findAuthorForPost();
+    }
+
+    protected function __construct(protected MarkdownPost $page)
+    {
+    }
+
+    protected function findAuthorForPost(): Author|null
+    {
+        if ($this->page->matter('author') !== null) {
+            if (is_string($this->page->matter('author'))) {
+                // If the author is a string, we assume it's a username,
+                // so we'll try to find the author in the config
+                return Author::get($this->page->matter('author'));
+            }
+            if (is_array($this->page->matter('author'))) {
+                // If the author is an array, we'll assume it's a user
+                // with one-off custom data, so we create a new author.
+                // In the future we may want to merge config data with custom data
+                return new Author($this->getUsername(), $this->page->matter('author'));
+            }
+        }
+
+        return null;
+    }
+
+    protected function getUsername(): string
+    {
+        return $this->page->matter('author')['username'] ?? $this->page->matter('author')['name'] ?? 'Guest';
+    }
+}

packages/framework/src/Actions/Constructors/FindsTitleForPage.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Hyde\Framework\Actions\Constructors;
+
+use Hyde\Framework\Contracts\AbstractMarkdownPage;
+use Hyde\Framework\Contracts\AbstractPage;
+use Hyde\Framework\Hyde;
+
+/**
+ * @see \Hyde\Framework\Testing\Feature\PageModelConstructorTest
+ *
+ * @internal
+ */
+class FindsTitleForPage
+{
+    public static function run(AbstractPage $page): string
+    {
+        return (new static($page))->findTitleForPage();
+    }
+
+    protected function __construct(protected AbstractPage $page)
+    {
+    }
+
+    protected function findTitleForPage(): string
+    {
+        return $this->page instanceof AbstractMarkdownPage
+            ? $this->findTitleForMarkdownPage()
+            : Hyde::makeTitle($this->page->identifier);
+    }
+
+    protected function findTitleForMarkdownPage(): string
+    {
+        return $this->page->matter('title')
+            ?? $this->findTitleFromMarkdownHeadings()
+            ?? Hyde::makeTitle($this->page->identifier);
+    }
+
+    protected function findTitleFromMarkdownHeadings(): ?string
+    {
+        if ($this->page instanceof AbstractMarkdownPage) {
+            foreach ($this->page->markdown()->toArray() as $line) {
+                if (str_starts_with($line, '# ')) {
+                    return trim(substr($line, 2), ' ');
+                }
+            }
+        }
+
+        return null;
+    }
+}

packages/framework/src/Actions/PageModelConstructor.php

@@ -4,7 +4,6 @@
 
 use Hyde\Framework\Contracts\AbstractMarkdownPage;
 use Hyde\Framework\Contracts\AbstractPage;
-use Hyde\Framework\Hyde;
 use Hyde\Framework\Models\Pages\BladePage;
 use Hyde\Framework\Models\Pages\DocumentationPage;
 use Illuminate\Support\Str;
@@ -34,10 +33,7 @@ protected function __construct(AbstractPage $page)
 
     protected function constructDynamicData(): void
     {
-        if (optional($this->page)->title === null) {
-            $this->page->title = static::findTitleForPage();
-        }
-
+        // @deprecated v0.58.x-beta (will be added to docpage schema)
         if ($this->page instanceof DocumentationPage) {
             $this->page->category = static::getDocumentationPageCategory();
         }
@@ -58,29 +54,4 @@ protected function getDocumentationPageCategory(): ?string
             ? Str::before($this->page->identifier, '/')
             : $this->page->matter('category');
     }
-
-    protected function findTitleForPage(): string
-    {
-        return $this->page instanceof AbstractMarkdownPage
-            ? $this->findTitleForMarkdownPage()
-            : Hyde::makeTitle($this->page->identifier);
-    }
-
-    protected function findTitleForMarkdownPage(): string
-    {
-        return $this->page->matter('title')
-            ?? static::findTitleFromMarkdownHeadings()
-            ?? Hyde::makeTitle($this->page->identifier);
-    }
-
-    protected function findTitleFromMarkdownHeadings(): ?string
-    {
-        foreach ($this->page->markdown()->toArray() as $line) {
-            if (str_starts_with($line, '# ')) {
-                return trim(substr($line, 2), ' ');
-            }
-        }
-
-        return null;
-    }
 }

packages/framework/src/Concerns/FrontMatter/Schemas/BlogPostSchema.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Hyde\Framework\Concerns\FrontMatter\Schemas;
+
+use Hyde\Framework\Actions\Constructors\ConfiguresFeaturedImageForPost;
+use Hyde\Framework\Actions\Constructors\FindsAuthorForPost;
+use Hyde\Framework\Models\Author;
+use Hyde\Framework\Models\DateString;
+use Hyde\Framework\Models\Image;
+
+trait BlogPostSchema
+{
+    /** @example "My New Post" */
+    public string $title;
+
+    /** @example "A short description" */
+    public ?string $description = null;
+
+    /** @example "general", "my favorite recipes" */
+    public ?string $category = null;
+
+    /**
+     * The date the post was published.
+     *
+     * @example 'YYYY-MM-DD [HH:MM]' (Must be parsable by `strtotime()`)
+     * @yamlType string|optional
+     */
+    public ?DateString $date = null;
+
+    /**
+     * @example See author section
+     * @yamlType string|array|optional
+     */
+    public ?Author $author = null;
+
+    /**
+     * @example See image section
+     * @yamlType string|array|optional
+     */
+    public ?Image $image = null;
+
+    protected function constructBlogPostSchema(): void
+    {
+        $this->category = $this->matter('category');
+        $this->description = $this->matter('description', substr($this->markdown, 0, 125).'...');
+        $this->date = $this->matter('date') !== null ? new DateString($this->matter('date')) : null;
+        $this->author = FindsAuthorForPost::run($this);
+        $this->image = ConfiguresFeaturedImageForPost::run($this);
+    }
+}

packages/framework/src/Concerns/FrontMatter/Schemas/PageSchema.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Hyde\Framework\Concerns\FrontMatter\Schemas;
+
+use Hyde\Framework\Actions\Constructors\FindsTitleForPage;
+
+trait PageSchema
+{
+    /** @example "Home", "About", "Blog Feed" */
+    public string $title;
+
+    protected function constructPageSchema(): void
+    {
+        $this->title = FindsTitleForPage::run($this);
+    }
+}