Question

是否存在记录采用单个配置数组的函数的语法，而不是单个参数？

我正在考虑CodeIgniter样式的库，它使用类似于此的机制：

<?php

//
// Library definition
//

class MyLibrary {
  var $foo;
  var $bar;
  var $baz;
  // ... and many more vars...


  /* Following is how CodeIgniter documents their built-in libraries,
   * which is mostly useless.  AFAIK they should be specifying a name
   * and description for their @param (which they don't) and omitting
   * @return for constructors 
   */

  /** 
   * @access public
   * @param array
   * @return void
   */
  function MyLibrary($config = array()) {
    foreach ($config as $key => $value) {
      $this->$key = $value;
    }
  }
}

//
// Library usage:
//

// Iniitialize our configuration parameters
$config['foo'] = 'test';
$config['bar'] = 4;
$config['baz'] = array('x', 'y', 'z');

$x = new MyLibrary($config);

?>

所以我的问题是，是否有一些支持的方法来记录配置数组，而不仅仅是纯粹的文本描述？实际上指定一个允许PHPDoc解析有用值的正确@param [type] [name] [desc]？

顺便说一句，CodeIgniter确实只是用上面通过$ config数组传入的值覆盖它自己的值，有效地允许你破坏私人成员。我不是粉丝，但我坚持不懈。

Answer 1

我从未见过记录这种情况的“好”方式 - 而且我从未见过IDE （例如Eclipse PDT）可用于参数提示的任何内容： - （

我会说“就像你的框架一样”，但正如你所说，它的作用，在这里，还不够好......

但是，可能快速/排序的可能键可能比没有更好;有点像这样：

@param array $config [key1=>int, otherKey=>string]

不确定它是如何被phpDocumentor或IDE解释的......但是可能值得一试？

这是，顺便说一句，我倾向于避免使用这种传递参数的方式的一个原因 - 至少在方法没有太多（可选）参数时。

Answer 2

数组的正确数组@param表示法在PHPlint

中指定

您可以使用它以有用的方式记录配置数组：

示例：

/** * Does stuff * * @param array[int|string]array[string]Object $config * * @return array[int]string */ public function foo(array $config) { // do stuff here return array('foo', 'bar', 'baz'); }

Answer 3

你可以这样做：

/**
 * @param array $param1
 * @param string $param1['hello']
 */
function hey($param1)
{
}

和netbeans将接收它，但phpdoc会弄乱文档

Answer 4

我总是在这种情况下使用<pre>标签。例：

/**
 * @param array $ops An array of options with the following keys:<pre>
 *     foo: (string) Some description...
 *     bar: (array) An array of bar data, with the following keys:
 *         boo: (string) ...
 *         far: (int) ...
 *     baz: (bool) ...
 * </pre>
 */

我使用过的大多数IDE和文档生成器似乎都以合理的方式呈现它，当然它们不提供任何类型检查或检查数组参数。

Answer 5

目前没有“官方”（如“多工具支持”）的方式。

PHP FIG正在https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

进行讨论

Answer 6

文字描述，无论您想要什么程度的完整性，都是您唯一的选择。您可以根据需要使其清晰易读，但代码分析工具（phpDocumentor，IDE支持）无法知道您的$array在运行时的实际结构。

我同意许多评论者以这种方式编写代码，以便为代码易读性提供便利。

Answer 7

我使用过课程。

<?php
class MyLibrary {
    var $foo;
    var $bar;
    var $baz;

    /**
     * @param MyLibraryConfig|null $config
     */
    function MyLibrary( $config = null ) {
        if ( isset( $config->foo ) ) {
            $this->foo = $config->foo;
        }
        if ( isset( $config->baz ) ) {
            $this->baz = $config->baz;
        }
        if ( isset( $config->bar ) ) {
            $this->bar = $config->bar;
        }
    }
}

/**
 * @property string $foo
 * @property int    $bar
 * @property array  $baz
 */
class MyLibraryConfig {
}

它工作得很好，主要问题是代码中充斥着特定的类。它们可以嵌套，因此可以重用部分配置。

PHPDoc用于可变长度的参数数组

7 个答案: