О сущностях Doctrine – Using Zend Framework 3

12.5. О сущностях Doctrine

Сущность (entity) - это PHP-класс, предназначенный для хранения данных. Ниже приведены несколько примеров наиболее часто используемых сущностей:

Сущность User предназначена для хранения информации о посетителе сайта. Она может содержать такие свойства, как логин, пароль, имя, фамилию и др.
Сущность License предназначена для хранения информации о лицензии программного обеспечения. Она может содержать такие данные, как уникальный ключ лицензии, ссылку на пользователя, который приобрел лицензию, дату создания лицензии и др.
Сущность Payment может содержать свойства, связанные с приобретением неких товаров. Такими свойствами являются: ID транзакции, сумма покупки, валюта и др.

С точки зрения DDD, сущности - это тип моделей, предназначенных для хранения данных. За дополнительными примерами сущностей и других типов моделей обратитесь к главе Модель-Представление-Контроллер.

В ORM Doctrine классу сущности ставится в соответствие определенная таблица базы данных. Например, сущности User обычно ставится в соответствие таблица user (имя таблицы, если нужно, может быть произвольным).

Для нашего приложения Blog мы создадим три класса сущностей:

Сущность Post будет содержать данные, связанные с определенным постом блога. Ее свойства будут точно такими же, какие мы использовали при определении таблицы post в схеме базы данных blog. Этот класс сущности также будет геттеры и сеттеры для получения/задания данных.
По аналогии, сущность Comment будет содержать данные, связанные с комментариями к посту блога.
и сущность Tag будет содержать данные, связанные с тегами.

12.5.1. Аннотации

Аннотация - это особый тип PHP-комментария, который предобрабатывается ORM Doctrine. Другие словами, аннотации - это метаданные, добавленные к классу сущности, которые могут быть прочитаны ORM Doctrine во время выполнения. Аннотации предоставляют подробную информацию о сущности. Они описывают сущность и сообщают ORM Doctrine, каким образом установить соответствие между ней и таблицей базы данных.

Аннотация Docblock - это комментарий в стиле языка C++, начинающийся со слеша (/) и двух звездочек (*). Эти "начальные" символы необходимы, иначе Doctrine не сможет распознать аннотацию. Пример аннотации показан ниже:

/**
 * Это аннотация DocBlock.
 */

Doctrine читает doc-блоки с помощью компонента Doctrine\Annotations.

Возможно, вы уже сталкивались с Dockblock-аннотациями, если вы используете такие инструменты генерации документации, как phpDocumentor или Doxygen. В этих инструментах аннотации выполняют ту же функцию: описывают PHP-класс, а также его свойства и методы. Затем инструмент проходит по коду и автоматически составляет HTML-документацию, полностью основанную на анализе кода и аннотаций.

Ниже, в качестве примера мы приведем базовый пример класса сущности Doctrine. Как видите, класс и его свойства помечены аннотациями Dockblock с помощью специальных тегов (тег начинается с символа '@').

<?php
namespace Application\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="post")
 */
class Post 
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(name="id")   
     */
    protected $id;

    /** 
     * @ORM\Column(name="title")  
     */
    protected $title;

    /** 
     * @ORM\Column(name="content")  
     */
    protected $content;

    /** 
     * @ORM\Column(name="status")  
     */
    protected $status;

    /**
     * @ORM\Column(name="date_created")  
     */
    protected $dateCreated;   
}

Рассмотрим фрагмент кода выше:

В строке 2 мы объявили пространство имен Application\Entity, где "живут" классы сущностей для модуля Application.

В строке 4, как вы можете заметить, мы используем класс Doctrine\ORM\Mapping и его псевдоним ORM для аннотаций Doctrine ⁴⁸.

⁴⁸⁾ Предоставляемые Doctrine теги аннотаций реализованы как классы, содержащиеся внутри пространства имен Doctrine/ORM/Mapping. Это сделано для того, чтобы избежать конфликтов имен аннотаций (например, в случае, когда какой-то другой компонент имет аннотацию с именем Entity или Table, возникнет конфликт имен).

В строках 6-9 находится аннотация DocBlock для класса Post. Каждый тег аннотации начинается с символа '@", имеет имя и (опционально) параметры, заключенные в круглые скобки.

Предоставляемые Doctrine теги, используемые в аннотациях могут быть двух типов: на уровне класса и на уровне свойства. Во фрагменте кода выше мы используем следующие теги на уровне класса (описывающие весь класс сущности):

тег @ORM\Entity (строка 7), объявляет, что этот класс является сущностью ORM Doctrine;
тег @ORM\Table(name="post") (строка 8) сообщает Doctrine ORM, что этому классу сущности поставлена в соответствие таблица БД post.

Свойства сущности описываются с помощью следующих тегов на уровне свойства:

@ORM\Id указывает, что это свойство является уникальным идентификатором сущности (строка 13);
@ORM\GeneratedValue используется для того, чтобы сообщить ORM Doctrine, что это свойство использует некоторую автосгенерированную последовательность для своей инициализации (строка 14). В MySQL это, как правило, означает, что соответствующий столбец таблицы использует инициализатор AUTO_INCREMENT.
@ORM\Column(name="<column_name>") используется для того, чтобы сообщить ORM Doctrine, с каким столбцом таблицы данному свойству необходимо установить соответствие (строки 15, 20, 25, 30, 35).

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