Laravel Actions

Scramble supports Laravel Actions (lorisleiva/laravel-actions) as part of the Scramble PRO package. You can get Scramble PRO here: https://scramble.dedoc.co/pro. After purchasing, you will receive the license key via email.

Installation

Usage

If you already configured routes for Scramble, then after you install Scramble PRO, you’re done! Scramble will generate operation documentation, taking into account the Laravel Actions way of organizing controllers.

Using actions as controllers

By default, when you register an action class as a route action, Laravel will call the handle method of the class. If you define an asController method, it will be used.

Scramble takes this into account and will document the operation using the correct method.

1
namespace App\Actions;
2

3
use App\Models\User;
4
use Illuminate\Http\Response;
5
use Lorisleiva\Actions\Concerns\AsAction;
6

7
class DeleteUser
8
{
9
    use AsAction;
10

11
    public function asController(int $id): Response
12
    {
13
        $this->handle($id);
14

15
        return response()->noContent();
16
    }
17

18
    public function handle(int $id): void
19
    {
20
        User::findOrFail($id)->delete();
21
    }
22
}

You can add documentation manually using PHPDoc comments on the appropriate method on the action class.

However, if you have both asController and handle methods, and you have PHPDoc comments only on the handle method, Scramble will use those comments for the operation documentation. This is useful if you document the handle method and want to avoid duplicating it for the asController method.

Validation rules

To add validation rules, you can define a rules method on your Laravel Action class and use an ActionRequest instance as the request. Scramble will use these rules to document the operation parameters.

1
namespace App\Actions;
2

3
use App\Models\User;
4
use Lorisleiva\Actions\ActionRequest;
5
use Lorisleiva\Actions\Concerns\AsAction;
6

7
class CreateUser
8
{
9
    use AsAction;
10

11
    public function rules()
12
    {
13
        return [
14
            'name' => ['required', 'string'],
15
            'email' => ['required', 'email', 'unique:users,email'],
16
            'password' => ['required', 'string', 'min:8', 'confirmed'],
17
        ];
18
    }
19

20
    public function asController(ActionRequest $request): User
21
    {
22
        $user = $this->handle($request->validated());
23

24
        return $user;
25
    }
26

27
    /* ... */
28
}

Authorization

When you define an authorize method on your Laravel Action class and use an ActionRequest instance as the request, Scramble will document a possible 403 response.

1
namespace App\Actions;
2

3
use Lorisleiva\Actions\ActionRequest;
4
use Lorisleiva\Actions\Concerns\AsAction;
5

6
class UpdateUser
7
{
8
    use AsAction;
9

10
    public function authorize(ActionRequest $request): bool
11
    {
12
        return $request->user()->role === 'admin';
13
    }
14

15
    public function asController(User $user, ActionRequest $request): JsonResponse
16
    /* ... */
17
}

Recipes

Using action class name as operation summary

By default, Scramble does not generate an operation summary (the summary is essentially the title of the operation when displayed in the UI), and UI libraries often use the operation ID as the title. You can use PHPDoc to specify the operation summary:

1
namespace App\Actions;
2

3
use Lorisleiva\Actions\Concerns\AsAction;
4

5
class CreateUser
6
{
7
    use AsAction;
8

9
    /**
10
     * Create user
11
     */
12
    public function handle(array $data): User
13
    /* ... */
14
}

However, since it’s common to name your action classes in a way that reflects the operation they perform (for example, the CreateUser action class creates a user), it would be much better to avoid manually adding a PHPDoc comment that duplicates the action class name, and instead use the class name as the operation summary directly. You can do this by adding an operation transformer that will automatically use the action class name as the operation summary if the route is a Laravel Action route. Here is how you can define such a transformer in a service provider:

1
namespace App\Providers;
2

3
use Dedoc\Scramble\Scramble;
4
use Dedoc\Scramble\Support\Generator\Operation;
5
use Dedoc\Scramble\Support\RouteInfo;
6
use Illuminate\Support\ServiceProvider;
7
use Illuminate\Support\Str;
8
use Lorisleiva\Actions\Concerns\AsAction;
9

10
class AppServiceProvider extends ServiceProvider
11
{
12
    /**
13
     * Bootstrap any application services.
14
     */
15
    public function boot(): void
16
    {
17
        Scramble::configure()
18
            ->withOperationTransformers(function (Operation $operation, RouteInfo $routeInfo) {
19
                if (! $className = $routeInfo->className()) {
20
                    return;
21
                }
22

23
                if (! in_array(AsAction::class, class_uses_recursive($className))) {
24
                    return;
25
                }
26

27
                if ($routeInfo->phpDoc()->getAttribute('summary')) {
28
                    return;
29
                }
30

31
                $name = Str::afterLast($className, '\\');
32

33
                $operation->summary(Str::ucfirst(Str::lower(Str::headline($name))));
34
            });
35
    }
36
}

This transformer uses a properly formatted action class name (CreateUser becomes Create user) as the operation summary if the route is a Laravel Action route. It also makes sure not to interfere with PHPDoc if there is one, allowing you to specify your own operation summary when needed.