Merge pull request #1650 from hydephp/introduce-a-new-feature-enum

Introduce a new Feature enum to improve the Features facade

RELEASE_NOTES.md

@@ -13,12 +13,13 @@ This serves two purposes:
 - Added a `@head` stack to the `head.blade.php` component in https://github.com/hydephp/develop/pull/1567
 - Added a `Hyde::route()` helper to the `Hyde` facade in https://github.com/hydephp/develop/pull/1591
 - Added new global helper functions (`asset()`, `route()`, `url()`) in https://github.com/hydephp/develop/pull/1592
+- Added a new `Feature` enum to improve the `Features` facade in https://github.com/hydephp/develop/pull/1650
 
 ### Changed
-- for changes in existing functionality.
+- The `features` array in the `config/hyde.php` configuration file is now an array of `Feature` enums in https://github.com/hydephp/develop/pull/1650
 
 ### Deprecated
-- for soon-to-be removed features.
+- Deprecated the static `Features` flag methods used in the configuration files in https://github.com/hydephp/develop/pull/1650 and will be removed in HydePHP v2.0
 
 ### Removed
 - for now removed features.
@@ -28,3 +29,33 @@ This serves two purposes:
 
 ### Security
 - in case of vulnerabilities.
+
+### Upgrade Path
+
+In order to prepare your project for HydePHP v2.0, you should update your `config/hyde.php` configuration file to use the new `Feature` enum for the `features` array.
+
+Your new config array should look like this:
+
+```php
+    // Make sure to import the new Feature enum at the top of the file 
+    use Hyde\Enums\Feature;
+
+    // Then replace your enabled features with the new Feature enum cases
+    'features' => [
+        // Page Modules
+        Feature::HtmlPages,
+        Feature::MarkdownPosts,
+        Feature::BladePages,
+        Feature::MarkdownPages,
+        Feature::DocumentationPages,
+
+        // Frontend Features
+        Feature::Darkmode,
+        Feature::DocumentationSearch,
+
+        // Integrations
+        Feature::Torchlight,
+    ],
+```
+
+If you need more help, you can see detailed upgrade instructions with screenshots in the pull request https://github.com/hydephp/develop/pull/1650

config/hyde.php

@@ -23,7 +23,7 @@
 */
 
 use Hyde\Facades\Author;
-use Hyde\Facades\Features;
+use Hyde\Enums\Feature;
 use Hyde\Facades\Meta;
 
 return [
@@ -254,18 +254,18 @@
 
     'features' => [
         // Page Modules
-        Features::htmlPages(),
-        Features::markdownPosts(),
-        Features::bladePages(),
-        Features::markdownPages(),
-        Features::documentationPages(),
+        Feature::HtmlPages,
+        Feature::MarkdownPosts,
+        Feature::BladePages,
+        Feature::MarkdownPages,
+        Feature::DocumentationPages,
 
         // Frontend Features
-        Features::darkmode(),
-        Features::documentationSearch(),
+        Feature::Darkmode,
+        Feature::DocumentationSearch,
 
         // Integrations
-        Features::torchlight(),
+        Feature::Torchlight,
     ],
 
     /*

packages/framework/config/hyde.php

@@ -23,7 +23,7 @@
 */
 
 use Hyde\Facades\Author;
-use Hyde\Facades\Features;
+use Hyde\Enums\Feature;
 use Hyde\Facades\Meta;
 
 return [
@@ -254,18 +254,18 @@
 
     'features' => [
         // Page Modules
-        Features::htmlPages(),
-        Features::markdownPosts(),
-        Features::bladePages(),
-        Features::markdownPages(),
-        Features::documentationPages(),
+        Feature::HtmlPages,
+        Feature::MarkdownPosts,
+        Feature::BladePages,
+        Feature::MarkdownPages,
+        Feature::DocumentationPages,
 
         // Frontend Features
-        Features::darkmode(),
-        Features::documentationSearch(),
+        Feature::Darkmode,
+        Feature::DocumentationSearch,
 
         // Integrations
-        Features::torchlight(),
+        Feature::Torchlight,
     ],
 
     /*

packages/framework/src/Console/Commands/DebugCommand.php

@@ -70,11 +70,11 @@ protected function printVerbosePathInformation(): void
 
     protected function printEnabledFeatures(): void
     {
-        /** @var array<string, string> $features */
+        /** @var array<\Hyde\Enums\Feature> $features */
         $features = Config::getArray('hyde.features', []);
 
         foreach ($features as $feature) {
-            $this->line(" - $feature");
+            $this->line(" - $feature->name");
         }
     }
 }

