falseclock / dbd-php-entity
DTO like library to fetch any data in an Object-Oriented manner (ORM)
Installs: 5 346
Dependents: 1
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 3
Open Issues: 1
Requires
- php: ^8.2
- ext-json: *
- myclabs/php-enum: ^1.8.4
Requires (Dev)
- php-coveralls/php-coveralls: ^v2.7.0
- phpunit/phpunit: ^11.2.8
README
NOTICE: readme находится в процессе написания.
Данная библиотека позволяет легко преобразовывать ассоциативные массивы в объекты по заранее предопределенным структурам (мапингу), иными словами реализует DTO. Изначально проект реализовывался как ORM библиотека, но не ограничивается этим. С помощью библиотеки можно описывать любые структурированные данные, а не только таблицы и их поля.
Принцип действия на пальцах
Представим, у вас есть таблица, с несколькими полями:
test=# select currency_id, currency_name, currency_short_name, currency_symbol,currency_code FROM currencies;
currency_id | currency_name | currency_short_name | currency_symbol | currency_code
-------------+---------------------+---------------------+-----------------+---------------
505 | Доллар США | Доллар | $ | USD
36 | Казахстанский Тенге | Тенге | ₸ | KZT
506 | Российский Рубль | Рубль | ₽ | RUB
548 | Евро | Евро | € | EUR
(4 строки)
Данные из этой таблицы извлекаются через некий PDO и у вас есть именованный массив.
Чтобы обращаться к элементам, вам явно нужно оказывать наименование поля:
$item['currency_name']; $item['currency_symbol'];
Если заранее создать маппинг, то мы можем получит объект вместо именованного массива:
$objects = []; foreach ($array as $item) { $objects[] = new Currency($item); } // обращаться к значениям теперь можно так: $objects[0]->name; $objects[0]->symbol;
Это дает нам возможность не привязываться к наименованиям полей. Только ли для табличных данных подходит данная библиотека? Нет. Можно описывать любые структуры, например YAML файла или просто какие-то JSON данные. Нужны вложенные структуры? Нужны геттеры и сэттеры? Нужна предварительная конвертация данных? Это все есть, и даже больше. Можно контролировать целостность данных, вложенность структур, скрывать поля, если вы хотите отдавать их во внешную среду и много много чего другого. Поможет в вашем проекте? Тогда вперед с установки.
Установка
composer require falseclock/dbd-php-entity
Оглавление
Основные классы
Описание полей
Вспомогательные классы
Вспомогательные классы
- FullEntity
- FullMapper
- OnlyDeclaredPropertiesEntity
- StrictlyFilledEntity
- SyntheticEntity
- MapperVariables
Mapper
Любое описание модели начинается с наследования этого абстрактного класса. Дочерний класс должен отвечать нескольким простым правилам:
- Все переменные с типом
Column
объявляются какpublic
. - Любые другие переменные кроме
Column
, объявляются какprotected
. - Класс не должен содержать
private
переменных. - Класс не должен иметь методы.
- Константа
ANNOTATION
должна быть переопределена. - Название класса должно иметь тоже самое название что и основной класс
Entity
с постфиксомMap
. - Оба класс
Entity
иMapper
должны быть в одномnamespace
.
Пример
class City extends Entity { } class CityMap extends Mapper { const ANNOTATION = "Data description"; }
Постфикс Map
, при желании, можно переопределить через константу Maper::POSTFIX
Все потомки Mapper
класса является синглтонами и вызываются через статичный метод me
.
Публичные методы
- __get
- findColumnByOriginName
- getAllVariables
- getAnnotation
- getColumns
- getComplex
- getConstraints
- getEmbedded
- getEntityClass
- getOriginFieldNames
- getPrimaryKey
- getTable
- getVarNameByColumn
- me
- meWithoutEnforcer
- name
__get
__get — магический метод для доступа к protected
переменным класса.
Описание
public __get(string $property): mixed
В некоторых случаях, при необходимости обращения к непубличным переменным в IDE, можно через phpdoc в заголовке класса
прописать переменную через @property
, которая доступна через магический метод. Если обратиться к несуществующей
переменной, будет выброшено исключение.
Пример
/** * Class MapperGet * @property Embedded $Regions * @property Complex $Address */ class MapperGet extends Mapper { const ANNOTATION = "Data description"; /** @var Embedded */ protected $Regions = [ Embedded::NAME => "country_regions", Embedded::ENTITY_CLASS => Region::class, ]; /** @var Complex */ protected $Address = [ Complex::TYPE => Address::class, ]; }
findColumnByOriginName
findColumnByOriginName — получение экземпляра класса Column через ключ ассоциативного массива.
Описание
public findColumnByOriginName(string $originName): Column
Может быть использован, если необходимо получить информацию о том как описывается то или иное public
поле в Mapper
классе.
getAllVariables
getAllVariables — получение всех определенных переменных класса
Описание
public getAllVariables(): MapperVariables
Полезная функция, если имеется необходимость на основании описания полей сформировать скрипт создания таблицы в реляционной базе.
getAnnotation
getAnnotation — получение константы ANNOTATION
Описание
public getAnnotation(): string
getColumns
getColumns — получение массива стандартных полей
Описание
public getColumns(): array
Данная функция возвращает массив Columns
, которые определены в Mapper классе. Следует помнить, что комплексные поля
объявляются как public
.
getComplex
getComplex — получение массива комплексных полей
Описание
public getComplex(): array
Данная функция возвращает массив Complex
, которые определены в Mapper классе. Следует помнить, что комплексные поля
объявляются как protected
.
getConstraints
getConstraints — получение массива ограничений
Описание
public getConstraints(): array
Данная функция возвращает массив Constraint
, которые определены в Mapper классе. Следует помнить, что ограничения
объявляются как protected
.
getEmbedded
getEmbedded — получение массива встроенных полей
Описание
public getEmbedded(): array
Данная функция возвращает массив Embedded
, которые определены в Mapper классе. Следует помнить, что встроенные поля
объявляются как protected
.
getEntityClass
getEntityClass — получение класса, который использует данный маппинг
Описание
public getEntityClass(): string
Следует осторожно использовать данную функцию, если вы не объявили Entity
и Mapper
в одном namespace
getOriginFieldNames
getOriginFieldNames — получение массива объявленных public
полей
Описание
public getOriginFieldNames(): array
Данная функция возвращает ассоциативный массив, где ключ — наименование переменной класса Mapper
, а значение —
наименование поля.