Конструктор запросов (Query Builder)

Конструктор запросов Imhotep предоставляет удобный, плавный (fluent) интерфейс для создания и выполнения запросов к базе данных. Он поддерживает большинство операций, необходимых для работы с БД, и отлично работает со всеми поддерживаемыми системами управления базами данных. Он обеспечивает автоматическую защиту от SQL-инъекций через PDO-привязки.

Получение экземпляра конструктора

Для получения экземпляра конструктора запросов, используйте метод table фасада DB:

use Imhotep\Facades\DB;

// Получаем экземпляр конструктора запросов для таблицы "users"
$query = DB::table('users');

// С алиасом таблицы
$query = DB::table('users', 'u');
PHP

Работа с данными

Конструктор запросов предоставляет все необходимые методы для выполнения базовых операций с данными:

  • SELECT — получение, фильтрация, сортировка, группировка, соединения
  • INSERT — добавление одной или нескольких записей
  • UPDATE — изменение существующих записей
  • DELETE — удаление записей и очистка таблиц

Работа с выражениями (Expressions)

Для вставки сырых SQL-выражений в запрос используется класс Expression или DB::raw(). Это может быть полезно при вызове функций базы данных (NOW(), COUNT(*)), выполнении арифметических операций (price * 1.1) или использовании специфичных для СУБД конструкций.

use Imhotep\Facades\DB;
use Imhotep\Database\Expression;

DB::table('products')->update([
    'price' => new Expression('price * 1.1'),
    'updated_at' => DB::raw('NOW()')
]);
PHP

Важно: Значения, переданные в Expression или DB::raw(), НЕ ЭКРАНИРУЮТСЯ. Используйте их только с проверенными и безопасными значениями.

Использование мастер-соединения

По умолчанию SELECT-запросы выполняются через соединение для чтения (если настроена репликация). Метод useWritePDO() принудительно использует мастер-соединение (для записи) при выполнении запроса:

$users = DB::table('users')->useWritePDO()->get();
PHP

Гидратация моделей

Метод setModel указывает конструктору запросов, в какой класс модели следует преобразовывать результаты выборки. Это позволяет получать не объекты stdClass, а полноценные экземпляры ваших моделей со всеми их методами и атрибутами.

// Возвращает массив объектов User
$users = DB::table('users')
    ->setModel(User::class)
    ->get(); // [User, User, ...]
PHP

Важно: Модель должна наследовать базовый класс модели Imhotep\Database\Model\Model или если это содержать статический метод newFrom который первым аргументом принимает массив.

Отладка запросов

Конструктор запросов предоставляет несколько способов отладки SQL-запросов и их параметров. Методы отличаются поведением и областью применения:

dd() и dump() - отладка SELECT-запросов

Эти методы работают только с SELECT-запросами и позволяют увидеть SQL перед выполнением:

DB::table('users')
    ->where('age', '>', 18)
    ->dump() // Выведет SQL и параметры
    ->get(); // Запрос выполнится

// Остановит выполнение скрипта
DB::table('users')
    ->where('age', '>', 18)
    ->dd(); // Выведет SQL и параметры, затем остановит скрипт
PHP

withDump() и withSQL() - отладка любых запросов

Эти методы работают с любыми операциями (SELECT, INSERT, UPDATE, DELETE) и могут изменять поведение запроса:

// Выводит SQL и параметры, но НЕ выполняет запрос
DB::table('users')
    ->where('id', 1)
    ->withDump()
    ->delete();

// Возвращает SQL и параметры вместо выполнения
$result = DB::table('users')
    ->where('id', 1)
    ->withSQL()   // Вернет ['sql' => '...', 'bindings' => [...]]
    ->delete();
PHP