База данных

Сохраняйте пользовательский контент и настройки с помощью общего API хранения Elgg.

Содержание

Сущности
Пользовательская функциональность базы данных
Системный лог
- Хранение системного лога
- Создание собственного системного лога

Сущности 

Создание объекта 

Чтобы создать объект в вашем коде, вам нужно создать экземпляр ElggObject. Установка данных — это просто вопрос добавления переменных экземпляра или свойств. Встроенные свойства:

``guid`` GUID сущности; устанавливается автоматически
``owner_guid`` GUID пользователя-владельца
``subtype`` Произвольная строка из одного слова, определяющая, какой это объект, например blog
``access_id`` Целое число, представляющее уровень доступа к объекту
``title`` Заголовок объекта
``description`` Описание объекта

Подтип объекта — это специальное свойство. Это произвольная строка, описывающая, что представляет собой объект. Например, если вы пишете плагин блога, ваша строка подтипа может быть blog. Хорошая идея — сделать это уникальным, чтобы другие плагины случайно не попытались использовать тот же подтип. Для целей этого документа предположим, что мы строим простой форум. Следовательно, подтип будет forum:

Примечание

Рекомендуется зарегистрировать пользовательское расширение \ElggObject для вашего подтипа. Это упростит установку значений по умолчанию (таких как подтип), добавление пользовательских вспомогательных функций, регистрацию полей формы по умолчанию и т.д.

// register a custum class in your plugin Bootstrap
function init() {
    elgg_set_entity_class('object', 'forum', \MyForumObject::class);
}

// in your elgg-plugin.php entity definition
'entities' => [
    [
        'type' => 'object',
        'subtype' => 'forum',
        'class' => \MyForumObject::class,
    ],
],

// your custom class should be placed in /mod/<your_plugin>/classes
// in this example MyForumObject.php
class MyForumObject extends \ElggObject {

    /**
      * {@inheritdoc}
      */
    protected function initializeAttributes() {
        parent::initializeAttributes();

        $this->attributes['subtype'] = 'forum';
    }
}

$object = new \MyForumObject();
$object->access_id = 2;
$object->save();

access_id — это ещё одно важное свойство. Если вы не установите это, ваш объект будет приватным, и только пользователь-создатель сможет его видеть. Elgg определяет константы для специальных значений access_id:

ACCESS_PRIVATE Только владелец может видеть это
ACCESS_LOGGED_IN Любой авторизованный пользователь может видеть это
ACCESS_PUBLIC Даже посетители, не авторизованные, могут видеть это

Сохранение объекта автоматически заполнит свойство $object->guid, если оно успешно. Если вы измените какие-либо другие базовые свойства, вы можете снова вызвать $object->save(), и оно обновит базу данных для вас.

Вы можете установить метаданные на объекте так же, как стандартное свойство. Допустим, мы хотим установить SKU продукта:

$object->SKU = 62784;

Если вы назначите массив, все значения будут установлены для этих метаданных. Так, например, вы устанавливаете теги.

Метаданные не могут быть сохранены в базе данных, пока сущность не будет сохранена, но для удобства ElggEntity может кэшировать их внутри и сохранять при сохранении сущности.

Загрузка объекта 

По GUID

$entity = get_entity($guid);
if (!$entity) {
    // The entity does not exist or you're not allowed to access it.
}

Но что, если вы не знаете GUID? Есть несколько вариантов.

По пользователю, подтипу или сайту

Если вы знаете ID пользователя, для которого хотите получить объекты, или подтип, у вас есть несколько вариантов. Самый простой, вероятно, — вызвать процедурную функцию elgg_get_entities():

$entities = elgg_get_entities([
    'type' => $entity_type,
    'subtype' => $subtype,
    'owner_guid' => $owner_guid,
]);

Это вернёт массив объектов ElggEntity, по которым вы можете итерироваться. elgg_get_entities по умолчанию выполняет пагинацию с лимитом 10 и смещением 0.

Вы можете опустить owner_guid, чтобы получить все объекты, и опустить подтип или тип, чтобы получить объекты всех типов/подтипов.

Если у вас уже есть объект ElggUser — например, elgg_get_logged_in_user_entity(), который всегда содержит объект текущего пользователя, когда вы авторизованы, — вы можете просто использовать:

$objects = $user->getObjects($subtype, $limit, $offset)

Но как насчёт получения объектов с определённым фрагментом метаданных?

По свойствам

