Merge pull request #1782 from hydephp/overhaul-the-authors-feature

[2.x] Overhaul the blog post authors feature

Author: emmadesilva

RELEASE_NOTES.md

@@ -19,6 +19,7 @@ This serves two purposes:
 - **Breaking:** The internals of the navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations. For more information, see below.
 - **Breaking:** The `hyde.features` configuration format has changed to use Enums instead of static method calls. For more information, see below.
 - **Breaking:** Renamed class `DataCollections` to `DataCollection`. For more information, see below.
+- **Breaking:** The `hyde.authors` config setting should now be keyed by the usernames. For more information, see below.
 - Medium: The `route` function will now throw a `RouteNotFoundException` if the route does not exist in https://github.com/hydephp/develop/pull/1741
 - Minor: Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
 - Minor: Due to changes in the navigation system, it is possible that existing configuration files will need to be adjusted in order for menus to look the same (in terms of ordering etc.)
@@ -29,6 +30,7 @@ This serves two purposes:
 - Minor: `Includes::path()` and  `Includes::get()` methods now normalizes paths to be basenames to match the behaviour of the other include methods in https://github.com/hydephp/develop/pull/1738. This means that nested directories are no longer supported, as you should use a data collection for that.
 - Minor: The `processing_time_ms` attribute in the `sitemap.xml` file has now been removed in https://github.com/hydephp/develop/pull/1744
 - Minor: Updated the `Hyde::url()` helper to return `null` instead of throwing a `BaseUrlNotSetException` when no site URL is set and no path was provided to the method in https://github.com/hydephp/develop/pull/1760
+- Overhauled the blog post author feature in https://github.com/hydephp/develop/pull/1782
 - Improved the sitemap data generation to be smarter and more dynamic in https://github.com/hydephp/develop/pull/1744
 - Skipped build tasks will now exit with an exit code of 3 instead of 0 in https://github.com/hydephp/develop/pull/1749
 - The `hasFeature` method on the Hyde facade and HydeKernel now only accepts a Feature enum value instead of a string for its parameter.
@@ -47,6 +49,7 @@ This serves two purposes:
 - Breaking: Removed the deprecated `\Hyde\Framework\Services\BuildService::transferMediaAssets()` method (see upgrade guide below)
 - Removed the deprecated global`unslash()` function, replaced with the namespaced `\Hyde\unslash()` function in https://github.com/hydephp/develop/pull/1754
 - Removed the deprecated `BaseUrlNotSetException` class, with the `Hyde::url()` helper now returning `null` if no base URL is set in https://github.com/hydephp/develop/pull/1760
+- Removed: The deprecated `PostAuthor::getName()` method is now removed (use `$author->name`) in https://github.com/hydephp/develop/pull/1782
 - Internal: Removed the internal `DocumentationSearchPage::generate()` method as it was unused in https://github.com/hydephp/develop/pull/1569
 
 ### Fixed
@@ -146,6 +149,23 @@ Of course, if you have disabled any of the features, do not include them in the
 
 ## General impact
 
+### Post Author changes
+
+This release makes major improvements into the usability and design of the blog post author feature.
+
+Here is the full list of changes:
+
+- Breaking: The `hyde.authors` config setting should now be keyed by the usernames
+- Removed: The deprecated `PostAuthor::getName()` method is now removed (use `$author->name`)
+- Feature: We now support setting authors in the YAML configuration! Fixes `#1719`
+- Feature: Added a `$author->getPosts()` method to get all author's posts
+- Feature: Authors now can also have custom biographies and social media links
+- The PostAuthor class is now Arrayable and JsonSerializable
+- The collection of site authors are now stored in the HydeKernel
+- Authors can additionally be accessed through `Hyde::authors()`
+
+For more information, see https://github.com/hydephp/develop/pull/1782
+
 ### Documentation search page changes
 
 The documentation search page and search index have been changed to be generated as `InMemoryPages` instead of a post-build task.

config/hyde.php

