Download the PHP package beta/bx.model without Composer

Bitrix модели

• Установка
• Модели
  • Пример описания модели
  • Пример работы с моделью
  • Агрегационная модель
    • Пример описания агрегационной модели
    • Пример работы с агрегационной моделью
• Коллекции
  • Пример работы с коллекцией
  • Коллекция моделей
    • Пример использования
  • MappedCollection & MappedCollectionCallback
    • Пример использования
• Сервисы
  • Пример описания сервиса
  • Пример использования сервиса
  • Query
    • Пример использования
  • Pagination
    • Пример использования
  • Fetcher
  • Пример описания сервиса
    • Пример использования
  • Админ. интерфейсы
    • Пример использования
• Базовые сервисы
  • Сервис для работы с пользователями
    • Пример использования
  • Сервис для работы с файлами
    • Пример использования

Установка

Модели

Модели отражают сущности используемые в проекте: элементы инфоблоков, элементы hl блоков или записи в произвольной таблице. Представляют собой формализованные данные и предоставляют интерфейс для более удобного оперирования данными.

Каждая модель должна имплементировать интерфейс ModelInterface, в свою очередь данный интерфейс наследует интерфейсы ArrayAccess и IteratorAggregate, то есть с моделью можно работать как с ассоциативным массивом. Так же наследуется интерфейс CollectionItemInterface требующий реализации методов:

• assertValueByKey(string $key, $value): bool - проверяет соответствие значения по ключу переданному значению
• hasValueKey(string $key): bool - проверяет наличие значений по ключу
• getValueByKey(string $key) - возвращает значение по ключу

В данном модуле присутствует не полная реализация интерфейса модели - AbsOptimizedModel, предполагается использовать как основу для создания моделей.

Пример описания модели

Пример работы с моделью

Агрегационная модель

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

Пример описания агрегационной модели

Пример работы с агрегационной моделью

Коллекции

Для работы с совокупностью однотипных данных создана еще одна сущность - коллекция. Коллекции предоставляют удобный интерфейс для работы с подобными наборами данных, который в себя включает: фильтрацию, поиск, добавление/удаление элементов из коллекции, выборка значений по ключу...

Для реализации коллекции необходимо имплементировать интерфейс CollectionInterface или ReadableCollectionInterface если предполагается что набор элементов не изменяется. Коллекции в свою очередь могут включать в себя любые объекты имплементирующие интерфейс CollectionItemInterface. В данном модуле уже есть полноценная реализация коллекции - Collection.

Пример работы с коллекцией

Коллекция моделей

В модуле есть отдельная реализация коллекции для моделей ModelCollection, данные коллекции могут содержать любые объекты имплементирующие интерфейс ModelInterface.

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

MappedCollection & MappedCollectionCallback

Для удобства созданы производные коллекции в которых можно указывать произвольный ключ доступа к элементам коллекции:

• MappedCollection - принимает в конструкторе произвольную коллекцию и создает карту доступа по указанному ключу.
• MappedCollectionCallback - принимает в конструкторе произвольную коллекцию и создает карту доступа по вычисляемому ключу.

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

Сервисы

Для интеграции с СУБД используются сервисы - ModelServiceInterface, данные сервисы имплементируют базовые операции:

• Запрос списка элементов сущностей (по определенным критериям) - список моделей или коллекция
• Запрос конкретного элемента сущности - модель
• Добавление/обновление элемента сущности - модели
• Удаление элемента сущности - модели

Для реализации сервиса моделей необходимо имплементировать интерфейс ModelServiceInterface, данный интерфейс объединяет следующие:

• QueryableModelServiceInterface
  • ReadableModelServiceInterface - операции: getList, getCount и getById
  • FilterableInterface - необходим для указания правил фильтрации
  • SortableInterface - необходим для указания правил сортировки
  • LimiterInterface - необходим для указания правила ограничения выборки
• SaveableModelServiceInterface - метод сохранения/обновления
• RemoveableModelServiceInterface - метод удаления

В модуле есть не полная реализации сервиса на основе которой можно создать свой сервис - BaseModelService.

