Download the PHP package djinorm/djin without Composer

DjinORM

Легковесная ORM, нацеленная на работу с любым типом баз данных, будь то реляционные, документ-ориентированные, колоночные или key-value хранилища. Вы полностью управляете тем, как что и куда вы хотите сохранять и извлекать. Все что для этого нужно - создать репозитории для моделей

Установка:

Преамбула

DjinORM состоит из набора компонентов и интерфейсов, взаимодейтвие которых позволяет инкапсулировать логику ее работы

Модель

Модель - это объект, который мы хотим сохранять в БД, отдельная, полноценная сущность, которая может иметь в себе любые вложенные объекты и массивы. Моделью может быть абсолютно любой класс, который реализует интерфейс \DjinORM\Djin\Model\ModelInterface. Каждая модель должна иметь свой уникальный Id, благодаря которому осуществляется связывание моделей друг с другом.

Id

Id - объект, который содержит в себе уникальный идентификатор модели. Именно объект \DjinORM\Djin\Id\Id должна возвращать каждая модель, и именно благодаря нему осуществляется связывание моделей друг с другом. В PHP все объекты передаются по ссылке благодаря чему мы можем присвоить Id какой-либо модели и он автоматически попадет во все ее реляции. Пример:

Представьте, что у нас есть 2 простых модели: User и Comment. Пользователь может писать комментарии, где каждый комментарий должен быть закреплен за пользователем.

Модель пользователя

Модель комментария

Теперь давайте посмотрим как будет работать связывание пользователя и комментария:

За счет того, что объекты в php передаются по ссылке, мы можем проставить для нашего пользователя какой-то постоянный Id, который сразу попадет и в комментарий

Осталось только решить вопрос с тем, кто и как занимается простановкой Id. Об этом далее.

IdGenerator

В DjinORM простановка перманентных Id осуществляется отдельным компонентом, который должен реализовывать интерфейс \DjinORM\Djin\Id\IdGeneratorInterface, который в свою очередь проставляет Id непосредственно перед записью модели в БД.

Здесь стоит сделать отступление для тех, кто работал только с MySQL и привык к тому, что база сама проставляет Id. В случае с DjinORM такой подход невозможен, но это ничуть не плохо. Вместо этого вы можете использовать абсолютно любой счетчик, например Redis, sequences в PostgreSQL, строку UUID или даже использовать что-то вроде SELECT MAX(id) FROM table для каждой генерации (хотя так делать не надо, потому что это приведет к блокировкам)

В комплекте с ORM сразу идет 3 готовых Id-генератора (но вам ничего не мешает сделать свой)

• \DjinORM\Djin\Id\UuidGenerator - не требует сторонних решений для генерации Id, возвращает случайную 128-битную строку вида 550e8400-e29b-41d4-a716-446655440000. Используйте с осторожностью, т.к. использование строки в качестве Id сильно раздувает размер БД
• \DjinORM\Djin\Id\RedisIdGenerator - мы используем именно его. Он требует наличия ext-redis, а также механизма, который в случае утраты данных в redis восстановит актуальное состояние счетчика используя что-то вроде SELECT MAX(id) FROM table
• \DjinORM\Djin\Id\MemoryIdGenerator - удобен для тестов. Последовательно генерирует числа начиная с заданного, хранит состояние в памяти, в переменной
• \DjinORM\Djin\Id\IdGeneratorInterface - сам интерфейс генератора. Имеет лишь один метод IdGeneratorInterface::getNextId(ModelInterface $model) который на вход молучает модель, а на выходе отдает скальрное представление Id не проставляя при этом Id для самой модели. Благодаря таком подходу вы можете генерировать Id в зависимости от класса и состояния модели

Репозитории

