Merge pull request #1 from farbcodegmbh/feat/custom-states

[Feature] Custom Resource States

Co-authored-by: Raphael Störk <raphael.stoerk@farbcode.net>
Co-authored-by: Julian Schramm <hi@julian.center>

Author: 3 people

composer.json

@@ -21,7 +21,7 @@
     ],
     "require": {
         "php": "^8.4",
-        "illuminate/contracts": "^12.0",
+        "illuminate/contracts": "^12.1",
         "spatie/laravel-package-tools": "^1.16"
     },
     "require-dev": {

config/stateful-resources.php

@@ -1,5 +1,31 @@
 <?php
 
+use Farbcode\StatefulResources\Enums\State;
+
 return [
-    //
+    /*
+    |--------------------------------------------------------------------------
+    | States
+    |--------------------------------------------------------------------------
+    |
+    | 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.
+    |
+    */
+    'states' => [
+        ...State::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' => State::Full,
 ];

docs/.vitepress/config.mts

@@ -37,8 +37,15 @@ export default defineConfig({
                 text: 'Basics',
                 items: [
                     { text: 'Installation', link: '/installation' },
+                    { text: 'Basic Usage', link: '/basic-usage' },
                 ]
             },
+            {
+                text: 'Advanced Usage',
+                items: [
+                    { text: 'Extending States', link: '/extending-states' }
+                ]
+            }
         ],
 
         socialLinks: [

docs/pages/basic-usage.md

@@ -0,0 +1,162 @@
+# Basic Usage
+
+Laravel Stateful Resources allows you to create dynamic API responses by changing the structure of your JSON resources based on different states. This is especially useful when you need to return different levels of detail for the same model depending on the context.
+
+## Generating a Stateful Resource
+
+The package provides an Artisan command to quickly generate a new stateful resource:
+
+```bash
+php artisan make:stateful-resource UserResource
+```
+
+This command creates a new resource class in `app/Http/Resources/` that extends `StatefulJsonResource`:
+
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Farbcode\StatefulResources\StatefulJsonResource;
+
+class UserResource extends StatefulJsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return parent::toArray($request);
+    }
+}
+```
+
+## Built-in States
+
+The package comes with three built-in states defined in the `State` enum:
+
+-   **`Full`** - For all available attributes
+-   **`Table`** - For attributes suitable for table/listing views
+-   **`Minimal`** - For only essential attributes
+
+See the [Extending States](extending-states.md) documentation for how to configure this and add custom states.
+
+## Using States in Resources
+
+Inside your stateful resource, you can use conditional methods to control which attributes are included based on the current state:
+
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Farbcode\StatefulResources\Enums\State;
+use Farbcode\StatefulResources\StatefulJsonResource;
+use Illuminate\Http\Request;
+
+class UserResource extends StatefulJsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->whenState(State::Full, $this->email),
+            'profile' => $this->whenStateIn([State::Full], [
+                'bio' => $this->bio,
+                'avatar' => $this->avatar,
+                'created_at' => $this->created_at,
+            ]),
+            'role' => $this->whenStateIn([State::Full, State::Table], $this->role),
+            'last_login' => $this->unlessState(State::Minimal, $this->last_login_at),
+        ];
+    }
+}
+```
+
+You can also use the string representation of states instead of enum cases:
+
+```php
+'email' => $this->whenState('full', $this->email),
+'name' => $this->unlessState('minimal', $this->full_name),
+```
+
+## Available Conditional Methods
+
+The package provides several methods to conditionally include attributes:
+
+### `whenState`
+
+Include a value only when the current state matches the specified state:
+
+```php
+'email' => $this->whenState(State::Full, $this->email),
+'admin_notes' => $this->whenState(State::Full, $this->admin_notes, 'N/A'),
+```
+
+### `unlessState`
+
+Include a value unless the current state matches the specified state:
+
+```php
+'public_info' => $this->unlessState(State::Minimal, $this->public_information),
+```
+
+### `whenStateIn`
+
+Include a value when the current state is one of the specified states:
+
+```php
+'detailed_info' => $this->whenStateIn([State::Full, State::Table], [
+    'department' => $this->department,
+    'position' => $this->position,
+]),
+```
+
+### `unlessStateIn`
+
+Include a value unless the current state is one of the specified states:
+
+```php
+'sensitive_data' => $this->unlessStateIn([State::Minimal, State::Table], $this->sensitive_info),
+```
+
+### Magic Conditionals
+
+You can also use magic methods with for cleaner syntax:
+
+```php
+'email' => $this->whenStateFull($this->email),
+'name' => $this->unlessStateMinimal($this->full_name),
+```
+
+## Using Stateful Resources
+
+### Setting the State Explicitly
+
+Use the static `state()` method to create a resource with a specific state:
+
+```php
+$user = UserResource::state(State::Minimal)->make($user);
+```
+
+### Using Magic Methods
+
+You can also use magic methods for a more fluent syntax:
+
+```php
+// This is equivalent to the explicit state(State::Minimal) call
+$user = UserResource::minimal()->make($user);
+```
+
+### Default State
+
+If no state is specified, the resource will use the default state. You can change the default state in the package's configuration file: `config/stateful-resources.php`.
+
+```php
+// Uses the default state
+$user = UserResource::make($user);
+```

docs/pages/extending-states.md

@@ -0,0 +1,80 @@
+# Extending States
+
+You may find yourself being too limited with the three State states included in the package's `State` enum.
+This package allows you to register custom states that you can then use in your resources.
+
+## Registering Custom States
+
+Before using a custom state, register it in the package's `stateful-resources.states` configuration:
+
+```php
+<?php
+use Farbcode\StatefulResources\Enums\State;
+
+return [
+    'states' => [
+        ...State::cases(), // The built-in states
+        'custom', // Your custom state as a string
+        ...CustomResourceState::cases(), // Or as cases of a custom enum
+    ],
+];
+```
+
+## Creating a Custom State Enum
+
+Instead of using strings, you may want to create your own state enum to define custom states. This enum should implement the `ResourceState` interface provided by the package.
+
+```php
+<?php
+
+namespace App\Enums;
+
+use Farbcode\StatefulResources\Contracts\ResourceState;
+
+enum CustomResourceState: string implements ResourceState
+{
+    case Compact = 'compact';
+    case Extended = 'extended';
+    case Debug = 'debug';
+}
+```
+
+## Using Custom States
+
+Now that you have created and registered your custom state enum, you can use it just like the built-in states inside your resources.
+
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Farbcode\StatefulResources\StatefulJsonResource;
+use App\Enums\CustomResourceState;
+
+class UserResource extends StatefulJsonResource
+{
+    public function toArray($request)
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->whenState(CustomResourceState::Extended, $this->email),
+            'debug_info' => $this->whenStateDebug([
+                'created_at' => $this->created_at,
+                'updated_at' => $this->updated_at,
+            ]),
+            'avatar' => $this->unlessState('custom', $this->avatar),
+        ];
+    }
+}
+```
+
+You can then apply the custom states to your resource in the same way you would with the built-in states:
+
+```php
+// Using the static method
+UserResource::state(CustomResourceState::Compact)->make($user);
+
+// Using the magic method (if the state name matches the case name)
+UserResource::compact()->make($user);
+```

docs/pages/installation.md

@@ -3,7 +3,7 @@
 ## Requirements
 
 -   PHP \>= 8.4
--   Laravel 12.x
+-   Laravel \>= 12.1
 
 ## Installation
 

src/Builder.php

@@ -2,19 +2,35 @@
 
 namespace Farbcode\StatefulResources;
 
-use Farbcode\StatefulResources\Enums\ResourceState;
+use Farbcode\StatefulResources\Concerns\ResolvesState;
+use Farbcode\StatefulResources\Contracts\ResourceState;
 use Illuminate\Support\Facades\Context;
 
+/**
+ * Builder for creating resource instances with a specific state.
+ *
+ * @internal
+ */
 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;
+    }
+}