RUEN
Пакет · cdo

Операторы Qb

Полный набор операторов Qb. Каждый метод — статическая фабрика, возвращающая неизменяемый Qb; каждый аргумент-значение принимает сырой скаляр или CDOBind. Автогенерируемые плейсхолдеры именуются :iqb0, :iqb1, … в порядке создания.

Имена колонок должны быть доверенными идентификаторами

Параметризуются только значения. Аргумент $col каждого метода подставляется в SQL дословно, без кавычек и экранирования — как и сырой фрагмент raw() и условия WHEN в case(). Никогда не передавайте пользовательский ввод как имя колонки: Qb::eq('status', $userInput) безопасно, а Qb::eq($userInput, 'active') — вектор SQL-инъекции.

Чтение фрагмента

Две функции доступа дают части:

Метод Возвращает
getQuery() строку фрагмента SQL, напр. status = :iqb0
getBinds() CDOBind[] — по одной на плейсхолдер
getData() ['query' => string, 'binds' => CDOBind[]]

Сравнение

Метод SQL Типы значений
eq($col, $v) col = :v `CDOBind\
neq($col, $v) col != :v `CDOBind\
gt($col, $v) col > :v `CDOBind\
gte($col, $v) col >= :v `CDOBind\
lt($col, $v) col < :v `CDOBind\
lte($col, $v) col <= :v `CDOBind\
nsEq($col, $v) col <=> :v `CDOBind\

У eq и neq есть особые случаи для нескалярных значений:

Значение eq порождает neq порождает
null col IS NULL col IS NOT NULL
true col IS TRUE col IS NOT TRUE
false col IS FALSE col IS NOT FALSE

nsEq — синтаксис MySQL/MariaDB

<=> (NULL-безопасное равенство) нативно для MySQL/MariaDB. Эквивалент в PostgreSQL / стандартном SQL — IS NOT DISTINCT FROM; там пишите его через raw.

Проверки NULL

Метод SQL
isNull($col) col IS NULL
isNotNull($col) col IS NOT NULL

Принадлежность множеству

Метод SQL
in($col, $values) col IN (:a, :b, …)
notIn($col, $values) col NOT IN (:a, :b, …)

Пустые массивы бросают исключение

in() и notIn() бросают InvalidArgumentException на пустом массиве. Отфильтровывайте пустые списки из динамических фильтров перед вызовом — напр. $ids ? Qb::in('id', $ids) : null внутри and().

Сопоставление с шаблоном

Метод SQL При $insensitive = true
like($col, $v, $insensitive = false) col LIKE :v col ILIKE :v (PostgreSQL)
notLike($col, $v, $insensitive = false) col NOT LIKE :v col NOT ILIKE :v (PostgreSQL)

Подстановочные символы % / _ включайте в значение сами. На MySQL LIKE уже регистронезависим для небинарных колонок — не задавайте $insensitive. У Oracle нет ILIKE; используйте REGEXP_LIKE(col, val, 'i') через raw.

Диапазон

Метод SQL
between($col, $min, $max) col BETWEEN :min AND :max
notBetween($col, $min, $max) col NOT BETWEEN :min AND :max
betweenBy($v, $col1, $col2) :v BETWEEN col1 AND col2
notBetweenBy($v, $col1, $col2) :v NOT BETWEEN col1 AND col2

Варианты *By инвертируют форму: скалярное значение проверяется против двух колонок (напр. дата внутри окна валидности строки). Обе границы включительны.

Логика и группировка

Метод SQL Примечания
and(...$conds) a AND b AND … пропускает null / пустые условия
or(...$conds) a OR b OR … пропускает null / пустые условия
xor(...$conds) a XOR b XOR … нативно на MySQL/MariaDB
clip($cond) (cond) оборачивает в скобки; пустое пропускается как есть

Изменяемые построители

Эти мутируют экземпляр на месте (без возврата) вместо композиции нового — полезно для накопления в цикле:

Метод Эффект
addAnd($qb) добавить AND $qb
addOr($qb) добавить OR $qb
addXor($qb) добавить XOR $qb

CASE

php
Qb::case([
  'score >= 90' => 'A',
  'score >= 75' => 'B',
  'score >= 60' => 'C',
], else: 'F');
// CASE WHEN score >= 90 THEN :iqb0
//      WHEN score >= 75 THEN :iqb1
//      WHEN score >= 60 THEN :iqb2
//      ELSE :iqb3 END

Ключи — это сырые SQL-условия (не привязываются); значения (и else) — это результирующие литералы и привязываются.

raw

php
Qb::raw(string $query, array $binds = []): Qb

Вставляет $query дословно, опционально с привязками. $binds принимает объекты CDOBind и/или пары имя => значение (ведущее : необязательно):

php
Qb::raw('JSON_CONTAINS(tags, :tag)', ['tag' => '"php"']);
Qb::raw('views > :v', [new CDOBind('v', 100)]);

raw не санитизируется

Строка запроса выдаётся как есть. Никогда не подставляйте в неё пользовательский ввод — привязывайте значения через $binds. Qb::custom() — устаревший псевдоним для raw.

empty

php
Qb::empty(): Qb

Пустой фрагмент-заглушка ('' без привязок). Молча игнорируется методами and / or / xor и add* — полезен как нейтральное значение по умолчанию.

Связанное