Описание параметров запроса контроллера в PHPDoc - PullRequest
Новая
       19

Описание параметров запроса контроллера в PHPDoc

2 голосов
/ 15 апреля 2020

Мой Laravel контроллер имеет метод индекса, который принимает необязательный параметр строки запроса.

Как это должно быть представлено в блоке PHPDo c метода?

EmployerController. php: 

/**
 * @param Request $request
 * @return Response
 * Returns list of Employers
 */
public function index(Request $request) {
    // This is the optional parameter which needs to be represented
    // in the PHPDoc block
    $collectiveAgreement = $request->query('collective_agreement');

    ...
}

Ответы [ 2 ]

0 голосов
/ 15 апреля 2020

Сохранить описание в первой строке и @param и @return под этим. Это будет своего рода стандартный порядок. Не стесняйтесь добавлять описание, как вы хотели бы, и как это поможет другим, кто читает код. В этом случае вы уже задокументировали param, поскольку эта строка запроса является частью $request объекта, но вы можете расширить описание так: 

/**
 * Returns list of Employers. 
 * Request object may have optional query string parameter 'collective_agreement'
 * used for this and this and that and that
 *
 * @param Request $request
 * @return Response
 */
public function index(Request $request)
{
    // This is the optional parameter which needs to be represented
    // in the PHPDoc block
    $collectiveAgreement = $request->query('collective_agreement');
    ...
}
0 голосов
/ 15 апреля 2020

Если ваша цель - документировать эти поля, я бы порекомендовал создать FormRequest, который обрабатывает все эти логики c, а затем внедрить запрос формы в контроллер. Таким образом, вы знаете, где формируется запрос, а затем go к этому классу, чтобы увидеть поля, и даже лучше: правила для них, чтобы пройти проверку. 

php artisan make:request ListUsersRequest

ListUsersRequest. php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class ListUsersRequest extends FormRequest {

    public function rules()
    {
        return [
            'collective_agreement' => ['here', 'goes', 'your', 'rules'],
            'another_field'        => ['here', 'goes', 'more', 'rules'],
        ];
    }

    public function authorize()
    {
        return true;
    }
}

Затем вернитесь к контроллеру

UserController. php

public function index(ListUsersRequest $request)
{   //                ^^^^^^^^^^^^^^^^
    $data = $request->validated();
    $collectiveAgreement = $data['collective_agreement'];
//  Or as you did:   
//  $collectiveAgreement = $request->query('collective_agreement');
}
...