DataMapper

Основной класс для CRUD-операций — маппит DTO-объекты в строки базы данных и обратно.

Содержание

• Создание DataMapper
• insert
  • С Mapping (explicit-режим)
• update
  • Несколько WHERE-условий
• delete
• findAll
• findOne
• iterateAll
• Auto-режим и Explicit-режим
  • Auto-режим
  • Explicit-режим
• Расширенные WHERE-условия
• Доступ к Connection

---

Создание DataMapper

use AsceticSoft\Rowcast\Connection;
use AsceticSoft\Rowcast\DataMapper;

$connection = Connection::create('mysql:host=localhost;dbname=app', 'root', 'secret');
$mapper = new DataMapper($connection);

Опционально можно передать пользовательский конвертер имён и/или конвертер типов:

use AsceticSoft\Rowcast\NameConverter\SnakeCaseToCamelCase;
use AsceticSoft\Rowcast\TypeConverter\TypeConverterRegistry;

$mapper = new DataMapper(
    $connection,
    nameConverter: new SnakeCaseToCamelCase(),
    typeConverter: TypeConverterRegistry::defaults(),
);

---

insert

Вставляет DTO в базу данных.

$user = new User();
$user->name = 'Alice';
$user->email = 'alice@example.com';

$mapper->insert('users', $user);

Неинициализированные свойства автоматически пропускаются. Это удобно для автоинкрементных первичных ключей — просто не устанавливайте $id, и он не будет включён в INSERT.

С Mapping (explicit-режим)

use AsceticSoft\Rowcast\Mapping;

$mapping = Mapping::explicit(User::class, 'custom_users')
    ->column('usr_nm', 'name')
    ->column('usr_email', 'email');

$mapper->insert($mapping, $user);

---

update

Обновляет строки, соответствующие WHERE-условиям. Возвращает количество затронутых строк.

$user->name = 'Alice Updated';

$affected = $mapper->update('users', $user, ['id' => 1]);
// $affected = 1

WHERE-условия обязательны для предотвращения случайного массового обновления.

Несколько WHERE-условий

$mapper->update('users', $user, [
    'id' => 1,
    'status' => 'active',
]);

---

delete

Удаляет строки, соответствующие WHERE-условиям. Возвращает количество затронутых строк.

$affected = $mapper->delete('users', ['id' => 1]);

WHERE-условия обязательны для предотвращения случайного массового удаления.

---

findAll

Находит все строки, соответствующие условиям, и гидратирует их в DTO-объекты.

// Все пользователи
$users = $mapper->findAll(User::class);

// С условиями
$users = $mapper->findAll(User::class, ['status' => 'active']);

// С сортировкой
$users = $mapper->findAll(User::class, orderBy: ['name' => 'ASC']);

// С пагинацией
$users = $mapper->findAll(User::class, limit: 10, offset: 20);

// Комбинированный запрос
$users = $mapper->findAll(
    User::class,
    where: ['status' => 'active'],
    orderBy: ['created_at' => 'DESC'],
    limit: 10,
    offset: 0,
);

---

findOne

Находит одну строку и гидратирует её в DTO-объект. Возвращает null, если строка не найдена.

$user = $mapper->findOne(User::class, ['id' => 1]);

if ($user === null) {
    // не найден
}

---

iterateAll

Аналогичен findAll, но возвращает iterable (генератор) для эффективной обработки больших наборов данных.

foreach ($mapper->iterateAll(User::class, ['status' => 'active']) as $user) {
    // Обрабатываем по одному пользователю — без полного массива в памяти
    processUser($user);
}

Поддерживает те же параметры, что и findAll:

$users = $mapper->iterateAll(
    User::class,
    where: ['status' => 'active'],
    orderBy: ['created_at' => 'DESC'],
    limit: 1000,
);

Используйте iterateAll() вместо findAll() при обработке тысяч строк для поддержания постоянного потребления памяти.

---

Auto-режим и Explicit-режим

Auto-режим

Передайте имя таблицы (для записи) или class-string (для чтения). Маппинг определяется автоматически:

Имя класса	Имя таблицы
User	users
UserProfile	user_profiles
SimpleUser	simple_users

Explicit-режим

Передайте Mapping для полного контроля:

$mapping = Mapping::explicit(User::class, 'custom_users')
    ->column('usr_nm', 'name')
    ->column('usr_email', 'email')
    ->column('id', 'id');

$users = $mapper->findAll($mapping, ['id' => 1]);
$mapper->insert($mapping, $user);
$mapper->update($mapping, $user, ['id' => 1]);
$mapper->delete($mapping, ['id' => 1]);

Подробнее см. Маппинг.

---

Расширенные WHERE-условия

DataMapper передаёт массив where в тот же движок условий QueryBuilder, поэтому доступны расширенные операторы:

$users = $mapper->findAll(User::class, where: [
    'deleted_at' => null,
    '$or' => [
        ['status' => ['active', 'pending']],
        ['role' => 'admin'],
    ],
    'age >=' => 18,
]);

---

Доступ к Connection

$connection = $mapper->getConnection();