Wie deklarieren Sie unbegrenzte Parameter in DocBlock?

Question

Lets sagen, ich habe eine Funktion (offensichtlich ein triviales Beispiel):

public function dot(){ 
    return implode('.', func_get_args()); 
} 

Jetzt weiß ich, ich könnte diese

public function dot(array $items){ 
    return implode('.', $array); 
} 

aber mit einigen Funktionen ändern, ist keine Option. Also, wie würden Sie die erste Version der Funktion mit einem docBlock dokumentieren, damit eine IDE interpretieren kann, dass sie unbegrenzte Parameter erhalten kann?

Ich habe einige Methoden gesehen, die verwenden:

/** 
* Joins one or more strings together with a . (dot) 
* @param string $string1 
* @param string $string2 
* @param string $_ [optional] 
* @return string 
*/ 
public function dot($string1, $string2, $_ = null) { 
    return implode('.', func_get_args()); 
} 

, die in einer IDE wie

Aber das fühlt sich an wie ein Hack mir sehen, gibt es keine Möglichkeit, es nur mit Docblock zu tun?

Answer 1

In PHP existiert das Konzept der Valist oder Liste der "optionalen Argumente" nicht.

Die $_ Variable wird nur enthalten, hier die dritte Zeichenfolge, die Sie geben. Die einzige Möglichkeit, ein Array oder eine Zeichenfolge zu ermöglichen ist das erste Argument zu testen, mit is_array()

public function dot($arg1){ 
    if(is_array($arg1)){ 
     return implode('.',$arg1); 
    } 
    else if $arg1 instanceof \Traversable){ 
     return implode('.',iterator_to_array($arg1)); 
    } 
    else{ 
     return implode('.',func_get_args()); 
    } 
} 

Jetzt, wo Sie das Verhalten behandelt Sie wollen, müssen Sie es dokumentieren. Da in php das Überladen nicht zulässig ist, sollte eine Konvention den Typ "gemischt" als Typ verwenden, wenn Sie mehrere Typen bereitstellen möchten.

/** 
*@param mixed $arg1 an array, iterator that will be joined OR first string of the list 
*@return string a string with all strings of the list joined with a point 
*@example dot("1","2","3"); returns 1.2.3 dot(array(1,2,3)); returns 1.2.3 
*/ 

Darüber hinaus sind nach phpdocumentor documentation können Sie Art von valist mit

/** 
*@param string ... list of strings 
*/ 

Answer 2

[AKTUALISIERT 2015.01.08]

alte Art und Weise, dies zu tun in PHPDoc erklären war:

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

/** 
* @param int $param,... 
**/ 

Dies wird jedoch nicht mehr unterstützt. Ab PHP 5.6 sind Variadic-Methodenparameter ein Teil der PHP-Sprache und die PHPDocs wurden aktualisiert, um dies ab PHPDoc 2.4 wiederzugeben, wenn ich mich richtig erinnere. Dies ist auch in der PhpStorm IDE ab EAP 139.659 (sollte in 8.0.2 und höher sein). Nicht sicher über die Implementierung anderer IDEs.

https://youtrack.jetbrains.com/issue/WI-20157

in jedem Fall die richtige Syntax für DocBlocks vorwärts für variadische Parameter gehen ist:

/** 
* @param int ...$param 
**/ 

Answer 3

Wie Variadics implementiert sind in PHP 5.6 PHPDocumentor sollte die folgende Syntax wie von version 2.4 unterstützen.

Dies sollte der richtige Weg sein, um eine solche Signatur zu beschreiben. Dies wird likely in PSR-5 enthalten sein.Sobald dies akzeptiert ist, sollten IDEs folgen, um diese "offizielle" Empfehlung zu unterstützen.

Allerdings haben einige IDEs eine verbesserte Verständnis dessen, was sie richtig halten. Schlagen Sie hart auf den IDE-Hersteller, um die offizielle PHP-Syntax zu unterstützen, die ab Version 5.6 unterstützt wird, oder verwenden Sie, was auch immer in der Zwischenzeit funktioniert.