В репозиториях лежит вся "грязь", ответственная за то, как находить, извлекать и сохранять модели из БД. Каждый репозиторий должен реализовывать интерфейс \DjinORM\Djin\Repository\RepositoryInterface. Именно репозиторий имеет методы поиска, сохранения и удаления моделей. Именно он знает с какой именно БД вы работаете, и именно он знает как преобразовать вашу модель в массив данных для сохранения в БД и как обратно превратить этот массив в вашу модель. Именно репозиторий отвечает за простановку перманентного Id, поэтому IdGenerator должен передаваться ему через конструктор в качестве зависимости.

Подразумевается, что для этих целей используется рефлексия, при помощи которой вы можете обращаться к приватным свойствам класса, получать и изменять их значения, создавать объекты без вызова их конструктора и т.д. Чтобы упростить работу с моделями через рефлексию в DjinORM существует специальный хелпер \DjinORM\Djin\Helpers\RepoHelper.

С его помощью мы легко можем превратить нашу модель Comment в обычный массив

И обратно превратить массив, извлеченный из базы в модель

Подобный подход дает полный контроль над хранением данных: вы можете извлекать объекты любого уровня вложенности, как угодно трансформировать данные для записи в БД и делать с ними что угодно. В ряде случаев такой подход вполне оправдан, однако он требует большого количества кода, особенно когда вам надо трансформировать сложные объекты и проверять существование каких-либо значений. Кроме того, часто бывает так, что ряд сложных объектов встречается как вложенный в разных моделях.

О том, как решается данная проблема можно ознакомиться в следующем разделе.

Hydrator & Mapper

Первым делом стоит рассмотреть мапперы. Представьте, что мы решили сделать возможность создавать комментарии из примера выше анонимным пользователям. Т.е. у комментария нет автора. В таком случае его поле userId может быть Id, а может null. При таком подходе нам придется каждый раз проверять userId на null и в зависимости от этого создавать/извлекать значение Id или так и оставлять null. А теперь представьте, что помимо комментария у нас появятся такие модели как Post, Role и куча любых других, которые тоже работают с Id. Поэтому логично вынести куда-то логику преобразования Id туда-сюда. Именно по этой причине и появились мапперы.

Мапперы

Маппер умеет превращать данные определенного типа в скалярное представление или массив, а также, обратно превращать скалярные данные в нужный нам тип, осуществляя внутри себя все преобразорвания и проверки на null. Каждый маппер должен реализовывать интерфейс \DjinORM\Djin\Hydrator\Mappers\MapperInterface - посмотрите код этого интерфейса, и вам многое станет понятно

В Djin поставляется набор типовых мапперов, которые могут конвертировать большинство распространенных типов данных:

• \DjinORM\Djin\Hydrator\Mappers\IdMapper - преобразует скалярное представление Id в объект Id и обратно
• \DjinORM\Djin\Hydrator\Mappers\ArrayMapper - маппер массивов
• \DjinORM\Djin\Hydrator\Mappers\BoolMapper - маппер булевых значений
• \DjinORM\Djin\Hydrator\Mappers\DatetimeMapper - маппер значений DateTime и DateTimeImmutable
• \DjinORM\Djin\Hydrator\Mappers\DeepIdentityMapper - маппер сложных составных конструкций, который позволяет сохранять и извлекать из БД любые наборы значений. Фактически, это аналог serialize() за тем лишь исключением, что вместо сохранения имени класса при настройке маппера вы задаете алиасы имен классов. Такой подход позволяет вам безболезненно переименовывать классы и менять их пространства имен не боясь за то, что ранее репозиторий не сможет воссоздать модель или объект нужного класса потому, что имя класса изменилось
• \DjinORM\Djin\Hydrator\Mappers\FloatMapper - маппер вещественных чисел
• \DjinORM\Djin\Hydrator\Mappers\IntMapper - маппер целых чисел
• \DjinORM\Djin\Hydrator\Mappers\NestedMapper - составной маппер, в который можено передать набор любых других мапперов с целью конвертирования сложных составных объектов
• \DjinORM\Djin\Hydrator\Mappers\NestedArrayMapper - составной маппер, в который можено передать набор любых других мапперов с целью конвертирования сложных массивов составных объектов
• \DjinORM\Djin\Hydrator\Mappers\RelationMapper - маппер для реляций (о них читайте ниже)
• \DjinORM\Djin\Hydrator\Mappers\StringMapper - маппер строковых значений
• \DjinORM\Djin\Hydrator\Mappers\ValueObjectMapper - маппер объектов-значений, используется в тех случаях, когда какой-либо объект содержит в себе лишь одно значение, и используется просто в качестве удобной ООП-обертки

