Entity

Общее описание

Класс Entity является базовым классом для всех сущностей CRM-системы Ultralight CRM. Это родительский класс, от которого наследуются все типы сущностей в системе, обеспечивая единый интерфейс для работы с различными типами данных.

Основная информация

• Полный путь: App\Models\Entity
• Класс-родитель: Model (Laravel Eloquent)
• Назначение: Базовый класс для всех сущностей системы

Назначение

Класс Entity предназначен для:

• Обеспечения единого интерфейса для всех сущностей системы
• Реализации базовой функциональности для работы с сущностями
• Хранения метаданных о сущности (идентификатор, тип, права доступа)
• Интеграции с системой управления правами доступа
• Поддержки расширяемости через наследование

Методы

initialize(int $id, int $typeId, bool $dnCheckRights = false)

Инициализирует экземпляр сущности с указанными параметрами.

Параметры:

• $id — идентификатор экземпляра сущности
• $typeId — идентификатор типа сущности
• $dnCheckRights — флаг, указывающий, нужно ли проверять права доступа (необязательный, по умолчанию false)

Пример использования:

// Инициализация сущности
$entity = new CrmUser();
$entity->initialize(1, 1);

getField(string $name)

Получает значение поля сущности по его имени.

Параметры:

• $name — имя поля

Возвращает: Значение поля

Пример использования:

// Получение значения поля
$name = $entity->getField('name');
$email = $entity->getField('email');

setField(string $name, $value)

Устанавливает значение поля сущности.

Параметры:

• $name — имя поля
• $value — новое значение поля

Пример использования:

// Установка значения поля
$entity->setField('name', 'Иван Иванов');
$entity->setField('email', 'ivan@example.com');

// Сохранение изменений
$entity->save();

delete()

Удаляет экземпляр сущности из базы данных.

Пример использования:

// Удаление сущности
$entity->delete();

save()

Сохраняет изменения в экземпляре сущности.

Пример использования:

// Изменение и сохранение сущности
$entity->setField('name', 'Новое имя');
$entity->save();

Свойства

Класс Entity содержит следующие свойства:

Публичные свойства

• public $timestamps = false — отключает автоматическое управление полями created_at и updated_at
• public int $accessRight = 2 — уровень прав доступа (2 — доступ запрещен по умолчанию)

Защищенные свойства

• protected $table = null — имя таблицы (устанавливается в наследниках)

Приватные свойства

• private int $typeID = 0 — идентификатор типа сущности
• private int $entityId = 0 — идентификатор экземпляра сущности
• private array $fieldsInfo = [] — информация о полях сущности

Особенности реализации

Наследование

Класс Entity служит основой для всех сущностей системы. Все конкретные сущности наследуют от него:

// Пример наследования
class CrmUser extends Entity {
    protected $table = 'crm_user';
}

class CrmGroup extends Entity {
    protected $table = 'crm_group';
}

Trait EntityTrait

Класс использует trait EntityTrait, который предоставляет дополнительную функциональность:

• Реализацию методов initialize, getField, setField, delete, save
• Интеграцию с системой управления правами
• Дополнительные утилиты для работы с сущностями

use App\Traits\EntityTrait;

class Entity extends Model {
    use EntityTrait;
}

Отключение timestamps

public $timestamps = false;

Свойство timestamps отключено, так как система использует собственную логику управления временем создания и обновления сущностей.

Принципы работы

Инициализация сущности

При создании экземпляра сущности необходимо вызвать метод initialize():

$entity = new CrmUser();
$entity->initialize($id, $typeId);

Это позволяет:

• Установить идентификаторы сущности
• Загрузить метаданные о полях
• Проверить права доступа

Работа с полями

Для доступа к полям сущности используются методы getField() и setField() вместо прямого доступа к свойствам:

// Правильно
$name = $entity->getField('name');
$entity->setField('name', 'Новое имя');

// Неправильно (может не сработать)
$name = $entity->name;
$entity->name = 'Новое имя';

Права доступа

Система проверяет права доступа при попытке чтения/записи данных:

• Уровень доступа хранится в свойстве $accessRight
• Значение определяется через CrmAuthorization::getAccess()
• По умолчанию установлено значение 2 (доступ запрещен)

Практическое использование

Создание новой сущности

// Создание новой сущности через EntityTable
$entity = EntityTable::createEntity(1, [
    'name' => 'Иван Иванов',
    'email' => 'ivan@example.com',
    'password' => bcrypt('secret')
]);

// Инициализация сущности
$user = new CrmUser();
$user->initialize($entity->entityId, 1);

Получение существующей сущности

// Получение сущности через EntityTable
$entities = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 1,
    'FILTER' => [['id', '=', 1]]
]);

if (!empty($entities)) {
    $user = $entities[0];
    
    // Работа с полями
    echo $user->getField('name');
    echo $user->getField('email');
}

Обновление сущности

// Обновление полей сущности
$user->setField('name', 'Новое имя');
$user->setField('email', 'newemail@example.com');

// Сохранение изменений
$user->save();

Удаление сущности

// Удаление сущности
$user->delete();

Безопасность

Проверка прав доступа

Система реализует проверку прав на нескольких уровнях:

1. На уровне EntityTable — при получении сущностей
2. На уровне CrmAuthorization — при проверке прав
3. На уровне методов — в методах getField, setField, save, delete

Уровни доступа

Уровень	Описание
0	Полный доступ (чтение и запись)
1	Только чтение
2	Доступ запрещен

Защита от несанкционированного доступа

• Прямой доступ к полям через свойства запрещен
• Все операции проходят через методы с проверкой прав
• Даже если данные загружены, операции записи будут отклонены без прав

Рекомендации по использованию

1. Всегда инициализируйте сущность — вызывайте initialize() после создания экземпляра
2. Используйте методы для доступа к полям — getField() и setField()
3. Проверяйте права — перед выполнением операций записи
4. Не изменяйте базовые свойства — $typeID, $entityId, $fieldsInfo
5. Наследуйтесь правильно — устанавливайте $table в наследниках

Заключение

Класс Entity является фундаментальным компонентом архитектуры Ultralight CRM. Он обеспечивает единый интерфейс для работы со всеми типами сущностей, реализует базовую функциональность и интегрируется с системой управления правами доступа. Благодаря своей простой, но эффективной архитектуре, класс позволяет легко расширять систему новыми типами сущностей, сохраняя при этом единый подход к их обработке и безопасности.