Eloquent ORM для PHP: полное руководство с примерами

Что такое Eloquent ORM и зачем он нужен?

Eloquent ORM (Object-Relational Mapping) — это встроенная библиотека для работы с базами данных в PHP-фреймворке Laravel. Она предоставляет элегантный, интуитивно понятный способ взаимодействия с реляционными базами данных (MySQL, PostgreSQL, SQLite, SQL Server) с использованием Active Record паттерна.

Зачем нужен Eloquent?

• Абстракция SQL: Вместо написания сырых SQL-запросов вы работаете с объектами PHP. Это делает код чище, читаемее и безопаснее.
• Active Record: Каждая модель Eloquent представляет собой таблицу в базе данных. Экземпляр модели — это строка в этой таблице. Вы можете читать, изменять и сохранять данные, просто работая со свойствами объекта.
• Защита от SQL-инъекций: Eloquent использует PDO (PHP Data Objects) с подготовленными запросами, что автоматически экранирует пользовательский ввод.
• Отношения: Легко определять и использовать связи между таблицами (один к одному, один ко многим, многие ко многим и т.д.).
• Коллекции: Результаты запросов возвращаются в виде коллекций — мощных объектов, которые предоставляют множество полезных методов для обработки данных (map, filter, reduce, pluck и т.д.).
• Мутаторы и Аксессоры: Позволяют преобразовывать данные при сохранении (мутаторы) или при чтении (аксессоры) из базы данных.

Eloquent — это не просто библиотека, это фундаментальная часть экосистемы Laravel. Понимание Eloquent необходимо для эффективной разработки на этом фреймворке.

Установка

Eloquent ORM устанавливается автоматически вместе с фреймворком Laravel. Если вы создаете новый проект Laravel, Eloquent уже готов к использованию.

Установка через Composer (если вы используете Laravel):

composer create-project laravel/laravel example-app
cd example-app

Установка Eloquent без Laravel (Standalone):

Вы можете использовать Eloquent вне Laravel, например, в вашем собственном проекте. Для этого вам понадобится установить пакет illuminate/database и настроить соединение с базой данных.

composer require illuminate/database
composer require illuminate/events // Для работы с событиями моделей (опционально)

Пример настройки соединения (standalone):

<?php
require 'vendor/autoload.php';

use Illuminate\Database\Capsule\Manager as Capsule;

$capsule = new Capsule;

$capsule->addConnection([
    'driver'    => 'mysql',
    'host'      => 'localhost',
    'database'  => 'your_database',
    'username'  => 'your_username',
    'password'  => 'your_password',
    'charset'   => 'utf8',
    'collation' => 'utf8_unicode_ci',
    'prefix'    => '',
]);

// Настройка глобального экземпляра Eloquent
$capsule->setAsGlobal();

// Запуск Eloquent
$capsule->bootEloquent();

Быстрый старт с примером кода

Предположим, у нас есть таблица users в базе данных. Создадим модель Eloquent для работы с ней.

Шаг 1: Создание модели

В Laravel модели обычно хранятся в app/Models. Создадим файл User.php:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    // Eloquent автоматически свяжет эту модель с таблицей 'users'
    // Имя таблицы определяется по имени класса во множественном числе (snake_case)
    // Если таблица называется иначе, укажите свойство $table
    // protected $table = 'my_users';

    // Укажите, какие поля можно массово заполнять (для защиты от mass-assignment)
    protected $fillable = ['name', 'email', 'password'];
}

Шаг 2: Использование модели

Теперь мы можем использовать нашу модель для взаимодействия с базой данных:

<?php

use App\Models\User;

// 1. Создание нового пользователя
$user = new User();
$user->name = 'John Doe';
$user->email = 'john@example.com';
$user->password = bcrypt('secret'); // bcrypt для хеширования пароля
$user->save(); // Сохраняем в БД

// 2. Поиск пользователя по ID
$user = User::find(1);
echo $user->name; // John Doe

// 3. Обновление пользователя
$user = User::find(1);
$user->email = 'john.doe@example.com';
$user->save();

// 4. Удаление пользователя
$user = User::find(1);
$user->delete();

// 5. Массовое создание (используя $fillable)
$user = User::create([
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
    'password' => bcrypt('secret')
]);

// 6. Получение всех пользователей
$users = User::all();
foreach ($users as $user) {
    echo $user->name;
}

