Восемь причин изучить PHPDoc

Часто встречаю вопрос о том, что же это за странные блоки комментариев постоянно генерируются в представлениях:

<?php
<?php
/* @var $this yii\web\View */
/* @var $searchModel \app\models\search\UserSearch */
/* @var $dataProvider yii\data\ActiveDataProvider */
?>

в ActiveRecord-классах:

/**
 * This is the model class for table "{{%user}}".
 *
 * @property integer $id
 * @property string $username
 * @property string $auth_key
 * @property string $password_hash
 * @property string $email
 */
class User extends ActiveRecord
{
    ...
}

и перед всеми методами:

/**
 * Saves the current record.
 * @param boolean $runValidation whether to perform validation before saving the record.
 * @param array $attributeNames list of attribute names that need to be saved.
 * @return boolean whether the saving succeeded (i.e. no validation errors occurred).
 */
public function save($runValidation = true, $attributeNames = null)
{
    ...
}

Что они обозначают и зачем они нужны? Это какой-то особый синтаксис объявления переменных в PHP или что?

Нет, это не совсем синтаксис PHP. А точнее, к самому PHP он никакого отношения не имеет и сам PHP интерпретатор его никогда не парсит. Это PHPDoc-блок, зародившийся ещё как JavaDoc и перешедший в PHPDocumentor

Все эти вещи, судя по названию, как-то связаны с документацией. С неё и начнём.

Документация кода

Кому то стало лень писать документацию отдельно и он, вероятно, решил: «Отдельно документировать проект сложно и муторно. Нам же проще описывать прямо в комментариях каждый метод и класс. Давайте сделаем особый вид комментариев и при необходимости будем генерировать документацию по нему». И понеслось. В итоге придумали конструкции для объявления переменных, их типов и прочей метаинформации. И написали автоматический генератор, который парсит файлы в папке и генерирует HTML-файлы для каждого нашего класса.

Если посмотреть в API Reference и в код класса то увидим одно и то же:

namespace yii\db;
/**
 * ActiveRecord is the base class for classes representing relational data in terms of objects.
 *
 * ...
 *
 * As an example, say that the `Customer` ActiveRecord class is associated with the `customer` table.
 * This would mean that the class's `name` attribute is automatically mapped to the `name` column in `customer` table.
 * Thanks to Active Record, assuming the variable `$customer` is an object of type `Customer`, to get the value of
 * the `name` column for the table row, you can use the expression `$customer->name`.
 * In this example, Active Record is providing an object-oriented interface for accessing data stored in the database.
 * But Active Record provides much more functionality than this.
 *
 * To declare an ActiveRecord class you need to extend [[\yii\db\ActiveRecord]] and
 * implement the `tableName` method:
 *
 * ```php
 * <?php
 *
 * class Customer extends \yii\db\ActiveRecord
 * {
 *     public static function tableName()
 *     {
 *         return 'customer';
 *     }
 * }
 * ```
 * ...
 */
class ActiveRecord extends BaseActiveRecord
{
    ...
}

Теперь понятно, как этот сайт так быстро меняется при каждом обновлении исходников. Оказывается, что он составлен не вручную, а автоматически сгенерирован по коду фреймворка.

Так что можем уже сформулировать первый бонус, который нам дают PHPDoc-блоки:

Применение первое: Возможность одной командой в консоли сгенерировать документацию с описанием всех классов, полей и методов своего проекта.

Но кроме этого чем он полезен в реальной жизни? Рассмотрим ещё несколько применений.

Виртуальные поля

В модели данных он пригодится для той же автогенерации полей по классу, но для чего его используют в представлениях, которые в документации не выводятся?

Оказалось, что формат PHPDoc оказался настолько удачным, что его встроенную поддержку наряду с JavaDoc подхватили практически все IDE вроде PhpStorm, NetBeans и прочие. В PHP нет встроенной типизации для чисел и строк, поэтому указывать тип в комментарии (чтобы не забыть) было бы полезно. Вот и нашему PHP-редактору оттуда тоже оказалось удобно парсить переменные и их типы.

Например, был класс без полей:

class Post extends ActiveRecord
{
    public static function tableName() {
        return '{{%post}}';
    }
}

и непонятно что там, так как Yii2 берёт атрибуты из таблицы в базе данных. Автоподстановка видит только поля и методы из базового класса ActiveRecord:

А наши поля подчёркивает, при этом ругаясь, что их в объекте нет:

