RUEN
Пакет · cdo

CDO

CDO (Connection Data Object) — расширенная обёртка над PDO для PHP. Она даёт безопасные параметризованные DML-операции — insert, update, delete, upsert и их пакетные варианты — типозависимый связыватель, который подбирает нужный PDO::PARAM_* для каждого значения, и Qb — композируемый конструктор запросов, порождающий защищённые от инъекций фрагменты WHERE. CDO говорит на PostgreSQL, MySQL/MariaDB и Oracle и подстраивает SQL под каждую из них.

Философия

  • Параметризация по умолчанию — каждое значение проходит через именованный плейсхолдер и типизированную привязку. На пути DML нигде нет конкатенации значений в строку, поэтому инъекция — не тот риск, о котором нужно помнить.
  • Учёт драйвера, но без привязки к нему — CDO определяет PostgreSQL, MySQL, MariaDB и Oracle в момент подключения и сам переписывает RETURNING, ON CONFLICT против ON DUPLICATE KEY UPDATE и обработку часового пояса.
  • Тонкий слой поверх PDO — CDO extends PDO, поэтому каждый знакомый метод (query, prepare, fetchAll, транзакции) остаётся на месте. Обёртка лишь добавляет удобство сверху и никогда не отнимает PDO.

Ключевые понятия

  • CDO — соединение. Наследует PDO и добавляет insert, insertGroup, upsert, upsertGroup, update, delete.
  • Qb — неизменяемый конструктор запросов. Статические фабрики (Qb::eq, Qb::and, …) возвращают композируемые фрагменты, каждый со своими значениями.
  • CDOBind — пара «имя + значение». Создаётся Qb автоматически; вручную — чтобы дать плейсхолдеру имя или переиспользовать его в нескольких условиях.
  • Классы конфигурации — наследуйте PgDbConfig / MySqlDbConfig (или используйте инлайновые PgDbCall / MySqlDbCall / DbCall), чтобы описать соединение.
  • ConnectionPool — реестр уровня процесса, создающий каждый конфиг один раз и возвращающий готовый CDO.

Ключевые возможности

  • Полный CRUD + upsert — одиночные и чанкованные пакетные вставки и апсерты с автоматическим возвратом первичного ключа там, где драйвер поддерживает RETURNING.
  • Композируемый Qb — операторы сравнения, NULL, множеств, шаблонов, диапазонов, логические, CASE и сырой SQL — всё сочетается через and / or / xor / clip.
  • Типозависимая привязка — null, bool, int, array (JSON), объекты (JsonSerializable, Stringable, DateTimeInterface, BackedEnum) привязываются с корректным PDO-типом.
  • Проверки здоровья — ping() и pingDetail() (статус + задержка) у каждого конфига, плюс ленивые connect / disconnect / reconnect.
  • Логирование PSR-3 — подключите любой LoggerInterface; каждый порождённый запрос логируется на уровне debug.

Когда подходит

Доступ к данным приложения, где нужны параметризованная безопасность и пакетная пропускная способность без веса полноценной ORM — сервисы, воркеры, импортёры и любое место, где вы уже тянетесь к PDO, но снова и снова пишете одну и ту же обвязку для insert/upsert.

Требования

  • PHP ≥ 8.3
  • ext-pdo и расширение драйвера вашей базы данных (pdo_pgsql, pdo_mysql или pdo_oci)
  • psr/log ^3.0

Полный список — в разделе Установка и требования.

Установка

bash
composer require flytachi/winter-cdo

На пробу

Получить соединение, вставить строку, прочитать сгенерированный id:

php
use Flytachi\Winter\Cdo\ConnectionPool;
use Flytachi\Winter\Cdo\Qb;

$cdo = ConnectionPool::db(AppDb::class);

$id = $cdo->insert('users', ['name' => 'Alice', 'email' => 'alice@example.com']);

$cdo->update('users', ['name' => 'Alice Smith'], Qb::eq('id', $id));

Пройдите путь целиком в Быстром старте.

Исходники и ссылки

Продолжайте с Установки и требований, Быстрого старта и Модели работы.