Должен ли я использовать @return self, этот или текущий класс?

У меня есть метод, который возвращает текущий объект, как мне это документировать?

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

Или я должен сделать @return self или @return Current_Class_Name?

Причина, по которой этот вопрос не является "в первую очередь основанным на мнении" (и должен быть вновь открыт): соответствие стандартам и поддержка хинтинга типа IDE.

Ответ 1

@return Current_Class_Name определенно будет работать и я предпочитаю.

@return self может работать нормально и с некоторыми программами.

@return this плохо, потому что это не имя_файла.

Ответ 2

Существует Рекомендация по стандартам PHP (PSR), в настоящее время находящаяся в черновике (PSR-5), в которой предлагается @return$ this, чтобы указать, что возвращается тот же экземпляр.

$ this, элемент, к которому применяется этот тип, является тем же точным экземпляром, что и текущий класс в данном контексте. Таким образом, этот тип является более строгой версией static, так как, кроме того, возвращаемый экземпляр должен быть не только того же класса, но и того же экземпляра.

Этот тип часто используется в качестве возвращаемого значения для методов, реализующих шаблон проектирования интерфейса Fluent.

Эта нотация в настоящее время используется популярными IDE, такими как PhpStorm и Netbeans.

Ответ 3

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

Вы можете использовать тип "self" как @param или @return..

PHPDoc рекомендует "self" ссылаться на self в объекте.

Источник: http://www.phpdoc.org/docs/latest/references/phpdoc/types.html

Ответ 4

Этот вопрос довольно старый, но я просто хочу поделиться всем!

НА МЕНЬШЕ для тех, кто использует NetBeans 8.1. Эта нотация делает автозаполнение кода хорошо работать на IDE:

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

Я говорю "ПОСЛЕДНИЕ" для пользователей NetBeans8.1, но может работать и с более старыми версиями и/или с другими IDE =]