Можно заморочиться и написать плагин, который бы парсил поля из базы для каждой таблицы. Но это явно не лёгкий путь.

А давайте просто обозначим поля в PHPDoc-блоке (комментарии особой формы):

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property integer $created_at
 * @property integer $updated_at
 * @property string $title
 * @property string $content
 * @property integer $status
 */
class Post extends ActiveRecord
{
    public static function tableName() {
        return '{{%post}}';
    }
}

и редактору сразу станет понятно, какие поля теперь там есть для автоподстановки и какого они типа:

Теперь он в курсе наших дел и больше не ругается.

Или если в классе есть связи:

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property string $title
 * @property string $content
 */
class Post extends ActiveRecord
{
    public function getCategory()
    {
        return $this->hasOne(Category::className(), ['id' => 'category_id']);
    }
    public function getUser()
    {
        return $this->hasOne(Category::className(), ['id' => 'category_id']);
    }
    public function getTags()
    {
        return $this->hasMany(Tag::className(), ['id' => 'tag_id'])->viaTable(PostTag::tableName(), ['post_id' => 'id']);
    }
}

В коде мы можем использовать их просто как поля category, user и tags:

echo $post->category->name;
echo $post->user->username;
foreach ($post->tags as $tag) {
    echo $tag->name;
}

Но этих полей в классе нет. Всё работает через виртуальные методы и геттеры. Поэтому нам ничего не остаётся, как указать эти псевдополя и их типы явно:

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property string $title
 * @property string $content
 * @property User $user
 * @property Category $category
 * @property Tag[] $tags
 */
class Post extends ActiveRecord
{
    ...
}

Так что PHPDoc-блок перед классом может содержать полное перечисление того, чего в классе нет.

Применение второе: Указание псевдополей класса.

В примерах мы рассмотрели пока только поля. К псевдометодам подойдём позже.

Типы существующих полей

Помимо блока перед классом можно использовать и другие места.

Допустим, что у нас есть приватное поле _user у класса PasswordChangeForm:

class PasswordChangeForm extends Model
{
    ...
    private $_user;
    public function __construct($user, $config = [])
    {
        $this->_user = $user;
        parent::__construct($config);
    }
    ...
    public function changePassword()
    {
        if ($this->validate()) {
            $user = $this->_user;
            $user->setPassword($this->newPassword);
            return $user->save();
        } else {
            return false;
        }
    }
}

Но на строках:

$user = $this->_user;
$user->setPassword($this->newPassword);
return $user->save();

редактор впадает в ступор и методы setPassword и save подсвечивает жёлтым, мотивируя это тем, что таких методов в этой переменной нет:

А если мы подскажем, что там у нас находится объект класса User:

class PasswordChangeForm extends Model
{
    /**
     * @var User
     */
    private $_user;
}

то всё заработает как нам этого и хотелось.

Здесь мы аннотации @var передаём только тип. Но вообще ей можно передавать имя переменной, её тип или оба аргумента сразу.

Применение третье: Подсказка типов для имеющихся полей в классе.

Тип возвращаемого результата

Аналогично, если мы аннотацией @return укажем тип возвращаемого методом объекта:

class UsersController extends Controller
{
    /**
     * @param integer $id
     * @return User
     * @throws NotFoundHttpException
     */
    protected function findModel($id)
    {
        if (($model = User::findOne($id)) !== null) {
            return $model;
        } else {
            throw new NotFoundHttpException('The requested page does not exist.');
        }
    }
}

то при использовании этого метода наша система разработки поймёт, что внутри переменной $user после вызова данного метода окажется объект класса User:

class UsersController extends Controller
{
    public function actionUpdate($id)
    {
        $model = $this->findModel($id);
        if ($model->load(Yii::$app->request->post()) && $model->save()) {
            return $this->redirect(['view', 'id' => $model->id]);
        } else {
            return $this->render('update', [
                'model' => $model,
            ]);
        }
    }
}

и больше не будет ругаться на ранее неизвестные ей методы load и save.

А что если какой-либо метод возвращает нам либо User, либо null? Тогда можно перечислить варианты через вертикальную черту:

/**
 * @param integer $id
 * @return User|null
 */

И IDE будет учитывать оба случая.

Применение четвёртое: Подсказка типов аргументов и типа возвращаемого результата (при наличии) у процедур, функций, методов.

Переменные из ниоткуда