@@ -284,7 +284,7 @@
     */
 
     'authors' => [
-        Author::create(
+        'mr_hyde' => Author::create(
             'mr_hyde', // Required username
             'Mr. Hyde', // Optional display name
             'https://hydephp.com' // Optional website URL

docs/creating-content/blog-posts.md

@@ -156,7 +156,7 @@ author:
 ```
 
 When specifying an array you don't need all the sub-properties. The example just shows all the supported values.
-Array values here will override all the values in the `authors` config entry.
+Array values here will override all the values in the `authors` config entry, if one exists.
 
 ### Image
 

packages/framework/config/hyde.php

@@ -284,7 +284,7 @@
     */
 
     'authors' => [
-        Author::create(
+        'mr_hyde' => Author::create(
             'mr_hyde', // Required username
             'Mr. Hyde', // Optional display name
             'https://hydephp.com' // Optional website URL

packages/framework/src/Foundation/Concerns/HasKernelData.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Foundation\Concerns;
+
+use Hyde\Facades\Config;
+use Illuminate\Support\Collection;
+use Hyde\Framework\Features\Blogging\Models\PostAuthor;
+
+use function collect;
+
+/**
+ * Contains accessors and containers for data stored in the kernel.
+ *
+ * @internal Single-use trait for the HydeKernel class.
+ *
+ * @see \Hyde\Foundation\HydeKernel
+ */
+trait HasKernelData
+{
+    /**
+     * The collection of authors defined in the config.
+     *
+     * @var \Illuminate\Support\Collection<string, \Hyde\Framework\Features\Blogging\Models\PostAuthor>
+     */
+    protected Collection $authors;
+
+    /**
+     * Get the collection of authors defined in the config.
+     *
+     * @return \Illuminate\Support\Collection<string, \Hyde\Framework\Features\Blogging\Models\PostAuthor>
+     */
+    public function authors(): Collection
+    {
+        if (isset($this->authors)) {
+            return $this->authors;
+        }
+
+        $config = collect(Config::getArray('hyde.authors', []));
+
+        if ($config->isEmpty()) {
+            // Defer setting the authors property until the next try.
+            return $config;
+        }
+
+        return $this->authors = $this->parseConfigurationAuthors($config);
+    }
+
+    protected function parseConfigurationAuthors(Collection $authors): Collection
+    {
+        return $authors->mapWithKeys(function (PostAuthor $author, string $username): array {
+            return [$username ?: $author->username => $author];
+        });
+    }
+}

packages/framework/src/Foundation/HydeKernel.php

@@ -45,6 +45,7 @@ class HydeKernel implements SerializableContract
     use Concerns\ManagesExtensions;
     use Concerns\ManagesViewData;
     use Concerns\BootsHydeKernel;
+    use Concerns\HasKernelData;
 
     use Serializable;
     use Macroable;
@@ -110,6 +111,7 @@ public function toArray(): array
             'files' => $this->files(),
             'pages' => $this->pages(),
             'routes' => $this->routes(),
+            'authors' => $this->authors(),
         ];
     }
 }

packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php

@@ -7,6 +7,7 @@
 use Illuminate\Support\Arr;
 use Hyde\Foundation\Application;
 use Illuminate\Config\Repository;
+use Hyde\Framework\Features\Blogging\Models\PostAuthor;
 
 use function array_merge;
 
@@ -43,6 +44,10 @@ public function bootstrap(Application $app): void
     protected function mergeParsedConfiguration(): void
     {
         foreach ($this->yaml->getData() as $namespace => $data) {
+            if ($namespace === 'hyde' && isset($data['authors'])) {
+                $data['authors'] = $this->parseAuthors($data['authors']);
+            }
+
             $this->mergeConfiguration($namespace, Arr::undot($data ?: []));
         }
     }
@@ -51,4 +56,15 @@ protected function mergeConfiguration(string $namespace, array $yaml): void
     {
         $this->config[$namespace] = array_merge($this->config[$namespace] ?? [], $yaml);
     }
+
+    /**
+     * @param  array<string, array{username?: string, name?: string, website?: string, bio?: string, avatar?: string, socials?: array<string, string>}>  $authors
+     * @return array<string, \Hyde\Framework\Features\Blogging\Models\PostAuthor>
+     */
+    protected function parseAuthors(array $authors): array
+    {
+        return Arr::mapWithKeys($authors, function (array $author, string $username): array {
+            return [$username => PostAuthor::getOrCreate($author)];
+        });
+    }
 }

packages/framework/src/Framework/Features/Blogging/Models/PostAuthor.php

@@ -4,30 +4,37 @@
 
 namespace Hyde\Framework\Features\Blogging\Models;
 
+use Hyde\Hyde;
 use Stringable;
 use Hyde\Facades\Author;
-use Hyde\Facades\Config;
+use Hyde\Pages\MarkdownPost;
 use Illuminate\Support\Collection;
-use JetBrains\PhpStorm\Deprecated;
+use Hyde\Support\Concerns\Serializable;
+use Hyde\Foundation\Kernel\PageCollection;
+use Hyde\Support\Contracts\SerializableContract;
 
-use function strtolower;
 use function is_string;
+use function array_merge;
+use function array_filter;
 
 /**
- * Object representation of a post author for the site.
+ * Object representation of a blog post author for the site.
  */
-class PostAuthor implements Stringable
+class PostAuthor implements Stringable, SerializableContract
 {
+    use Serializable;
+
     /**
      * The username of the author.
+     *
      * This is the key used to find authors in the config.
      */
     public readonly string $username;
 
     /**
      * The display name of the author.
      */
-    public readonly string $name;
+    public readonly ?string $name;
 
     /**
      * The author's website URL.
@@ -37,6 +44,27 @@ class PostAuthor implements Stringable
      */
     public readonly ?string $website;
 
+    /**
+     * The author's biography.
+     */
+    public readonly ?string $bio;
+
+    /**
+     * The author's avatar image.
+     *
+     * If you in your Blade view use `Hyde::asset($author->avatar)`, then this value supports using both image names for files in `_media`, or full URIs starting with the protocol.
+     */
+    public readonly ?string $avatar;
+
+    /**
+     * The author's social media links/handles.
+     *
+     * @var array<string, string
+     *
+     * @example ['twitter' => 'mr_hyde'] ($service => $handle)
+     */
+    public readonly array $socials;
+
     /**
      * Construct a new Post Author object.
      *
@@ -45,58 +73,72 @@ class PostAuthor implements Stringable
      * @param  string  $username
      * @param  string|null  $name
      * @param  string|null  $website
+     * @param  string|null  $bio
+     * @param  string|null  $avatar
+     * @param  array<string, string>  $socials
      */
-    public function __construct(string $username, ?string $name = null, ?string $website = null)
+    public function __construct(string $username, ?string $name = null, ?string $website = null, ?string $bio = null, ?string $avatar = null, array $socials = [])
     {
         $this->username = $username;
-        $this->name = $name ?? $this->username;
+        $this->name = $name ?? $username;
         $this->website = $website;
+        $this->bio = $bio;
+        $this->avatar = $avatar;
+        $this->socials = $socials;
     }
 
     /**
      * Dynamically get or create an author based on a username string or front matter array.
      *
-     * @param  string|array{username?: string, name?: string, website?: string}  $data
+     * @param  string|array{username?: string, name?: string, website?: string, bio?: string, avatar?: string, socials?: array<string, string>}  $data
      */
     public static function getOrCreate(string|array $data): static
     {
         if (is_string($data)) {
             return static::get($data);
         }
 
-        return Author::create(static::findUsername($data), $data['name'] ?? null, $data['website'] ?? null);
+        return new static(...array_merge([
+            'username' => static::findUsernameFromData($data),
+        ], $data));
     }
 
-    /** Get an Author from the config, or create it. */
+    /** Get an Author from the config, or create it with the username. */
     public static function get(string $username): static
     {
-        return static::all()->firstWhere('username', strtolower($username)) ?? Author::create($username);
+        return static::all()->get($username) ?? Author::create($username);
     }
 
     /** @return \Illuminate\Support\Collection<string, \Hyde\Framework\Features\Blogging\Models\PostAuthor> */
     public static function all(): Collection
     {
-        return (new Collection(Config::getArray('hyde.authors', [])))->mapWithKeys(function (self $author): array {
-            return [strtolower($author->username) => $author];
-        });
+        return Hyde::authors();
     }
 
     public function __toString(): string
     {
         return $this->name;
     }
 
+    public function toArray(): array
+    {
+        return array_filter($this->automaticallySerialize());
+    }
+
     /**
-     * @deprecated This is not needed as the name property can be accessed directly.
+     * Get all posts by this author.
+     *
+     * @return \Hyde\Foundation\Kernel\PageCollection<\Hyde\Pages\MarkdownPost>
      */
-    #[Deprecated(reason: 'Use the name property instead.', replacement: '%class%->name')]
-    public function getName(): string
+    public function getPosts(): PageCollection
     {
-        return $this->name;
+        return MarkdownPost::getLatestPosts()->filter(function (MarkdownPost $post) {
+            return $post->author?->username === $this->username;
+        });
     }
 
     /** @param array{username?: string, name?: string, website?: string} $data */
-    protected static function findUsername(array $data): string
+    protected static function findUsernameFromData(array $data): string
     {
         return $data['username'] ?? $data['name'] ?? 'Guest';
     }

packages/framework/src/Hyde.php

@@ -7,10 +7,12 @@
 use Hyde\Enums\Feature;
 use Hyde\Facades\Features;
 use Hyde\Foundation\HydeKernel;
+use Illuminate\Support\Collection;
 use Hyde\Foundation\Kernel\FileCollection;
 use Hyde\Foundation\Kernel\Filesystem;
 use Hyde\Foundation\Kernel\PageCollection;
 use Hyde\Foundation\Kernel\RouteCollection;
+use Hyde\Framework\Features\Blogging\Models\PostAuthor;
 use Hyde\Pages\Concerns\HydePage;
 use Hyde\Support\Models\Route;
 use Hyde\Support\Filesystem\SourceFile;
@@ -53,6 +55,7 @@
  * @method static string getMediaDirectory()
  * @method static string getMediaOutputDirectory()
  * @method static Features features()
+ * @method static Collection<string, PostAuthor> authors()
  * @method static FileCollection<string, SourceFile> files()
  * @method static PageCollection<string, HydePage> pages()
  * @method static RouteCollection<string, Route> routes()

packages/framework/src/Markdown/Contracts/FrontMatter/SubSchemas/AuthorSchema.php

@@ -15,5 +15,8 @@ interface AuthorSchema extends BlogPostSchema
         'name' => 'string',
         'username' => 'string',
         'website' => 'string',
+        'bio' => 'string', // Todo: Support 'biography' as well?
+        'avatar' => 'string',
+        'socials' => 'array<string, string>',
     ];
 }