79
Является обязательным полем.
Таблица №17
Базовые поля сущности details_contact.
Название поля
Метка поля
Тип поля
Доп. информация
Дата создания
created
created
Поле хранящее timestamp даты
создания материала. Является
обязательным полем.
Дата
изменения
changed
changed
Поле хранящее timestamp даты
последнего изменения материала.
Является обязательным полем.
Таблица №18
Базовые поля сущности details_project.
Название поля
Метка поля
Тип поля
Доп. информация
Заголовок
title
string
Заголовок или название компании.
Является обязательным полем.
Дата создания
created
created
Поле хранящее timestamp даты
создания материала. Является
обязательным полем.
Дата
изменения
changed
changed
Поле хранящее timestamp даты
последнего изменения материала.
Является обязательным полем.
Статус
проекта
status
boolean
Поле хранящее булевое значение о
текущем статусе проекта. TRUE -
означает что проект активен,
FALSE - проект больше не
активен.
Также у всех сущностей есть геттеры (37) и сеттеры (38) для полей
добавляемые вместе с сущностью, как базовых, так и конфигурационных. В
приложении №8 приведен пример геттера и сеттера для даты рождения
контактного лица, которые позволяют получить текущее значение и установить
новое, которое будет сконвертировано в требуемый формат хранения.
Как правило геттеры и сеттеры сводятся к простому получению и
установке значений, которые итак доступны через методы get() и set() от
80
сущностей, но их принято описывать отдельно, так как, во первых, они выходят
короче, а во вторых, они не динамичные и заранее известны, в таком случае, нет
никакого смысла использовать методы где необходимо указывать названия поле,
а проще описать семантический метод.
Описание интерфейсов для объектов в PHP не является обязательным, они
создаются на усмотрение разработчика. В Drupal считается best-practice
32
добавление интерфейсов для своих объектов, в особенности для таких
комплексных как сущность. В связи с этим у всех объектов сущностей
описанных в модулях присутствуют интерфейсы, которые они расширяют.
Данные интерфейсы описывают методы, которые были добавлены сущности и
содержат в себе краткое описание, полное описание при необходимости, список
всех аргументов метода, если такие имеются, и их типы и описание для них,
возвращаемые значения, их типы и описание. В приложении №9 приведен
пример интерфейса для сущности “Проект”, где описаны все методы данной
сущности. Данные интерфейсы также наследуют стандартные интерфейсы от
ядра, таким образом, формируется полная картина происходящего и что за что
отвечает. Их связи также продемонстрированы на рисунке 21.
Каждая сущность, обычно, имеет определенные поля в которых хранятся
значения. Базовые поля объявляются при помощи метода baseFieldDefinition()
объекта сущности, а все остальные поля также являются сущностями, но уже
конфигурационными. Так, каждое поле имеет свои конфигурационные YAML
файлы содержащие информацию о поле-сущности и на основе которого строятся
все данные, отображение и т.д. Данные конфигурационные-сущности для полей
также подключаются к сущности и используются ею для хранения данных.
Есть два способа добавления дополнительных полей для сущности.
Первый способ заключается в создании конфигурационной-сущностей для полей
при помощи программного кода в определенные моменты, так и при помощи
создания YAML файла с необходимой структурой, названием и описанием,
которые автоматически будут преобразованы в поля сущности. Так как
конфигурационные сущности, независимо от того, как были добавлены на сайт,
через программный код или же описанные заранее конфигурационные-файлы,
32
Лучшая практика.
81
все равно в итоге будут экспортироваться для хранения в файлы, разумнее всего
добавлять конфигурационные сущности в поставке по умолчанию при помощи
файлов, если не требуется динамическая генерация данных полей. Если
информация и условия заранее известны, то проще и быстрее всего делать это в
файлах.
Конфигурационные файлы поставляемые с модулями находятся в
соответствующих папках модулей:
● config/install: Папка содержащая конфигурационные файлы, которые
будут принудительно импортированы в активную конфигурацию при включении
модуля. В дальнейшем данные файлы никак не используются. Попадая в
активную конфигурацию, они настраиваются либо через файлы активной
конфигурации, или пользовательский интерфейс, если такой допустим. При
попытке включения модуля, данные конфигурации проходят проверку на
валидность их структуры и присутствия всех данных и зависимостей. Если что-
то пошло не так в момент установки, модуль будет автоматически отключен
пока проблема не будет решена. Конфигурации в данной папки все до единой
обязательные на импорт.
● config/options: Аналогичная папка как и config/install, с тем отличием,
что конфигурации из нее являются опциональными, и если, по каким-то
причинам, условия для конфигураций не были выполнены, они просто будут
пропущены без прерывания процесса установки и включения модуля и каких-
либо ошибок.
Так как сущности описываемые в модулях для данной ИС и по её
требованиям описанным в пункте 1.2.2, должны иметь строго определенные
поля, мы их должны поставлять вместе с модулем.
Каждый из трех модулей описывает и добавляем свои собственные поля к
своим сущностям. Поля являются уникальными в пределах одной сущности. Так,
может быть поле field_name для каждой сущности, но не может быть два таких
поля в пределах одной сущности. При этом, данное поле может быть
совершенно разных типов в разных сущностях, иметь совершенно разные
настройки поведения и хранения данных.
82
Поля объявляемые через конфигурационные-сущности состоят из двух
файлов:
● field.storage.{ENTITY_TYPE}.{FIELD_NAME}.yml: Сторейдж
33
файл
является описывающим базовые свойства поля. В нем описываются базовые
значения. Для примера, рассмотрим сотрейдж для поля address (Адрес) сущности
details_contact (Контактное лицо), которое хранит информацию об адресе
контактного лица из приложения №10:
○ langcode - код языка, на котором данная конфигурация описана. Как
правило, для базовых значений всегда используется en (English). На основе
данного значения Drupal принимает решение, необходимо ли строковые
значения переводить, и с какого языка на какой.
○ status - булевое значение со статусом данного поля, включено оно или
нет.
○ dependencies - массив со списком конфигураций (config) и модулей
(module) от которых данная конфигурация зависит. Указанные здесь
конфигурации и модули должны присутствовать и быть активны на момент
импорта.
○ id - машинное имя конфигурации. Должно соответствовать названию
файла, без расширения yml и приставки field.storage. В случае несоответствия
данная конфигурация признается невалидной.
○ field_name - машинное название поля.
○ entity_type - тип сущности к которой данное поле относится.
○ type - машинный тип поля.
○ settings - различные настройки хранилища поля, если имеются.
○ module - модуль, который отвечает за type поля.
○ locked - булевое значение, позволяющее “заблокировать” поле для
сущности. Так, данное поле будет невозможно удалить через UI, кнопки для
управления будут удалены.
○ cardinality - числовое значение отвечающее за то, сколько значений
своего типа оно может хранить в данном поле. -1 используется для указания
“неограниченного” количества значений в поле.
33
Хранилище.
83
○ translatable - булевое значение указывающее, могут ли быть значения
данного поля быть переведены в случае активации мультиязычности. Если
указано FALSE, то значения данного поля будут во всех языках иметь значение
своего оригинала.
○ indexes - массив с ключами индексов поля для базы данных. Как
правило, предусмотрено для экзотических ситуаций и не используется по
умолчанию нигде.
○ persist_with_no_fields - булевое значение, которое позволяет
сохранить поле у сущности если его удалили. Если locked не установлен в true,
то поле можно будет удалить через интерфейс, даже если оно добавлено
модулем. При текущем значении в false, оно удалит и storage поля, что позволит
создать одноименное поле через UI или программно и поменять его логику, тип
и всё остальное. Если же значение установлено в TRUE, то данное поле будет
хранить storage конфигурацию поля. Его всегда можно будет воссоздать обратно,
и другие поля с данным именем создать будет невозможно.
○ custom_storage - булевое значение отвечающее за то, есть ли у поля
собственное хранилище, отличное от оригинального.
● field.field.{ENTITY_TYPE}.{BUNDLE_TYPE}.{FIELD_NAME}.yml:
Описание одного экземпляра поля в пределах одной сущности. Некоторые
сущности могут иметь различные подтипы, которых у наших сущностей нет, что
в таком случае заменяется на тип сущности. Одно и тоже поле описанное в
сторейдже, может иметь различные варианты в пределах одной сущности. В
нашем случае это будет 1 вариант, так как нет вариативности, но там где есть,
это позволяет делать немного различные поведения одних и тех же полей в
пределах их возможностей и структуры хранения данных. Рассмотрим
возможности на примере поля address для сущности details_contact (Контактное
лицо) из приложения №11. Некоторые возможности опущены, так как являются
точными копиями из описаний выше.
○ field_name - название поля, по нему будет производиться соответствие
с конфигом описывающим сторейдж.
○ entity_type - тип сущности, для которого полей, по нему будет
производиться соответствие с конфигом описывающим сторейдж.
84
○ bundle - подтип сущности, для которого внедряется вариант поля. У
объявляемых сущностей нет подтипа, в таком случае задается название
сущности.
○ label - метка поля, для конкретного экземпляра.
○ description - описание поля, для конкретного экземпляра.
○ required - является ли экземпляр поля обязательным.
○ translatable - является ли экземпляр поля переводимым.
○ default_value - значение по умолчанию.
○ default_value_callback - колбек
34
для значения по умолчанию.
Позовляет задавать его динамически.
○ settings - настройки поля определенного типа.
○ field_type - тип поля.
Таким образом формируется сущность, поля для неё и вся необходимая
логика для хранения данных.
Каждый модуль также определяет свои собственные права доступа в
{MODULENAME}.permissions.yml. Данный файл состоит из массивов, где
ключом является название права доступа, а его значения, его описанием.
Рассмотрим на примере права доступа, объявляемые модулем details_company из
приложения №12:
● title - метка доступа, отображаемая на странице управления правами.
● description - описание доступа.
● restrict access - если true, добавляет дополнительную надпись к праву
доступа в интерфейсе, о том, что права данного типа нужно давать только
доверенным лицам.
Далее, данные права доступа выбираются в интерфейсе и распределяются
по ролям.
34
Обратный вызов.
85
Рис. №25 Управление распределением прав доступов по ролям,
объявленных модулем details_company.
Данные права можно использовать в любом месте программно, для
разграничения прав доступа. Для сущности типа details_company объявлен
специальный файл с описанием условий на CRUD
35
операции с сущностью.
Файл описывающий различные права доступа для сущности должен
наследоваться от EntityAccessControlHandler. В приложении №13 приведен
пример для сущности details_company, в описываются два метода:
● checkAcсess() - в него передают экземпляр материала, для которого
необходимо проверить права доступа, операцию, для которой проверяются права
доступа: view (просмотр), update (обновление, редактирование), delete (удаление).
Третьим аргументом туда передается экземпляр объекта текущего пользователя,
который пытается произвести какую-либо операцию. При помощи объекта
AccessResult производятся сверка на ранее объявленных прав доступа и
текущего пользователя.
● checkCreateAccess() - аналогичный метод checkAccess(), где
проверка производится на возможность текущего пользователя создавать новые
сущности данного типа. В него передается аккаунт текущего пользователя,
контекст, в котором могут быть переданы дополнительные данные другими
модулями, а также подтип сущности.
35
Create, Read, Update, Delete - Создание, Чтение, Обновление, Удаление.
86
На основе данного файла и прав доступа, собранных из всех ролей
пользователя, ограничивается доступ к тем или иным возможностям и частям
сайта.
В файлах {MODULENAME}.module каждого файла описаны
дополнительные функции - хуки
36
.
Таблица №19 Список хуков используемых в модулях.
Хуки
Используется в модулях
Описание
hook_theme()
(41)
details_company,
details_contact,
details_project
Используется для описания
темплейтов сущностей.
hook_preprocess
_HOOK()
details_company,
details_contact,
details_project
Используется для
препроцессинга темплетйов
объявленных в hook_theme().
hook_entity_base
_field_info() (42)
details_company,
details_contact
Позволяет добавлять новые
базовые поля к сущностям.
2.4. Контрольный пример реализации проекта и его описание
Для того чтобы работать с системой, первым делом необходимо
авторизоваться в системе под пользователям, у которого есть необходимые
права доступа.
Рис. №26 Страница авторизации.
36
Функции, вызываемые динамически сторонними модулями или ядром с заранее известным
именованием и аргументами.
87
После авторизации под администратором будет доступ к
административному тулбару, и всему ранее добавленному содержимому, а также
всем возможностям, добавленными модулями.
Проверка и демонстрация будет производится для каждой сущности,
каждого конкретного модуля.
Первым делом мы проверим сущность “Компания”:
1. Заходим в “Content” (Содержимое) > “Company” (Компания).
Рис. №27 Страница со списком добавленных компаний.
2. Для добавления новой компании жмем “Add company” (Добавить
компанию)
3. Заполняем форму проверочными данными.
Таблица №20
Проверочные данные для создания новой сущности “Компания”.
Поле
Значение
Title (Заголовок)
ИП Малышев Никита Александрович
Banking details (Банковские
реквизиты)
Филиал Точка Публичного
акционерного общества Банка
«Финансовая Корпорация Открытие»
Расчетный счет:
40802810414500005142
Корреспондентский счёт:
30101810845250000999 в ГУ банка
России по ЦФО
БИК: 044525999
ИНН банка: 7706092528
КПП: 770543002
ОКПО: 04503985
88
ОГРН: 1027739019208
Comments (Комментарии)
Наша компания.
Address (Адрес)
Страна: Россия
Улица: Борчанинова 12
Город: Пермь
Область: Пермский край
Почтовый индекс: 614068
Internet Messaging (Мессенджеры)
@Niklan - Telegram,
niklanrus - Skype
Phones (Телефоны)
+7 919 449-55-60 - Руководитель
Emails
hello@niklan.net - Основная почта
Webs
https://niklan.net - Персональный сайт
Рис. №28 Форма заполненная тестовыми данными.