Dois-je utiliser @return self, this ou la classe actuelle ?

Question

J'ai une méthode qui renvoie l'objet courant, comment puis-je documenter cela ?

/**
 * set something
 *
 * @return this
 */
public function setSomething(){
            // ...
    return $this;
}

Ou devrais-je le faire ? @return self o @return Current_Class_Name ?

---

Raison pour laquelle cette question n'est pas "principalement basée sur l'opinion" (et devrait être rouverte) : conformité aux normes et prise en charge de l'indication du type d'IDE.

Answer 1

Il existe un Recommandation sur les normes PHP (PSR) actuellement en projet (PSR-5) qui propose @return $this est utilisé pour indiquer que la même instance est renvoyée.

$this, l'élément auquel ce type s'applique est exactement la même instance que la classe actuelle dans le contexte donné. En tant que tel, ce type est une version plus stricte de static car, en outre, l'instance renvoyée doit être non seulement de la même classe, mais aussi de la même instance.

Ce type est souvent utilisé comme valeur de retour pour les méthodes mettant en œuvre le modèle de conception Fluent Interface.

Cette notation est actuellement utilisée par des IDE populaires tels que PhpStorm et Netbeans.

Answer 2

@return Current_Class_Name fonctionnera sans aucun doute et c'est ce que je préfère.

@return self peut également fonctionner avec certains programmes.

@return this est mauvais car ce n'est pas un nom de type.

Answer 3

Cette question est assez ancienne, mais je tiens à en faire part à tout le monde !

AU MOINS pour ceux qui utilisent NetBeans 8.1 cette notation rend l'autocomplétion du code pour qu'elle fonctionne bien à l'IDE :

/**
 * Method that returns $this instance (using late state binding)
 * @return static
 */
 public function iWillReturnMyself ( ) {
     return $this;
 }

Je dis AU MOINS pour les utilisateurs de NetBeans8.1, mais peut fonctionner sur des versions plus anciennes et/ou d'autres IDEs aussi =]

Answer 4

/**
 * set something
 *
 * @return self
 */
public function setSomething(){
            // ...
    return $this;
}

Vous pouvez utiliser le type "self" comme @param ou @return.

PHPDoc recommande 'self' pour se référer à soi dans l'objet

Fuente: http://www.phpdoc.org/docs/latest/references/phpdoc/types.html