Гидратор

Итак, у нас есть мапперы, которые могут преобразовывать определенные типы данных, но сами по себе они бесполезны. Им нужен компонент, который будет ими управлять. Для этого есть \DjinORM\Djin\Hydrator\Hydrator который как раз и отвечает за комплексную трансформацию сложных объектов в простые массивы и обратно. Также, гидратор содержит в себе схему мапперов в точечной нотации и может вернуть вам экземпляр маппера по его нотации. Это полезно при дополнительной обработке данных в репозитории (если такая требуется).

Например, вот так будет выглядеть гидратор для моделей User и Comment

Поэтому наши репозитории теперь могут выглядеть примерно следующим образом

Разумеется, в реальном проекте вы можете использовать не только SQL базы, но и любые другие. Вы можете вынести общую логику в абстрактный репозиторий и всячески оптимизировать код. В качестве примера можете посмотреть на SQL репозиторий djin-repo-sql

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

ModelManager

Задача компонента \DjinORM\Djin\Manager\ModelManager - собрать все вместе. Именно он максимально упрощает реальную работу с моделями, связывая модели, репозитории, согласованное сохранение данных и т.д.

В конструктор ModelManager можно передать 4 параметра:

• PSR-совместимый контейнер (обязательно), который может возвращать объекты репозиториев по имени класса репозитория. Например, PHP-DI
• callable onBeforeCommit(ModelManager $manager, array $modelsToSave, array $modelsToDelete) в которой можно осуществлять начало транзакции вашей СУБД
• callable onAfterCommit(ModelManager $manager, array $modelsToSave, array $modelsToDelete) в которой можно осуществлять commit транзакции вашей СУБД
• callable onCommitException(ModelManager $manager, array $modelsToSave, array $modelsToDelete) в которой можно осуществлять откат транзакции вашей СУБД

Также, нам нужно настроить ModelManager так, чтобы он знал с какими репозиториями и моделями ему предстоит работать. Для этого мы передаем ему репозиторий и модель или массив моделей, с которыми репозиторий может работать. Это бывает полезно когда один репозиторий может сохранять несколько разных моделей, наследников какой-то общей модели

Либо указание классов моделей можно опустить, если наш репозиторий сохраняет только одну модель. Модель будет определена согласно интерфейсу \DjinORM\Djin\Repository\RepositoryInterface::getModelClass

Теперь мы можем работать с моделями примерно следующим образом

Реляции

Связь с использованием объекта Id работает быстро и хорошо. Но объект Id передается по ссылке только в момент создания записей. Если в момент создания User::$id и Comment::$userId ссылаются на один и тот же объект Id, то в последующих сессиях при извлечении их из БД они будут ссылаться на разные объекты Id с одним и тем же перманентным значением. Обычно, это не создает проблем, т.к. значение самого Id изменить нельзя. Но Id сам по себе никак не связан с моделью. Например, в ситуации, когда автором комментария может быть не только User, но и Bot, то как нам определить кто именно является автором комментария?

Именно для решения подобных задач существует \DjinORM\Djin\Model\Relation. Давайте перепишем наш Comment так, чтобы он в качестве автора мог принимать кого угодно

Реляции хранят в себе значение Id модели ModelInterface::getId() и ее имени из ModelInterface::getModelName(). Для реляций также есть специальный маппер.

Теперь благодаря реляциям мы можем легко находить автора комментария, кто бы им ни был (любая модель)