Сущность (entity) - это PHP-класс, предназначенный для хранения данных. Ниже приведены несколько примеров наиболее часто используемых сущностей:
Сущность User
предназначена для хранения информации о посетителе сайта. Она может
содержать такие свойства, как логин, пароль, имя, фамилию и др.
Сущность License
предназначена для хранения информации о лицензии программного обеспечения. Она
может содержать такие данные, как уникальный ключ лицензии, ссылку на пользователя, который приобрел
лицензию, дату создания лицензии и др.
Сущность Payment
может содержать свойства, связанные с приобретением неких товаров. Такими свойствами
являются: ID транзакции, сумма покупки, валюта и др.
С точки зрения DDD, сущности - это тип моделей, предназначенных для хранения данных. За дополнительными примерами сущностей и других типов моделей обратитесь к главе Модель-Представление-Контроллер.
В ORM Doctrine классу сущности ставится в соответствие определенная таблица базы данных. Например, сущности
User
обычно ставится в соответствие таблица user
(имя таблицы, если нужно, может быть произвольным).
Для нашего приложения Blog мы создадим три класса сущностей:
Сущность Post
будет содержать данные, связанные с определенным постом блога. Ее свойства
будут точно такими же, какие мы использовали при определении таблицы post
в схеме базы данных
blog
. Этот класс сущности также будет геттеры и сеттеры для получения/задания данных.
По аналогии, сущность Comment
будет содержать данные, связанные с комментариями к посту блога.
и сущность Tag
будет содержать данные, связанные с тегами.
Аннотация - это особый тип 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 48.
48) Предоставляемые 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 тегов, используемых в аннотациях, можно найти по следующей ссылке.