Пример описания сервиса

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

Query

В модуле представлена объектная модель параметров запроса из базы, описана в интерфейсе QueryInterface, так же есть полная реализация данного интерфейса - Query. Объекты данного класса могут содержать параметры: select, filter, order, group, limit,offset. Есть производный интерфейс ModelQueryInterface, в модуле есть полная реализация данного интерфейса QueryModel, работает непосредственно с сервисом моделей, сервис передается в конструктор и посредством двойной диспетчеризации обеспечивается выборка данных, предоставляет дополнительные методы для выборки моделей:

• loadFiler - формирует фильтр на основе переданного ассоциативного массива в соответствии с правилами фильтрации сервиса, описанными в методе ModelServiceInterface->getFilterFields()
• loadSort - формирует параметры сортировки данных на основе переданного ассоциативного массива в соответствии с правилами сортировки сервиса, описанными в методе ModelServiceInterface->getSortFields()
• loadPagination - формирует параметры пагинации на основе переданного массива, используются ключи: limit и page
• getPagination - возвращает объект пагинации PaginationInterface
• getList - возвращает коллекцию моделей на основе сформированных параметров выборки

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

Pagination

Для более удобной работы с пагинацией описан интерфейс PaginationInterface, в модуле имеется полная реализация данного интерфейса - Pagination. Данный класс работает совместно с интерфейсом QueryInterface.

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

Fetcher

Довольно часто требуется получить модель данных со связанными моделями (по внешним ключам БД или другим критериям), для упрощения этой задачи был описан интерфейс FetcherModelInterface, данный интерфейс имеет полную реализацию - FetcherModel. Данный класс работает с сервисами моделей, для более простой реализации описан абстрактный класс сервиса моделей BaseLinkedModelService на основе этого класса можно описать совой сервис для выборки моделей со связанными моделями.

Пример описания сервиса

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

Админ. интерфейсы

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

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

Базовые сервисы

В модуле есть несколько реализованных сервисов:

• FileService - позволяет работать с файлами из таблицы b_file
• UserService - позволяет работать с пользователями из таблицы b_user

  Сервис для работы с пользователями

Помимо стандартных методов сервиса моделей, предоставляет след. методы:

• login(string $login, string $password): ?UserContextInterface - авторизация по логину и паролю
• isAuthorized(): bool - проверка авторизации
• saveExtendedData(User $user, string ...$keyListForSave): Result - сохранение пользователя с произвольным набором данных
• updatePassword(User $user, string $password): Result - обновление пароля пользователя
• getCurrentUser(): ?UserContextInterface - запрос текущего пользователя, по факту возвращает объект контекста из которого уже можно получить модель пользователя

Как видно из описания методов, в ряде случаев сервис возвращает не саму модель, а контекст модели - UserContextInterface, а уже из контекста можно запросить либо идентификатор пользователя getUserId или саму модель пользователя getUser. В данном интерфейсе есть 2 интересных метода:

• setAccessStrategy(AccessStrategyInterface $accessStrategy) - позволяет указать произвольную стратегию по разграничению доступа
• hasAccessOperation(int $operationId): bool - проверяет возможность выполнения пользователем произвольной операции в соответствии с указанной стратегией

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

Сервис для работы с файлами

Помимо стандартных методов сервиса моделей, предоставляет след. методы:

• saveFiles(string $baseDir, string ...$filePaths): ModelCollection - сохраняет файлы из перечисленных url/абсолютных путей и возвращает коллекцию
• function saveUploadFiles(string $baseDir, UploadedFileInterface ...$files): ModelCollection - сохраняет файлы из перечисленных объектов интерфейса UploadedFileInterface - PSR-7
• saveFile(string $baseDir, string $filePath, ?string $name = null, ?string $description = null): ?File - сохраняет файл с возможностью задания альтернативного имени и описания
• replaceFile(int $fileId, string $baseDir, string $filePath, ?string $name = null, ?string $description = null): ?File - удаляет файл с указанным идентификатором и сохраняет новый

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