packages/framework/src/Enums/Feature.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Enums;
+
+/**
+ * A configurable feature that belongs to the Features class.
+ *
+ * @see \Hyde\Facades\Features
+ */
+enum Feature: string
+{
+    // Page Modules
+    case HtmlPages = 'html-pages';
+    case MarkdownPosts = 'markdown-posts';
+    case BladePages = 'blade-pages';
+    case MarkdownPages = 'markdown-pages';
+    case DocumentationPages = 'documentation-pages';
+
+    // Frontend Features
+    case Darkmode = 'darkmode';
+    case DocumentationSearch = 'documentation-search';
+
+    // Integrations
+    case Torchlight = 'torchlight';
+}

packages/framework/src/Facades/Features.php

@@ -5,8 +5,10 @@
 namespace Hyde\Facades;
 
 use Hyde\Hyde;
+use Hyde\Enums\Feature;
 use Hyde\Pages\MarkdownPost;
 use Hyde\Pages\DocumentationPage;
+use JetBrains\PhpStorm\Deprecated;
 use Hyde\Support\Concerns\Serializable;
 use Hyde\Support\Contracts\SerializableContract;
 use Hyde\Framework\Concerns\Internal\MockableFeatures;
@@ -39,9 +41,9 @@ class Features implements SerializableContract
     /**
      * Determine if the given specified is enabled.
      */