Вы можете получать сущности по их свойствам с помощью elgg_get_entities(). Используя конкретные параметры, переданные в массив $options, вы можете получать сущности по их атрибутам, метаданным, аннотациям и отношениям.

Отображение сущностей 

Чтобы сущности отображались в функциях списков, вам нужно предоставить представление для сущности в системе представлений.

Чтобы отобразить сущность, создайте представление EntityType/subtype, где EntityType — одно из следующих:

object: для сущностей, производных от ElggObject; user: для сущностей, производных от ElggUser; site: для сущностей, производных от ElggSite; group: для сущностей, производных от ElggGroup

Представление по умолчанию для всех сущностей уже создано, оно называется EntityType/default.

Иконки сущностей

Иконки сущностей могут быть сохранены из загруженных файлов, существующих локальных файлов или существующих объектов ElggFile. Эти методы сохраняют размер master иконки, определённый в системе. Другие определённые размеры будут сгенерированы по запросу.

$object = new \ElggBlog();
$object->title = 'Example entity';
$object->description = 'An example object with an icon.';

// from an uploaded file
$object->saveIconFromUploadedFile('file_upload_input');

// from a local file
$object->saveIconFromLocalFile('/var/data/generic_icon.png');

// from a saved ElggFile object
$file = get_entity(123);
if ($file instanceof ElggFile) {
        $object->saveIconFromElggFile($file);
}

$object->save();

Следующие размеры существуют по умолчанию:

master — 10240px по более длинной стороне (без масштабирования)
large — 200px по более длинной стороне (без масштабирования)
medium — квадрат 100px
small — квадрат 40px
tiny — квадрат 25px
topbar — квадрат 16px

Используйте elgg_get_icon_sizes(), чтобы получить все возможные размеры иконок для определённого типа и подтипа сущности. Функция запускает событие entity:icon:sizes event.

Чтобы проверить, установлена ли иконка, используйте $object->hasIcon($size).

Вы можете получить URL сгенерированной иконки с помощью метода ElggEntity::getIconURL($params). Этот метод принимает аргумент $params в виде массива, который указывает размер, тип и предоставляет дополнительный контекст для события для определения иконки для обслуживания. Метод запускает событие entity:icon:url event.

Используйте elgg_view_entity_icon($entity, $size, $vars), чтобы отобразить иконку. Это просканирует следующие места для представления и включит первое совпадение.

views/$viewtype/icon/$type/$subtype.php
views/$viewtype/icon/$type/default.php
views/$viewtype/icon/default.php

Где

$viewtype: Тип представления, например 'default' или 'json'.
$type: Тип сущности, например 'group' или 'user'.
$subtype: Подтип сущности, например 'blog' или 'page'.

Вам не нужно возвращать резервную иконку из обработчика события. Если загруженная иконка не найдена, система представлений просканирует представления (в этом конкретном порядке):

views/$viewtype/$icon_type/$entity_type/$entity_subtype.svg
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.gif
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.png
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.jpg

Где

$viewtype: Тип представления, например 'default' или 'json'.
$icon_type: Тип иконки, например 'icon' или 'cover_image'.
$entity_type: Тип сущности, например 'group' или 'user'.
$entity_subtype: Подтип сущности, например 'blog' или 'page' (или 'default', если сущность не имеет подтипа).
$size: Размер иконки (обратите внимание, что мы не используем размер с иконками svg)

Методы иконок поддерживают передачу типа иконки, если сущность имеет более одной иконки. Например, пользователь может иметь аватар и иконку обложки. Вы передадите 'cover_photo' в качестве типа иконки:

$object->saveIconFromUploadedFile('uploaded_photo', 'cover_photo');

$object->getIconUrl([
        'size' => 'medium',
        'type' => 'cover_photo'
]);

Примечание

Пользовательские типы иконок (например, обложки) имеют только предустановку для размера master, чтобы добавить пользовательские размеры, используйте событие entity:<icon_type>:url event для их настройки.

По умолчанию иконки будут храниться в /icons/<icon_type>/<size>.jpg относительно директории сущности в хранилище файлов. Чтобы предоставить альтернативное местоположение, используйте событие entity:<icon_type>:file event.

Добавление, чтение и удаление аннотаций 

Аннотации могут использоваться, например, для отслеживания рейтингов. Чтобы аннотировать сущность, вы можете использовать метод объекта annotate(). Например, чтобы дать записи блога рейтинг 5, вы можете использовать:

$blog_post->annotate('rating', 5);

