在 PHPDoc 中描述控制器查询参数

Question

我的 Laravel 控制器有一个索引方法，它接受一个可选的查询字符串参数。

这应该如何在方法的 PHPDoc 块中表示？

雇主控制器.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');

    ...

}

Answer 1

如果您的目的是记录这些字段，我建议创建一个处理所有逻辑的 FormRequest，然后将表单请求注入控制器。这样，您就知道请求是在哪里形成的，然后去那个类查看字段甚至更好：它们通过验证的规则。php artisan make:request ListUsersRequestListUsersRequest.phpnamespace 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;    }}然后，回到你的控制器用户控制器.phppublic function index(ListUsersRequest $request){   //                ^^^^^^^^^^^^^^^^    $data = $request->validated();    $collectiveAgreement = $data['collective_agreement'];//  Or as you did:   //  $collectiveAgreement = $request->query('collective_agreement');}

Answer 2

将描述放在第一行@param及其@return下方。这将是一种标准顺序。随意添加描述，以及它如何帮助其他阅读代码的人。在这种情况下，您已经记录了参数，因为该查询字符串是$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');    ...}