Describing controller query parameters in PHPDoc - php

Question

My Laravel controller has an index method on it which accepts an optional query string parameter.
How should this be represented in the method's PHPDoc block?
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');
...
}

Answer 1

If your purpose is to document those fields, I'd recommend to create a FormRequest that handles all that logic, and then inject the form request into the controller. This way, you know where the request is formed and then go to that class to see the fields and even better: the rules for them to pass the validation.
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;
}
}
Then, back to your controller
UserController.php
public function index(ListUsersRequest $request)
{ // ^^^^^^^^^^^^^^^^
$data = $request->validated();
$collectiveAgreement = $data['collective_agreement'];
// Or as you did:
// $collectiveAgreement = $request->query('collective_agreement');
}

Answer 2

Keep description in first line and #param and #return under that. It would be sort of standard order. Feel free to add description as you would like and how it would help other who read the code. In this case you've already documented param since that query string is part of $request object but you can extend description to be like:
/**
* 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');
...
}