请求参数和 phpdoc

Question

可能的重复：
是否有记录 GET/POST 参数的标准？

尝试找出通过 phpdoc 以有意义的方式记录请求参数的最佳方法。 具体来说，我有一些 Zend Framework 控制器操作，它们通过 GET/POST 接收参数，但不是功能参数。 这有道理吗？

/**
 * Display a pagination/grid list of rows.
 *
 * @param string $_GET['order']  What field to sort on
 * @param string $_GET['dir']    Direction to sort; either ASC|DESC
 * 
 * @return void
 */
public function listAction()
{
    $order = $this->_request->order;
    ...

如果我为此方法生成文档，则不会表明“order”和“dir”可以通过 url 字符串传递给此方法。 这样做更有意义吗？

@param string $order

我应该使用 @var 吗？

欢迎想法。

Answer 1

我会避免与@param搞混。

您还可以创建一个 _validate() 方法以使其在代码中显而易见。 然后您可以使用 _validate() 创建一个用于单元测试的接缝。

/**
 * Display a pagination/grid list of rows.
 *
 * Requires $_REQUEST['order'] and $_REQUEST['dir']
 * 
 * @return void
 */
public function listAction()
{
    list($order, $dir) = $this->_validate($this->_request);
    ...

private function _validate($request) {
    if (!$request->order)
         throw new InvalidArgumentException('"Order" must be in request');

    if (!$request->dir)
         throw new InvalidArgumentException('"Dir" must be in request');

    // maybe clean vars???
    //Zend_Filter_Numeric.....

    return array($request->order, $request->dir);
} 

Answer 2

我通常要么使用你建议的内容，要么在代码太长时添加一个简单的非 phpdoc 注释，或者什么都不做。

我相信，在这三者之间，您的解决方案是最好的。

您只需检查一件事：生成 phpdoc 时渲染效果是否良好？

理论上，由于 phpdoc 使用您在文档块中给出的名称，我想它应该......

如果是的话......那么，我没有看到更好的方法； 不需要更好的方法：我认为你不能做任何比这更干净/可读/可理解的事情。

我不喜欢这个

@param string $order

想法：没有任何内容表明 $order 应该在 $_GET 中给出，并且不是“真正的方法参数”； 所以我宁愿避免这种语法。

我从不使用 @var 作为参数，顺便说一句：仅用于变量，当我觉得需要记录它们时（这并不常见；至少对于短方法/代码部分）