Построение запросов (Query Builder)

Одна из задач, которую берут на себя ORM – это построение произвольных SQL-запросов в базу данных. Вот как это делается с помощью Eloquent:

<?php

// SELECT * FROM users WHERE name = "John" ORDER BY name DESC LIMIT 10
$users = User::where('name', 'John') // WHERE
    ->orderBy('name', 'desc') // ORDER BY
    ->take(10) // LIMIT
    ->get();

foreach ($users as $user) {
    echo $user->first_name;
}

Такая цепочка вызовов поэтапно конструирует необходимый запрос. Метод get() указывает на окончание запроса и выполняет его в базе данных. Eloquent автоматически конвертирует вернувшиеся данные в объекты модели и возвращает их наружу. Если нужно вернуть только одну запись, то вместо get() можно использовать first():

<?php

// SELECT * FROM users WHERE name = "John" LIMIT 1
$user = User::where('name', 'John')->first();

Порядок вызовов функций не важен. Сначала можно сортировать, а потом фильтровать:

<?php

$users = User::orderBy('name', 'desc')
    ->where('name', 'John')
    ->get();
// SELECT * FROM users WHERE name = "John" ORDER BY name DESC

Eloquent самостоятельно расставит все части в правильном порядке. Несмотря на такую заботу, всё же рекомендуется там, где это возможно соблюдать ожидаемый порядок вызовов. Это упростит чтение кода.

Многие вызовы могут накапливаться. Цепочка из where породит в SQL-запросе одну часть WHERE, где все условия объединены с помощью оператора AND.

<?php

User::where('name', 'John')->where('age' => 34)->where('city', 'Moscow')->get();
// WHERE name = "John" AND age = 34 AND city = "Moscow"

Обратите внимание на то, что первый вызов всегда идёт через статический метод самой модели. Все дальнейшие вызовы выполнятся из объекта, который возвращает первый вызов. Это касается любого метода и зависит от порядка вызовов:

<?php

// Статический метод orderBy
User::orderBy('name', 'desc')->where('name', 'John');

// Статический метод where
User::where('name', 'John')->orderBy('name', 'desc');

Будьте осторожны: в Eloquent каждый вызов в цепочке изменяет объект запроса. Это значит, что каждый отдельный запрос нужно строить заново, либо использовать клонирование.

<?php
$scope = User::orderBy('name', 'desc');
$scope->where('name', 'John'); // этот вызов изменяет $scope
print_r($scope->toSQL());
// SELECT * FROM users WHERE name = "John" ORDER BY name DESC

$scope->where('age', '18');
print_r($scope->toSQL());
// SELECT * FROM users WHERE name = "John" AND age = 18 ORDER BY name DESC

В языке запросов Eloquent есть по методу на каждую часть SQL. Некоторые из них в таблице ниже:

метод	sql
where	WHERE
orderBy	ORDER
take	LIMIT
select	SELECT
skip	OFFSET
groupBy	GROUP

Мы рассмотрим только некоторые из них. Все остальное достаточно легко понять из документации если вы знаете SQL. Если вы его не знаете, то самое время пройти курс основы баз данных.

Where – наиболее часто используемая часть при построении запросов. Ниже примеры кода и описание:

<?php

// WHERE votes = 100
// Равносильно User::where('votes', 100);
User::where('votes', '=', 100);

// WHERE votes >= 100
// Кроме >= можно использовать все что поддерживается базой данных.
User::where('votes', '>=', 100);

У метода Where много специализированных версий:

<?php

// orWhere – соединяется с другими вызовами "where" через оператор OR
$users = User::where('votes', '>', 100)->orWhere('name', 'John')->get();

// WHERE id IN (1, 2, 3)
$users = User::whereIn('id', [1, 2, 3])->get();

// Проверка по дате
$users = User::whereDate('created_at', '2016-12-31')->get();

Зачем?

Для чего нужен такой язык, почему недостаточно SQL? На это есть несколько разных причин:

Универсальность. Eloquent способна генерировать SQL, подходящий под конкретную базу данных. Построение запросов же не привязано к базе данных. Хотя это не отменяет ситуаций, в которых приходится выполнять "сырые" запросы в базу данных.
Безопасность. Такой способ построения запросов автоматически экранирует все подставляемые значения.
Автоматическая конвертация. Если делать запросы руками, то придётся руками же описывать как выбранные данные должны лечь на свойства конкретной модели. Это довольно серьёзная работа, которую лучше поручить ORM (во многом она для этого и создавалась).
Динамические запросы. SQL очень плохо подходит для динамических запросов, когда они конструируются по условиям. Такое часто встречается в фильтрах.

Самостоятельная работа

Откройте REPL. Попробуйте повыбирать пользователей по разным условиям.

Дополнительные материалы

Язык запросов