Чтобы получить рейтинги записи блога, используйте $blogpost->getAnnotations('rating'), и если вы хотите удалить аннотацию, вы можете оперировать классом ElggAnnotation, например $annotation->delete().

Получение одной аннотации можно выполнить с помощью get_annotation(), если у вас есть ID аннотации. Если вы удалите ElggEntity любого вида, все её метаданные, аннотации и отношения также будут автоматически удалены.

Расширение ElggEntity 

Если вы наследуете от одного из классов ядра Elgg, вам нужно будет сообщить Elgg, как правильно создать экземпляр нового типа объекта, чтобы get_entity() и подобные возвращали соответствующий класс PHP. Например, если я кастомизирую ElggGroup в классе под названием «Committee», мне нужно сделать так, чтобы Elgg знал о новом сопоставлении. Ниже приведён пример расширения класса:

// Class source
class Committee extends ElggGroup {

    protected function initializeAttributes() {
        parent::initializeAttributes();
        $this->attributes['subtype'] = 'committee';
    }

    // more customizations here
}

В файле elgg-plugin.php вашего плагина добавьте секцию entities.

<?php // mod/example/elgg-plugin.php
return [
    // entities registration
    'entities' => [
                    [
                            'type' => 'group',
                            'subtype' => 'committee',
                            'class' => 'Committee',
                            'capabilities' => [
                                    'searchable' => true,
                            ],
                    ],
            ],
];

Сущности будут зарегистрированы при активации плагина.

Теперь, если вы вызовете get_entity() с GUID объекта комитета, вы получите объект типа Committee.

Расширенные функции 

URL сущностей

URL сущностей предоставляются интерфейсом getURL() и предоставляют фреймворку Elgg общий способ направления пользователей к соответствующему обработчику отображения для любого данного объекта.

Например, страница профиля в случае пользователей.

URL устанавливается с помощью функции elgg_register_entity_url_handler(). Функция, которую вы регистрируете, должна возвращать соответствующий URL для заданного типа — это само по себе может быть адресом, установленным обработчиком страницы.

Обработчик по умолчанию — использовать интерфейс экспорта по умолчанию.

Производительность загрузки сущностей

elgg_get_entities() имеет несколько опций, которые иногда могут быть полезны для улучшения производительности.

preload_owners: Если полученные сущности будут отображаться в списке с информацией о владельце, вы можете установить эту опцию в true для эффективной загрузки пользователей-владельцев полученных сущностей.
preload_containers: Если полученные сущности будут отображаться в списке с использованием информации из их контейнеров, вы можете установить эту опцию в true для их эффективной загрузки.
distinct: Когда Elgg получает сущности с помощью SQL-запроса, Elgg должен быть уверен, что каждая строка сущности появляется только один раз в результирующем наборе. По умолчанию он включает модификатор DISTINCT в столбце GUID для обеспечения этого, но некоторые запросы естественным образом возвращают уникальные сущности. Установка опции distinct в false удалит этот модификатор и положится на запрос для обеспечения собственной уникальности.

Внутреннее устройство запросов сущностей Elgg — это сложная тема, и рекомендуется обратиться за помощью на сайте сообщества Elgg перед использованием опции distinct.

Пользовательская функциональность базы данных 

Настоятельно рекомендуется использовать сущности везде, где это возможно. Однако Elgg поддерживает пользовательские SQL-запросы с использованием API базы данных.

Системный лог 

Примечание

Этот раздел нуждается во внимании и будет содержать устаревшую информацию

Системный лог Elgg по умолчанию — это простой способ записи того, что происходит в системе Elgg. Его можно просматривать и искать напрямую из панели администрирования.

Хранение системного лога 

Строка системного лога сохраняется всякий раз, когда запускается событие, касающееся объекта, класс которого реализует интерфейс Loggable. ElggEntity и ElggExtender реализуют Loggable, поэтому строка системного лога создаётся всякий раз, когда событие выполняется над всеми объектами, пользователями, группами, сайтами, метаданными и аннотациями.

Общие события включают:

создание
обновление
удаление
вход

Создание собственного системного лога 

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

Для этого вы можете создать функцию, которая слушает все события для всех типов объектов:

register_elgg_event_handler('all','all','your_function_name');

Затем вашу функцию можно определить как:

function your_function_name($object, $event) {
   if ($object instanceof Loggable) {
      ...
   }
}

Затем вы можете использовать дополнительные методы, определённые в Loggable, для извлечения необходимой вам информации.