Этот простой пример показывает, как легко и интуитивно можно работать с базой данных с помощью Eloquent.

Основные методы/функции

Рассмотрим 10 ключевых методов Eloquent, которые вы будете использовать постоянно.

1. find($id)

Что делает: Находит запись по её первичному ключу (обычно id). Возвращает экземпляр модели или null, если запись не найдена.

Параметры:

• $id (mixed): Значение первичного ключа. Может быть массивом для поиска нескольких записей.

Рабочий пример кода:

<?php

use App\Models\User;

// Найти пользователя с ID 1
$user = User::find(1);
if ($user) {
    echo $user->name;
}

// Найти пользователей с ID 1, 2, 3
$users = User::find([1, 2, 3]);
foreach ($users as $user) {
    echo $user->name;
}

2. where($column, $operator = null, $value = null)

Что делает: Добавляет условие WHERE к запросу. Это основа для фильтрации данных. Можно вызывать цепочкой.

Параметры:

• $column (string): Имя столбца.
• $operator (string|null): Оператор сравнения (=, <, >, like и т.д.). Если не указан, по умолчанию =.
• $value (mixed|null): Значение для сравнения. Если $operator не указан, то $value будет вторым параметром, а оператор будет =.

Рабочий пример кода:

<?php

use App\Models\User;

// Все пользователи с именем 'John'
$users = User::where('name', 'John')->get();

// Все пользователи старше 18 лет
$users = User::where('age', '>', 18)->get();

// Все пользователи, email которых содержит 'example'
$users = User::where('email', 'like', '%example%')->get();

// Сложное условие: имя John ИЛИ возраст > 25
$users = User::where('name', 'John')->orWhere('age', '>', 25)->get();

3. get()

Что делает: Выполняет построенный запрос и возвращает коллекцию всех подходящих записей. Это финальный шаг в цепочке построителя запросов.

Параметры:

• $columns (array): Массив столбцов, которые нужно получить. По умолчанию ['*'] (все столбцы).

Рабочий пример кода:

<?php

use App\Models\User;

// Получить всех пользователей
$allUsers = User::get();

// Получить только имена и email всех пользователей
$users = User::get(['name', 'email']);

// Комбинация с where
$activeUsers = User::where('status', 'active')->get();

4. first()

Что делает: Выполняет запрос и возвращает первую запись из результата. Возвращает экземпляр модели или null.

Параметры:

• $columns (array): Массив столбцов для получения. По умолчанию ['*'].

Рабочий пример кода:

<?php

use App\Models\User;

// Найти первого пользователя с именем 'John'
$user = User::where('name', 'John')->first();

// Найти первого пользователя, отсортировав по ID по убыванию
$lastUser = User::orderBy('id', 'desc')->first();

// Если запись не найдена, можно вернуть значение по умолчанию
$user = User::where('name', 'NonExistent')->first() ?? new User();

5. create(array $attributes)

Что делает: Создает новую запись в базе данных и возвращает её экземпляр. Для работы метода необходимо определить свойство $fillable или $guarded в модели, чтобы защититься от массового присвоения (mass-assignment).

Параметры:

• $attributes (array): Ассоциативный массив данных для создания записи (ключ = имя столбца, значение = значение).

Рабочий пример кода:

<?php

use App\Models\User;

// Создать нового пользователя
$user = User::create([
    'name' => 'Alice',
    'email' => 'alice@example.com',
    'password' => bcrypt('password123')
]);

echo $user->id; // ID новой записи

6. update(array $values)

Что делает: Обновляет существующие записи в базе данных. Можно использовать как на экземпляре модели, так и в цепочке запросов для массового обновления.

Параметры:

• $values (array): Ассоциативный массив данных для обновления.

Рабочий пример кода:

<?php

use App\Models\User;

// Обновление конкретного пользователя
$user = User::find(1);
$user->update(['email' => 'new.email@example.com']);

// Массовое обновление: всем пользователям с ролью 'user' установить статус 'active'
User::where('role', 'user')->update(['status' => 'active']);

7. delete()

Что делает: Удаляет запись из базы данных. Можно использовать на экземпляре модели или в цепочке запросов для массового удаления.

Параметры:

• Нет параметров (для экземпляра). Для массового удаления используется в цепочке.

Рабочий пример кода:

<?php

use App\Models\User;

//