Компонент Entity (Сущность)

Сущность – это некий набор данных, которые называют «свойствами» (property). Например, сущность «Пользователь» (User) имеет такие свойства, как идентификатор, логин, адрес электронной почты, и т.д. Нередко сущность – это запись из таблицы базы данных, и тогда ее свойства соответствуют полям таблицы. Но в общем случае сущность вовсе не обязательно должна отображать структуру какой-то таблицы, а может использоваться просто как удобный способ организации какого-то набора данных.

Все классы сущности имеют в своих предках класс Entity, и, как правило, связаны с каким-либо модулем (Module) самого движка или плагина.

Если есть сущность, у которой есть свойство «first_name», то обратиться к нему можно так:

$oUser->getFirstName();
$oUser->getProp('first_name');

Эти два способа идентичны. Причем, метода getFirstName() на самом деле может не существовать в классе сущности, и он будет с помощью «магического метода» PHP __call() преобразован в вызов getProp('first_name').

Если запрашиваемое свойство не существует, то вернется значение NULL. Но т.к. свойство может хранить в себе любые значения, в т.ч. и NULL, и бывают ситуации, когда важно знать — действительно свойство не задвалось или ему было задано значение NULL, — то есть специальный метод, который поможет определить, существует свойство у сущности или нет:

$oUser->hasProp('avatar'); // возвращает TRUE или FALSE

Присвоение значения сущности:

$oUser->setFirstName('Alex');
$oUser->setProp('first_name', 'Alex');

Как уже говорилось, свойству можно назначить любое значение, в т.ч. массив и объект.

Другие полезные методы для работы со свойствами сущности:

appendProp($sName, $Subname, $xValue)

Добавляет элемент к свойству-массиву, например:

$oUser->appendProp('contacts', 'email', 'alex@gmail.com');
$oUser->appendProp('contacts', 'phone', '1-836-739-1462');

Это будет равнозначно такому коду:

$oUser->setContacts(['email' => 'alex@gmail.com', 'phone' => '1-836-739-1462']);

setPropMask($sKey, $xMask, $bAnd)

Устанавливает битовую маску для указанного свойства сущности.

getPropMask($sKey, $xMask)

Возвращает значение свойства по битовой маске для указанного свойства сущности.