Devo usar @return self, this ou a class atual?

Eu tenho um método que retorna o object atual, como eu documento isso?

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

Ou devo fazer @return self ou @return Current_Class_Name ?

@return Current_Class_Name definitivamente funcionará e é o que eu prefiro.

@return self pode funcionar bem com alguns programas também.

@return this é ruim porque este não é um nome típico.

Existe uma Recomendação de Padrões PHP (PSR) atualmente no rascunho (PSR-5) que propõe @return $ isso é usado para indicar que a mesma instância é retornada.

$ this, o elemento ao qual este tipo se aplica é a mesma instância exata que a class atual no contexto dado. Como tal, esse tipo é uma versão mais rigorosa da estática, pois, além disso, a instância retornada não deve ser apenas da mesma class, mas também da mesma instância.

Esse tipo é freqüentemente usado como valor de retorno para methods que implementam o padrão de design Fluent Interface.

Esta notação é usada atualmente por IDEs populares, como PhpStorm e Netbeans.

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

Você pode usar o tipo “self” como @param ou @return ..

PHPDoc recomenda “auto” para se referir a si próprio no object ..

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

Esta questão é bastante antiga, mas eu só quero compartilhar com todos!

Pelo menos para aqueles que usam NetBeans 8.1 … esta notação faz com que o código de autocompleção funcione bem no IDE:

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

Eu digo pelo menos para usuários do NetBeans8.1, mas pode trabalhar em versões antigas e / ou outros IDEs também =]