6

可能重复:
是否有记录 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 吗?

欢迎提出想法。

4

2 回答 2

6

我会避免使用@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);
} 
于 2009-08-12T22:49:58.727 回答
1

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

在这三个之间,我相信你的解决方案是最好的。


您应该检查的只有一件事:当您生成 phpdoc 时,这是否能很好地呈现?

理论上,由于 phpdoc 使用您在 doc-block 中给出的名称,我想它应该......

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


我不喜欢

@param string $order

想法:没有任何东西表明$order应该给出$_GET并且不是“真正的方法参数”;所以我宁愿避免这种语法。


我从不使用@var 作为参数,顺便说一句:仅用于变量,当我觉得需要记录它们时(这并不常见;至少对于简短的方法/部分代码)

于 2009-08-12T22:43:05.680 回答