Can we have an additional option to declare response in doc-block?

[mikield]

I see that the recommended way to declare response is to use @response.
@return also works well.

But in my project, when I use PHP Storm with PHPDoc, first solution do not show usage of the classes.

The second option, suggest me to change return type or change doc-block signature.

But I found out an elegant solution that could fix my issue, use @returns instead of @return.

That solution will highlight my classes, indicate that they are not loaded, and will not complain about wrong return types.

The only 1 thing left - Scramble should parse it also, as it parses @response.

What do you think about this?

[romalytvynenko]

@mikield I planned to move to using attributes for responses instead of PHPDoc annotations.

Types will be passed to the attribute as a string:

#[Response(body: 'AnonymousResourceCollection<TodoItemResource>', status: 200)]
public function index()
{
    // ...
}

I planned to do such types parsing strict: in case the class is not imported, Scramble will throw the error.

This, however, still does not solve the issue you're raising. I quickly scanned through the PhpStorm meta documentation, but have not found how to make PhpStorm recognized strings passed to $body parameter as class names. If you can look at that, I'd appreciate it!

[m4tthumphrey]

Are you planning todo this for request body/params too?

The library is great, but is not so good for code reuse, ie if $request is used outside of the specific controller method.

For example; I would have to add this (useless) line to the controller method, just to document the order.source request param.

Edit: Not so useless as I can use phpdoc to further document it, but would be nice to be able todo it without additional lines.

$request->get('order.source');

Because somewhere other than the controller method, this code is used. Unfortunately there are 70+ other instances of this!

    public function defineSource(): int
    {
        if (is_null(auth()->user())) {
            $source = $this->request->order['source'] ?? Order::SOURCE_ADMIN;
        } else {
            $source = Order::SOURCE_API;
        }

        return $source;
    }