Или ещё вариант. Есть некое представление, в которое из контроллера передаётся переменная $model. К тому же, это представление рендерится в объекте класса \yii\web\View, который и будет доступен через $this:

<?php
<?php
use yii\helpers\Html;
use yii\widgets\DetailView;
$this->title = $model->meta_title;
$this->registerMetaTag(['name' => 'description', 'content' => $model->meta_description]);
$this->registerMetaTag(['name' => 'keywords', 'content' => $model->meta_keywords]);
$this->params['breadcrumbs'][] = ['label' => 'Блог', 'url' => ['index']];
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="user-view">
    <h1><?= Html::encode($this->title) ?></h1>
    ...
</div>

Но IDE не в курсе наших планов, поэтому сразу подсвечивает переменные $this и $model как не определённые в этом файле. Для исправления ситуации мы можем добавить сколько угодно Doc-блоков с аннотацией @var прямо внутрь кода представления:

<?php
<?php
use yii\helpers\Html;
use yii\widgets\DetailView;
/** @var $this \yii\web\View */
/** @var $model \app\models\User */
$this->title = $model->meta_title;
...
?>

При этом для @var можно указать сначала тип, потом имя переменной:

/** @var \app\models\User $model */

В итоге автоподстановка, поиск и автозамена полей и методов объектов заработают для этих переменных автоматически.

Применение пятое: Обозначение переменных, каким-либо образом переданных извне.

Подмена типа

Не всегда мы в контроллерах и прочих компонентах используем метод findModel. Часто можно напрямую в коде выполнить какой-нибудь запрос:

$model = Post::find()->where(['id' => $id])->andWhere(...)->one();
echo $model->title;

В итоге IDE по цепочке наследования подсмотрит аннотации метода ActiveRecord::find:

