feat: add custom resource states, refactor naming

Author: julian-farbcode

config/stateful-resources.php

@@ -1,5 +1,18 @@
 <?php
 
 return [
-    //
+    /*
+    |--------------------------------------------------------------------------
+    | Custom States
+    |--------------------------------------------------------------------------
+    |
+    | Below you may register custom resource states that you want to use inside
+    | your stateful resources. Each state must be a valid enum class that
+    | implements the ResourceState interface and uses the AsResourceState
+    | trait.
+    |
+    */
+    'custom_states' => [
+        // App\Enums\CustomResourceState::class,
+    ],
 ];

src/Builder.php

@@ -2,9 +2,14 @@
 
 namespace Farbcode\StatefulResources;
 
-use Farbcode\StatefulResources\Enums\ResourceState;
+use Farbcode\StatefulResources\Contracts\ResourceState;
 use Illuminate\Support\Facades\Context;
 
+/**
+ * Builder for creating resource instances with a specific state.
+ *
+ * @internal
+ */
 class Builder
 {
     private string $resourceClass;

src/Concerns/AsResourceState.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Farbcode\StatefulResources\Concerns;
+
+trait AsResourceState
+{
+    /**
+     * Get the string value of the state.
+     */
+    public function value(): string
+    {
+        return $this->value;
+    }
+
+    /**
+     * Get the name of the state.
+     */
+    public function name(): string
+    {
+        return $this->name;
+    }
+}

src/Concerns/StatefullyLoadsAttributes.php

@@ -2,7 +2,8 @@
 
 namespace Farbcode\StatefulResources\Concerns;
 
-use Farbcode\StatefulResources\Enums\ResourceState;
+use Farbcode\StatefulResources\Contracts\ResourceState;
+use Farbcode\StatefulResources\StateRegistry;
 use Illuminate\Http\Resources\ConditionallyLoadsAttributes;
 use Illuminate\Http\Resources\MergeValue;
 use Illuminate\Http\Resources\MissingValue;
@@ -155,7 +156,12 @@ public function __call($method, $parameters)
                     continue;
                 }
 
-                return $this->{$singleStateMethod}(ResourceState::from($state), ...$parameters);
+                $stateInstance = StateRegistry::tryFrom($state);
+                if ($stateInstance === null) {
+                    continue;
+                }
+
+                return $this->{$singleStateMethod}($stateInstance, ...$parameters);
             }
         }
 

src/Contracts/ResourceState.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Farbcode\StatefulResources\Contracts;
+
+interface ResourceState
+{
+    /**
+     * Get the string value of the state.
+     */
+    public function value(): string;
+
+    /**
+     * Get the name of the state.
+     */
+    public function name(): string;
+
+    /**
+     * Create a state instance from a string value.
+     */
+    public static function from(string $value): static;
+
+    /**
+     * Try to create a state instance from a string value.
+     */
+    public static function tryFrom(string $value): ?static;
+
+    /**
+     * Get all available states.
+     */
+    public static function cases(): array;
+}

src/Enums/ResourceState.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Farbcode\StatefulResources\Enums;
+
+use Farbcode\StatefulResources\Concerns\AsResourceState;
+use Farbcode\StatefulResources\Contracts\ResourceState;
+
+enum Variant: string implements ResourceState
+{
+    use AsResourceState;
+
+    case Minimal = 'minimal';
+    case Table = 'table';
+    case Full = 'full';
+}

src/Enums/Variant.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Farbcode\StatefulResources;
+
+use Farbcode\StatefulResources\Contracts\ResourceState;
+use InvalidArgumentException;
+
+/**
+ * @internal
+ */
+class StateRegistry
+{
+    private static array $stateClasses = [];
+
+    /**
+     * Register a state enum class.
+     */
+    public static function register(string $stateClass): void
+    {
+        if (! is_subclass_of($stateClass, ResourceState::class)) {
+            throw new InvalidArgumentException("State class {$stateClass} must implement the ResourceState interface.");
+        }
+
+        self::$stateClasses[] = $stateClass;
+    }
+
+    /**
+     * Try to find a state by value across all registered state classes.
+     */
+    public static function tryFrom(string $value): ?ResourceState
+    {
+        foreach (self::$stateClasses as $stateClass) {
+            $state = $stateClass::tryFrom($value);
+            if ($state !== null) {
+                return $state;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Find a state by value across all registered state classes.
+     */
+    public static function from(string $value): ResourceState
+    {
+        $state = self::tryFrom($value);
+
+        if ($state === null) {
+            throw new InvalidArgumentException("Unknown state: {$value}");
+        }
+
+        return $state;
+    }
+
+    /**
+     * Get all available states from all registered classes.
+     */
+    public static function all(): array
+    {
+        $states = [];
+        foreach (self::$stateClasses as $stateClass) {
+            $states = array_merge($states, $stateClass::cases());
+        }
+
+        return $states;
+    }
+
+    /**
+     * Clear all registered state classes.
+     */
+    public static function clear(): void
+    {
+        self::$stateClasses = [];
+    }
+}

src/StateRegistry.php

@@ -3,7 +3,8 @@
 namespace Farbcode\StatefulResources;
 
 use Farbcode\StatefulResources\Concerns\StatefullyLoadsAttributes;
-use Farbcode\StatefulResources\Enums\ResourceState;
+use Farbcode\StatefulResources\Contracts\ResourceState;
+use Farbcode\StatefulResources\Enums\Variant;
 use Illuminate\Http\Resources\Json\JsonResource;
 use Illuminate\Support\Facades\Context;
 
@@ -41,7 +42,7 @@ protected function getState(): ResourceState
      */
     public function __construct($resource)
     {
-        $this->state = Context::get('resource-state-'.static::class, ResourceState::Full);
+        $this->state = Context::get('resource-state-'.static::class, Variant::Full);
         parent::__construct($resource);
     }
 
@@ -56,7 +57,7 @@ public function __construct($resource)
      */
     public static function __callStatic($method, $parameters)
     {
-        $state = ResourceState::tryFrom($method);
+        $state = StateRegistry::tryFrom($method);
 
         if ($state === null) {
             return parent::__callStatic($method, $parameters);

src/StatefulJsonResource.php

@@ -2,6 +2,7 @@
 
 namespace Farbcode\StatefulResources;
 
+use Farbcode\StatefulResources\Enums\Variant;
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
@@ -18,4 +19,21 @@ public function configurePackage(Package $package): void
             ->name('stateful-resources')
             ->hasConfigFile();
     }
+
+    public function bootingPackage(): void
+    {
+        $customStates = config()->array('stateful-resources.custom_states');
+
+        $this->app->singleton(StateRegistry::class, function () use ($customStates) {
+            $registry = new StateRegistry;
+
+            $registry->register(Variant::class);
+
+            foreach ($customStates as $stateClass) {
+                $registry->register($stateClass);
+            }
+
+            return $registry;
+        });
+    }
 }