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

Оглавление

Основные классы

• Mapper
• Entity
• View

Описание полей

• Column
• Complex
• Constraint
• Embedded

Вспомогательные классы

• Primitive
• Type

Вспомогательные классы

• FullEntity
• FullMapper
• OnlyDeclaredPropertiesEntity
• StrictlyFilledEntity
• SyntheticEntity
• MapperVariables

Mapper

Любое описание модели начинается с наследования этого абстрактного класса. Дочерний класс должен отвечать нескольким простым правилам:

1. Все переменные с типом Column объявляются как public.
2. Любые другие переменные кроме Column, объявляются как protected.
3. Класс не должен содержать private переменных.
4. Класс не должен иметь методы.
5. Константа ANNOTATION должна быть переопределена.
6. Название класса должно иметь тоже самое название что и основной класс Entity с постфиксом Map.
7. Оба класс 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, а значение — наименование поля.