Сущности и маппинг

Сущность — это типизированный объект строки таблицы. Колонки описываются атрибутами на свойствах: тип, ключ, индекс, внешний ключ, ограничение. Из этих же атрибутов PPA строит SELECT и — при миграции — DDL таблицы.

Что такое сущность и зачем

Сущность (entity) — PHP-класс, одно свойство которого соответствует одной колонке таблицы.

Проблема. Если результат запроса — безликий массив ($row['created_at']), нет ни типов, ни автодополнения, ни единого места, где видно устройство таблицы. Колонки, их типы и связи размазаны по SQL-строкам.

Решение. Опишите строку типизированным классом, а колонки — атрибутами. PPA гидрирует результат в такой объект (типы, автодополнение), а из атрибутов умеет сгенерировать схему таблицы. Один класс — источник правды о структуре. Об этом и раздел.

Базовый вид

Сгенерируйте сущность командой make (флаг -e):

php call make -e .User   # → main/User.php

Класс помечается #[Table], свойства — атрибутами колонок:

<?php

namespace Main;

use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Entity\Table;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Hybrid\Id;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Primal\Varchar;

#[Table]
class User
{
  #[Id]
  public ?int $id = null;

  #[Varchar(200)]
  public string $username;
}

Первичные ключи

Атрибуты-«гибриды» разворачиваются в набор других — это готовые шаблоны для первичных ключей:

#[Id]      public ?int $id = null;        // авто-инкремент int PK
#[UuidPk]  public ?string $id = null;     // UUID PK со значением по умолчанию

Типы колонок

Ровно один тип на свойство (Ppa\Mapping\Attributes\Primal). Тип свойства PHP проверяется на совместимость на этапе скана:

Null и значения по умолчанию

Без #[DefaultVal] дефолт выводится из значения свойства PHP: null → DEFAULT NULL, false → DEFAULT FALSE, 'pending' → DEFAULT 'pending', число → как есть.

#[Boolean]
public bool $is_deleted = false;       // → DEFAULT FALSE

#[Timestamp]
#[DefaultVal('NOW()')]
public string $created_at;

Индексы

Атрибуты Ppa\Mapping\Attributes\Idx. Повторяемы — можно навесить несколько на одно свойство:

columns: ['other'] добавляет в индекс дополнительные колонки (свойство-носитель подставляется первым). Опции where (частичный индекс) и opClass — только PostgreSQL.

#[Varchar(200)]
#[NullableIs(false)]
#[Unique]                              // UNIQUE INDEX по username
public string $username;

Внешние ключи и ограничения

Атрибуты Ppa\Mapping\Attributes\Constraint:

Действия FK — enum FKAction (Mapping\Constants\FKAction): RESTRICT, NO_ACTION, SET_DEFAULT, SET_NULL, CASCADE.

use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Constraint\ForeignRepo;
use Flytachi\Winter\K2\Ppa\Mapping\Constants\FKAction;

#[Uuid]
#[ForeignRepo(InstanceRepository::class, FKAction::CASCADE, FKAction::CASCADE)]
public string $instance_id;

#[SmallInteger]
#[CheckEnum(InstanceStatus::class)]        // col IN (0, 1, 2)
public int $status;

Полный пример

<?php

namespace Main\Entities;

use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Entity\Table;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Hybrid\UuidPk;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Primal\{Uuid, Varchar, BigInteger, Boolean, Timestamp};
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Idx\Unique;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Constraint\ForeignRepo;
use Flytachi\Winter\K2\Ppa\Mapping\Attributes\Additive\DefaultVal;
use Flytachi\Winter\K2\Ppa\Mapping\Constants\FKAction;

#[Table]
class FileRecord
{
  #[UuidPk]
  public ?string $id = null;

  #[Uuid]
  #[ForeignRepo(InstanceRepository::class, FKAction::CASCADE, FKAction::CASCADE)]
  #[Unique(['name'])]
  public string $instance_id;

  #[Varchar(255)]
  public string $name;

  #[BigInteger]
  public int $size;

  #[Boolean]
  public bool $is_public = false;

  #[Timestamp]
  #[DefaultVal('NOW()')]
  public string $created_at;
}

Как сущность влияет на SELECT

Свойство $entityClassName репозитория задаёт, во что гидрируются строки, и как строится список колонок:

• Обычный класс (не наследует stdClass) → PPA читает публичные свойства и строит явный SELECT id, name, email FROM ....
• Класс, наследующий \stdClass (или дефолт \stdClass) → выборка через *.

Своя формула колонки — EntityInterface

Чтобы задать SQL-выражение для свойства, реализуйте EntityInterface::selection() — карта [свойство => 'SQL AS свойство']. Отсутствующие в карте свойства выбираются по имени:

use Flytachi\Winter\K2\Ppa\Entity\EntityInterface;

class UserCard implements EntityInterface
{
  public int    $id;
  public string $fullName;

  public static function selection(): array
  {
      return [
          'fullName' => "CONCAT(u.first_name, ' ', u.last_name) AS fullName",
      ];
  }
}

Дальше

• Конструктор запросов — как выбирать эти сущности
• CRUD — вставка и обновление сущностей
• Миграции — генерация схемы из этих атрибутов