-    public static function enabled(string $feature): bool
+    public static function enabled(Feature $feature): bool
     {
-        return static::resolveMockedInstance($feature) ?? in_array(
+        return static::resolveMockedInstance($feature->value) ?? in_array(
             $feature, Config::getArray('hyde.features', static::getDefaultOptions())
         );
     }
@@ -52,39 +54,39 @@ public static function enabled(string $feature): bool
 
     public static function hasHtmlPages(): bool
     {
-        return static::enabled(static::htmlPages());
+        return static::enabled(Feature::HtmlPages);
     }
 
     public static function hasBladePages(): bool
     {
-        return static::enabled(static::bladePages());
+        return static::enabled(Feature::BladePages);
     }
 
     public static function hasMarkdownPages(): bool
     {
-        return static::enabled(static::markdownPages());
+        return static::enabled(Feature::MarkdownPages);
     }
 
     public static function hasMarkdownPosts(): bool
     {
-        return static::enabled(static::markdownPosts());
+        return static::enabled(Feature::MarkdownPosts);
     }
 
     public static function hasDocumentationPages(): bool
     {
-        return static::enabled(static::documentationPages());
+        return static::enabled(Feature::DocumentationPages);
     }
 
     public static function hasDocumentationSearch(): bool
     {
-        return static::enabled(static::documentationSearch())
+        return static::enabled(Feature::DocumentationSearch)
             && static::hasDocumentationPages()
             && count(DocumentationPage::files()) > 0;
     }
 
     public static function hasDarkmode(): bool
     {
-        return static::enabled(static::darkmode());
+        return static::enabled(Feature::Darkmode);
     }
 
     /**
@@ -93,7 +95,7 @@ public static function hasDarkmode(): bool
      */
     public static function hasTorchlight(): bool
     {
-        return static::enabled(static::torchlight())
+        return static::enabled(Feature::Torchlight)
             && (Config::getNullableString('torchlight.token') !== null)
             && (app('env') !== 'testing');
     }
@@ -102,44 +104,60 @@ public static function hasTorchlight(): bool
     // Configure features to be used in the config file.
     // =================================================
 
-    public static function htmlPages(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::HtmlPages` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::HtmlPages Enum case', replacement: 'Feature::HtmlPages', since: '1.6.0')]
+    public static function htmlPages(): Feature
     {
-        return 'html-pages';
+        return Feature::HtmlPages;
     }
 
-    public static function bladePages(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::BladePages` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::BladePages Enum case', replacement: 'Feature::BladePages', since: '1.6.0')]
+    public static function bladePages(): Feature
     {
-        return 'blade-pages';
+        return Feature::BladePages;
     }
 
-    public static function markdownPages(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::MarkdownPages` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::MarkdownPages Enum case', replacement: 'Feature::MarkdownPages', since: '1.6.0')]
+    public static function markdownPages(): Feature
     {
-        return 'markdown-pages';
+        return Feature::MarkdownPages;
     }
 
-    public static function markdownPosts(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::MarkdownPosts` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::MarkdownPosts Enum case', replacement: 'Feature::MarkdownPosts', since: '1.6.0')]
+    public static function markdownPosts(): Feature
     {
-        return 'markdown-posts';
+        return Feature::MarkdownPosts;
     }
 
-    public static function documentationPages(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::DocumentationPages` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::DocumentationPages Enum case', replacement: 'Feature::DocumentationPages', since: '1.6.0')]
+    public static function documentationPages(): Feature
     {
-        return 'documentation-pages';
+        return Feature::DocumentationPages;
     }
 
-    public static function documentationSearch(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::DocumentationSearch` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::DocumentationSearch Enum case', replacement: 'Feature::DocumentationSearch', since: '1.6.0')]
+    public static function documentationSearch(): Feature
     {
-        return 'documentation-search';
+        return Feature::DocumentationSearch;
     }
 
-    public static function darkmode(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::Darkmode` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::Darkmode Enum case', replacement: 'Feature::Darkmode', since: '1.6.0')]
+    public static function darkmode(): Feature
     {
-        return 'darkmode';
+        return Feature::Darkmode;
     }
 
-    public static function torchlight(): string
+    /** @deprecated This method will be removed in v2.0. Please use `Feature::Torchlight` instead. */
+    #[Deprecated(reason: 'Replaced by the \Hyde\Enums\Feature::Torchlight Enum case', replacement: 'Feature::Torchlight', since: '1.6.0')]
+    public static function torchlight(): Feature
     {
-        return 'torchlight';
+        return Feature::Torchlight;
     }
 
     // ====================================================
@@ -185,18 +203,18 @@ protected static function getDefaultOptions(): array
     {
         return [
             // Page Modules
-            static::htmlPages(),
-            static::markdownPosts(),
-            static::bladePages(),
-            static::markdownPages(),
-            static::documentationPages(),
+            Feature::HtmlPages,
+            Feature::MarkdownPosts,
+            Feature::BladePages,
+            Feature::MarkdownPages,
+            Feature::DocumentationPages,
 
             // Frontend Features
-            static::darkmode(),
-            static::documentationSearch(),
+            Feature::Darkmode,
+            Feature::DocumentationSearch,
 
             // Integrations
-            static::torchlight(),
+            Feature::Torchlight,
         ];
     }
 }

packages/framework/src/Foundation/HydeKernel.php

@@ -4,6 +4,7 @@
 
 namespace Hyde\Foundation;
 
+use Hyde\Enums\Feature;
 use Hyde\Facades\Features;
 use Hyde\Foundation\Kernel\Filesystem;
 use Hyde\Foundation\Kernel\Hyperlinks;
@@ -89,9 +90,9 @@ public function features(): Features
         return new Features;
     }
 
-    public function hasFeature(string $feature): bool
+    public function hasFeature(Feature|string $feature): bool
     {
-        return Features::enabled($feature);
+        return Features::enabled(is_string($feature) ? Feature::from($feature) : $feature);
     }
 
     /** @inheritDoc */

packages/framework/src/Framework/Concerns/Internal/MockableFeatures.php

@@ -4,6 +4,8 @@
 
 namespace Hyde\Framework\Concerns\Internal;
 
+use Hyde\Enums\Feature;
+
 use function is_array;
 
 /**
@@ -30,8 +32,12 @@ public static function mock(string|array $feature, ?bool $enabled = null): void
         static::$mockedInstances[$feature] = $enabled;
     }
 
-    public static function resolveMockedInstance(string $feature): ?bool
+    public static function resolveMockedInstance(Feature|string $feature): ?bool
     {
+        if ($feature instanceof Feature) {
+            $feature = $feature->value;
+        }
+
         return static::$mockedInstances[$feature] ?? null;
     }