class ActiveRecord extends BaseActiveRecord
{
    /**
     * @inheritdoc
     * @return ActiveQuery the newly created [[ActiveQuery]] instance.
     */
    public static function find()
    {
        return Yii::createObject(ActiveQuery::className(), [get_called_class()]);
    }

и, так как указана аннотация @inheritdoc, пойдёт ещё выше в аннотации этого же метода в интерфейсе:

interface ActiveRecordInterface
{
    /**
     * Creates an ActiveQueryInterface instance for query purpose.
     * ...
     * @return ActiveQueryInterface the newly created [[ActiveQueryInterface]] instance.
     */
    public static function find();
}

и склеит всё воедино.

В итоге IDE по строке:

/**
 * @return ActiveQuery
 */

поймёт, что из метода find должен вернуться экземпляр класса \yii\db\ActiveQuery и методы where и one будут вызываться уже у него:

class ActiveQuery extends Query implements ActiveQueryInterface
{
    ...
    /**
     * Executes query and returns a single row of result.
     * @param Connection $db the DB connection used to create the DB command.
     * @return ActiveRecord|array|null a single row of query result.
     */
    public function one($db = null)
    {
        ...
    }
}

и здесь мы видим, что метод one возвращает либо экземпляр ActiveRecord, либо массив (если вызывали asArray()), либо null. Редактор так и будет думать, поэтому выдаст замечание при попытке обратиться к полю title:

$model = Post::find()->where(['id' => $id])->one();
echo $model->title;

Для правильной работы нам нужно явно указать тип переменной с помощью Doc-блока перед присваиванием:

/** @var \app\models\Post $model */
$model = Post::find()->where(['id' => $id])->one();
echo $model->title;

или непосредственно перед использованием объекта:

$model = Post::find()->where(['id' => $id])->one();
/** @var \app\models\Post $model */
echo $model->title;

Это удобно делать в циклах по различным выборкам:

foreach (Category::find()->orderBy('name')->each() as $category) {
    /** @var \app\models\Category $category */
    echo $category->title;
}

Применение шестое: Подмена типа уже существующих переменных.

И вернёмся к методам.

Подключение примесей

Вначале мы рассмотрели виртуальные переменные. Теперь предположим, что к своему классу мы примешиваем любое поведение вроде:

composer require yii-dream-team/yii2-upload-behavior

Его достаточно добавить в метод behaviors:

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property string $title
 * @property string $content
 * @property string $image
 */
class Post extends ActiveRecord
{
    ...
    public function behaviors()
    {
        return [
            [
                'class' => ImageUploadBehavior::className(),
                'createThumbsOnRequest' => true,
                'attribute' => 'image',
                'filePath' => '@webroot/uploads/posts/[[pk]].[[extension]]',
                'fileUrl' => '@web/uploads/posts/[[pk]].[[extension]]',
                'thumbPath' => '@webroot/uploads/posts/[[profile]]_[[pk]].[[extension]]',
                'thumbUrl' => '@web/uploads/posts/[[profile]]_[[pk]].[[extension]]',
                'thumbs' => [
                    'thumb' => ['width' => 100, 'height' => 100],
                    'preview' => ['width' => 250, 'height' => 180],
                ],
            ],
        ];
    }
}

и в представлениях выводить оригинал или превью:

<?php
<?= Html::img($post->getImageFileUrl('image')) ?>
<?= Html::img($post->getThumbFileUrl('image', 'preview')) ?>

А мы помним, что IDE ругается на всё, чего нет в классе. Но с помощью аннотации @mixin, которую поддерживает IDE PhpStorm и, возможно, некоторые другие, можно «подмешать» класс поведения:

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property string $title
 * @property string $content
 * @property string $image
 *
 * @mixin ImageUploadBehavior
 */
class Post extends ActiveRecord
{
    ...
}

и все методы getImageFileUrl и прочие будут доступны в автоподстановке.

Но есть один нюанс. Помимо нужных методов в классе поведения имеется и много ненужных. Например, вспомогательные resolveProfilePath или createThumbs, которые мы использовать не будем.

В таком случае вместо примешавания всего класса поведения с помощью @mixin мы можем просто добавить определение только пары нужных нам виртуальных методов:

/**
 * @property integer $id
 * @property integer $user_id
 * @property integer $category_id
 * @property string $title
 * @property string $content
 * @property string $image
 *
 * @method getImageFileUrl($attribute, $emptyUrl = null)
 * @method getThumbFileUrl($attribute, $profile = 'thumb', $emptyUrl = null)
 */
class Post extends ActiveRecord
{
    ...
}

Аналогично можно добавлять сигнатуры любых своих методов, работающих через свой магический метод __call.

Применение седьмое: Определение псевдометодов класса.

Программирование с аннотациями

Помимо простой работы с PHPDocumentor некоторые системы пошли дальше и придумали для своих целей собственные виды аннотаций. И некий программный код через рефлексию парсит эти данные. Взять хоть первый попавшийся пример с сайта StackOverflow:

$r = new ReflectionClass($class);
$doc = $r->getDocComment();
preg_match_all('#@(.*?)\n#s', $doc, $annotations);
print_r($annotations[1]);

Аналогично можно получить $r->getMethods() и парсить уже их.

В итоге этот подход нашёл новое применение. Например, в Symfony Framework с помощью собственных аннотаций (помимо конфигурации в YAML или XML-файлах) с использованием пакета doctrine/annotations можно конфигурировать те же сущности прямо в коде:

namespace AppBundle\Entity;
use Doctrine\ORM\Mapping as ORM;
/**
 * @ORM\Entity
 * @ORM\Table(name="product")
 */
class Product
{
    /**
     * @ORM\Column(type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;
    /**
     * @ORM\Column(type="string", length=100)
     */
    protected $name;
    /**
     * @ORM\Column(type="decimal", scale=2)
     */
    protected $price;
    /**
     * @ORM\Column(type="text")
     */
    protected $description;
}

или ту же маршрутизацию контроллеров:

class BlogController extends Controller
{
    /**
     * @Route("/blog/{slug}", name="blog_show")
     */
    public function showAction($slug)
    {
        // ...
    }
}

И фреймворк легко парсит эти данные и кеширует в простые PHP-массивы, чтобы не парсить их каждый раз снова и снова.

Также в уроке по тестированию мы рассматривали аннотации вроде @group и @dataProvider для тестов в пакете PHPUnit.

Этот подход уже мало связан с оригинальным PHPDoc, так как просто использует его идею. Но при этом друг другу никто не мешает и можно спокойно использовать различные ключи вместе:

class Product
{
    /**
     * @var string
     * @ORM\Column(type="string", length=100)
     */
    protected $name;
}

Многим такой подход с конфигурированием аннотациями в Symfony не нравится, так как он нарушает принцип единой ответственности, смешивая программный код и конфигурацию в одном файле. Так что используйте по своему усмотрению.

Восьмая причина: Появление программных систем с поддержкой специфических аннотаций.