Skip to content

Commit d6c9da6

Browse files
julian-farbcodejulian-farbcode
committed
feat: add basic usage and extending states documentation
1 parent d242c96 commit d6c9da6

File tree

4 files changed

+249
-1
lines changed

4 files changed

+249
-1
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,15 @@ export default defineConfig({
3737
text: 'Basics',
3838
items: [
3939
{ text: 'Installation', link: '/installation' },
40+
{ text: 'Basic Usage', link: '/basic-usage' },
4041
]
4142
},
43+
{
44+
text: 'Advanced Usage',
45+
items: [
46+
{ text: 'Extending States', link: '/extending-states' }
47+
]
48+
}
4249
],
4350

4451
socialLinks: [

‎docs/pages/basic-usage.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Basic Usage
2+
3+
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.
4+
5+
## Generating a Stateful Resource
6+
7+
The package provides an Artisan command to quickly generate a new stateful resource:
8+
9+
```bash
10+
php artisan make:stateful-resource UserResource
11+
```
12+
13+
This command creates a new resource class in `app/Http/Resources/` that extends `StatefulJsonResource`:
14+
15+
```php
16+
<?php
17+
18+
namespace App\Http\Resources;
19+
20+
use Illuminate\Http\Request;
21+
use Farbcode\StatefulResources\StatefulJsonResource;
22+
23+
class UserResource extends StatefulJsonResource
24+
{
25+
/**
26+
* Transform the resource into an array.
27+
*
28+
* @return array<string, mixed>
29+
*/
30+
public function toArray(Request $request): array
31+
{
32+
return parent::toArray($request);
33+
}
34+
}
35+
```
36+
37+
## Built-in States
38+
39+
The package comes with three built-in states defined in the `Variant` enum:
40+
41+
- **`Full`** - For all available attributes
42+
- **`Table`** - For attributes suitable for table/listing views
43+
- **`Minimal`** - For only essential attributes
44+
45+
See the [Extending States](extending-states.md) documentation for how to configure this and add custom states.
46+
47+
## Using States in Resources
48+
49+
Inside your stateful resource, you can use conditional methods to control which attributes are included based on the current state:
50+
51+
```php
52+
<?php
53+
54+
namespace App\Http\Resources;
55+
56+
use Farbcode\StatefulResources\Enums\Variant;
57+
use Farbcode\StatefulResources\StatefulJsonResource;
58+
use Illuminate\Http\Request;
59+
60+
class UserResource extends StatefulJsonResource
61+
{
62+
public function toArray(Request $request): array
63+
{
64+
return [
65+
'id' => $this->id,
66+
'name' => $this->name,
67+
'email' => $this->whenState(Variant::Full, $this->email),
68+
'profile' => $this->whenStateIn([Variant::Full], [
69+
'bio' => $this->bio,
70+
'avatar' => $this->avatar,
71+
'created_at' => $this->created_at,
72+
]),
73+
'role' => $this->whenStateIn([Variant::Full, Variant::Table], $this->role),
74+
'last_login' => $this->unlessState(Variant::Minimal, $this->last_login_at),
75+
];
76+
}
77+
}
78+
```
79+
80+
You can also use the string representation of states instead of enum cases:
81+
82+
```php
83+
'email' => $this->whenState('full', $this->email),
84+
'name' => $this->unlessState('minimal', $this->full_name),
85+
```
86+
87+
## Available Conditional Methods
88+
89+
The package provides several methods to conditionally include attributes:
90+
91+
### `whenState`
92+
93+
Include a value only when the current state matches the specified state:
94+
95+
```php
96+
'email' => $this->whenState(Variant::Full, $this->email),
97+
'admin_notes' => $this->whenState(Variant::Full, $this->admin_notes, 'N/A'),
98+
```
99+
100+
### `unlessState`
101+
102+
Include a value unless the current state matches the specified state:
103+
104+
```php
105+
'public_info' => $this->unlessState(Variant::Minimal, $this->public_information),
106+
```
107+
108+
### `whenStateIn`
109+
110+
Include a value when the current state is one of the specified states:
111+
112+
```php
113+
'detailed_info' => $this->whenStateIn([Variant::Full, Variant::Table], [
114+
'department' => $this->department,
115+
'position' => $this->position,
116+
]),
117+
```
118+
119+
### `unlessStateIn`
120+
121+
Include a value unless the current state is one of the specified states:
122+
123+
```php
124+
'sensitive_data' => $this->unlessStateIn([Variant::Minimal, Variant::Table], $this->sensitive_info),
125+
```
126+
127+
### Magic Conditionals
128+
129+
You can also use magic methods with for cleaner syntax:
130+
131+
```php
132+
'email' => $this->whenStateFull($this->email),
133+
'name' => $this->unlessStateMinimal($this->full_name),
134+
```
135+
136+
## Using Stateful Resources
137+
138+
### Setting the State Explicitly
139+
140+
Use the static `state()` method to create a resource with a specific state:
141+
142+
```php
143+
$user = UserResource::state(Variant::Minimal)->make($user);
144+
```
145+
146+
### Using Magic Methods
147+
148+
You can also use magic methods for a more fluent syntax:
149+
150+
```php
151+
// This is equivalent to the explicit state() call
152+
$user = UserResource::minimal()->make($user);
153+
```
154+
155+
### Default State
156+
157+
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`.
158+
159+
```php
160+
// Uses the default state
161+
$user = UserResource::make($user);
162+
```

‎docs/pages/extending-states.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Extending States
2+
3+
You may find yourself being too limited with the three Variant states included in the package's `Variant` enum.
4+
This package allows you to register custom states that you can then use in your resources.
5+
6+
## Registering Custom States
7+
8+
Before using a custom state, register it in the package's `stateful-resources.states` configuration:
9+
10+
```php
11+
<?php
12+
13+
return [
14+
'states' => [
15+
...Variant::cases(), // The built-in states
16+
'custom', // Your custom state as a string
17+
...CustomResourceState::cases(), // Or as cases of a custom enum
18+
],
19+
];
20+
```
21+
22+
## Creating a Custom State Enum
23+
24+
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.
25+
26+
```php
27+
<?php
28+
29+
namespace App\Enums;
30+
31+
use Farbcode\StatefulResources\Contracts\ResourceState;
32+
33+
enum CustomResourceState: string implements ResourceState
34+
{
35+
case Compact = 'compact';
36+
case Extended = 'extended';
37+
case Debug = 'debug';
38+
}
39+
```
40+
41+
## Using Custom States
42+
43+
Now that you have created and registered your custom state enum, you can use it just like the built-in states inside your resources.
44+
45+
```php
46+
<?php
47+
48+
namespace App\Http\Resources;
49+
50+
use Farbcode\StatefulResources\StatefulJsonResource;
51+
use App\Enums\CustomResourceState;
52+
53+
class UserResource extends StatefulJsonResource
54+
{
55+
public function toArray($request)
56+
{
57+
return [
58+
'id' => $this->id,
59+
'name' => $this->name,
60+
'email' => $this->whenState(CustomResourceState::Extended, $this->email),
61+
'debug_info' => $this->whenStateDebug([
62+
'created_at' => $this->created_at,
63+
'updated_at' => $this->updated_at,
64+
]),
65+
'avatar' => $this->unlessState('custom', $this->avatar),
66+
];
67+
}
68+
}
69+
```
70+
71+
You can then apply the custom states to your resource in the same way you would with the built-in states:
72+
73+
```php
74+
// Using the static method
75+
UserResource::state(CustomResourceState::Compact)->make($user);
76+
77+
// Using the magic method (if the state name matches the case name)
78+
UserResource::compact()->make($user);
79+
```

‎docs/pages/installation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Requirements
44

55
- PHP \>= 8.4
6-
- Laravel 12.1+
6+
- Laravel \>= 12.1
77

88
## Installation
99

0 commit comments

Comments
 (0)