feat: improve state management with new state resolution and registration, add configurable default state

Author: julian-farbcode

config/stateful-resources.php

@@ -1,17 +1,31 @@
 <?php
 
+use Farbcode\StatefulResources\Enums\Variant;
+
 return [
     /*
     |--------------------------------------------------------------------------
-    | Custom States
+    | 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.
+    | Below you may register the resource states that you want to use inside
+    | your stateful resources. These can be instances of a ResourceState
+    | or simple strings.
     |
     */
-    'custom_states' => [
-        // App\Enums\CustomResourceState::class,
+    'states' => [
+        ...Variant::cases(),
+        //
     ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default State
+    |--------------------------------------------------------------------------
+    |
+    | This state will be used when no state is explicitly set on the resource.
+    | If not set, the first state in the states array will be used.
+    |
+    */
+    'default_state' => Variant::Full,
 ];

src/Builder.php

@@ -2,6 +2,7 @@
 
 namespace Farbcode\StatefulResources;
 
+use Farbcode\StatefulResources\Concerns\ResolvesState;
 use Farbcode\StatefulResources\Contracts\ResourceState;
 use Illuminate\Support\Facades\Context;
 
@@ -12,14 +13,24 @@
  */
 class Builder
 {
+    use ResolvesState;
+
     private string $resourceClass;
 
-    private ResourceState $state;
+    private string $state;
 
-    public function __construct(string $resourceClass, ResourceState $state)
+    public function __construct(string $resourceClass, string|ResourceState $state)
     {
+        $state = $this->resolveState($state);
+
+        $registeredState = app(StateRegistry::class)->tryFrom($state);
+
+        if ($registeredState === null) {
+            throw new \InvalidArgumentException("State \"{$state}\" is not registered.");
+        }
+
         $this->resourceClass = $resourceClass;
-        $this->state = $state;
+        $this->state = $registeredState;
     }
 
     /**

src/Concerns/ResolvesState.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Farbcode\StatefulResources\Concerns;
+
+use Farbcode\StatefulResources\Contracts\ResourceState;
+use Farbcode\StatefulResources\StateRegistry;
+
+trait ResolvesState
+{
+     /**
+     * Resolve the value of a given state.
+     *
+     * @throws \InvalidArgumentException
+     */
+    private function resolveState(ResourceState|string $state): string
+    {
+        $stateString = $state instanceof ResourceState ? (string) $state->value : $state;
+
+        if (app(StateRegistry::class)->tryFrom($stateString) === null) {
+            throw new \InvalidArgumentException("State \"{$stateString}\" is not registered.");
+        }
+
+        return $stateString;
+    }
+}

src/Concerns/StatefullyLoadsAttributes.php

@@ -26,18 +26,20 @@
  */
 trait StatefullyLoadsAttributes
 {
-    use ConditionallyLoadsAttributes;
+    use ConditionallyLoadsAttributes, ResolvesState;
 
     /**
      * Retrieve a value if the current state matches the given state.
      *
-     * @param  ResourceState  $state
+     * @param  string|ResourceState  $state
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MissingValue|mixed
      */
     protected function whenState($state, $value, $default = null)
     {
+        $state = $this->resolveState($state);
+
         if (func_num_args() === 3) {
             return $this->when($this->getState() === $state, $value, $default);
         }
@@ -48,13 +50,15 @@ protected function whenState($state, $value, $default = null)
     /**
      * Retrieve a value unless the current state matches the given state.
      *
-     * @param  ResourceState  $state
+     * @param  string|ResourceState  $state
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MissingValue|mixed
      */
     protected function unlessState($state, $value, $default = null)
     {
+        $state = $this->resolveState($state);
+
         if (func_num_args() === 3) {
             return $this->unless($this->getState() === $state, $value, $default);
         }
@@ -65,13 +69,15 @@ protected function unlessState($state, $value, $default = null)
     /**
      * Retrieve a value if the current state is one of the given states.
      *
-     * @param  array<ResourceState>  $states
+     * @param  array<string|ResourceState>  $states
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MissingValue|mixed
      */
     protected function whenStateIn(array $states, $value, $default = null)
     {
+        $states = array_map(fn ($state) => $this->resolveState($state), $states);
+
         $condition = in_array($this->getState(), $states, true);
 
         if (func_num_args() === 3) {
@@ -84,13 +90,15 @@ protected function whenStateIn(array $states, $value, $default = null)
     /**
      * Retrieve a value unless the current state is one of the given states.
      *
-     * @param  array<ResourceState>  $states
+     * @param  array<string|ResourceState>  $states
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MissingValue|mixed
      */
     protected function unlessStateIn(array $states, $value, $default = null)
     {
+        $states = array_map(fn ($state) => $this->resolveState($state), $states);
+
         $condition = in_array($this->getState(), $states, true);
 
         if (func_num_args() === 3) {
@@ -103,13 +111,15 @@ protected function unlessStateIn(array $states, $value, $default = null)
     /**
      * Merge a value if the current state matches the given state.
      *
-     * @param  ResourceState  $state
+     * @param  string|ResourceState  $state
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MergeValue|mixed
      */
     protected function mergeWhenState($state, $value, $default = null)
     {
+        $state = $this->resolveState($state);
+
         if (func_num_args() === 3) {
             return $this->mergeWhen($this->getState() === $state, $value, $default);
         }
@@ -120,13 +130,15 @@ protected function mergeWhenState($state, $value, $default = null)
     /**
      * Merge a value unless the current state matches the given state.
      *
-     * @param  ResourceState  $state
+     * @param  string|ResourceState  $state
      * @param  mixed  $value
      * @param  mixed  $default
      * @return \Illuminate\Http\Resources\MergeValue|mixed
      */
     protected function mergeUnlessState($state, $value, $default = null)
     {
+        $state = $this->resolveState($state);
+
         if (func_num_args() === 3) {
             return $this->mergeUnless($this->getState() === $state, $value, $default);
         }
@@ -138,7 +150,7 @@ protected function mergeUnlessState($state, $value, $default = null)
      * Get the current state of the resource.
      * This method should be implemented by the class using this trait.
      */
-    abstract protected function getState(): ResourceState;
+    abstract protected function getState(): string;
 
     public function __call($method, $parameters)
     {

src/Enums/Variant.php

@@ -6,7 +6,7 @@
 
 enum Variant: string implements ResourceState
 {
-    case Minimal = 'minimal';
-    case Table = 'table';
     case Full = 'full';
+    case Table = 'table';
+    case Minimal = 'minimal';
 }

src/StateRegistry.php

@@ -11,69 +11,67 @@
 class StateRegistry
 {
     /**
-     * @var array<string, ResourceState>
+     * @var string[] List of registered states.
      */
-    private array $stateClasses = [];
+    private array $states = [];
 
     /**
-     * Register a state enum class.
+     * Register a state.
      */
-    public function register(string $stateClass): void
+    public function register(string $state): void
     {
-        if (! is_subclass_of($stateClass, ResourceState::class)) {
-            throw new InvalidArgumentException("State class {$stateClass} must be a valid ResourceState enum.");
-        }
-
-        $this->stateClasses[] = $stateClass;
+        $this->states[] = $state;
     }
 
     /**
-     * Try to find a state by value across all registered state classes.
+     * Try to find a state by value across all registered states.
      */
-    public function tryFrom(string $value): ?ResourceState
+    public function tryFrom(string $value): ?string
     {
-        foreach ($this->stateClasses as $stateClass) {
-            $state = $stateClass::tryFrom($value);
-            if ($state !== null) {
-                return $state;
-            }
+        if (in_array($value, $this->states, true)) {
+            return $value;
         }
 
         return null;
     }
 
     /**
-     * Find a state by value across all registered state classes.
+     * Get all available states from all registered states.
+     *
+     * @return string[] List of states.
      */
-    public function from(string $value): ResourceState
+    public function all(): array
     {
-        $state = $this->tryFrom($value);
-
-        if ($state === null) {
-            throw new InvalidArgumentException("Unknown state: {$value}");
-        }
-
-        return $state;
+        return $this->states;
     }
 
     /**
-     * Get all available states from all registered classes.
+     * Clear all registered states.
      */
-    public function all(): array
+    public function clear(): void
     {
-        $states = [];
-        foreach ($this->stateClasses as $stateClass) {
-            $states = array_merge($states, $stateClass::cases());
-        }
-
-        return $states;
+        $this->states = [];
     }
 
-    /**
-     * Clear all registered state classes.
-     */
-    public function clear(): void
+    public function getDefaultState(): string
     {
-        $this->stateClasses = [];
+        $explicitDefault = config('stateful-resources.default_state');
+
+        if ($explicitDefault instanceof ResourceState) {
+            $explicitDefault = $explicitDefault->value;
+        }
+
+        if ($explicitDefault !== null) {
+            $state = $this->tryFrom($explicitDefault);
+            if ($state !== null) {
+                return $state;
+            }
+        }
+
+        if (empty($this->states)) {
+            throw new InvalidArgumentException('No states registered in the StateRegistry.');
+        }
+
+        return $this->states[0];
     }
 }

src/StatefulJsonResource.php

@@ -4,7 +4,6 @@
 
 use Farbcode\StatefulResources\Concerns\StatefullyLoadsAttributes;
 use Farbcode\StatefulResources\Contracts\ResourceState;
-use Farbcode\StatefulResources\Enums\Variant;
 use Illuminate\Http\Resources\Json\JsonResource;
 use Illuminate\Support\Facades\Context;
 
@@ -17,20 +16,20 @@ abstract class StatefulJsonResource extends JsonResource
 {
     use StatefullyLoadsAttributes;
 
-    private ResourceState $state;
+    private string $state;
 
     /**
      * Create a new stateful resource builder with a specific state.
      */
-    public static function state(ResourceState $state): Builder
+    public static function state(string|ResourceState $state): Builder
     {
         return new Builder(static::class, $state);
     }
 
     /**
      * Retrieve the state of the stateful resource.
      */
-    protected function getState(): ResourceState
+    protected function getState(): string
     {
         return $this->state;
     }
@@ -42,7 +41,9 @@ protected function getState(): ResourceState
      */
     public function __construct($resource)
     {
-        $this->state = Context::get('resource-state-'.static::class, Variant::Full);
+        $defaultState = app(StateRegistry::class)->getDefaultState();
+
+        $this->state = Context::get('resource-state-'.static::class, $defaultState);
         parent::__construct($resource);
     }