Eloquent Advanced — глубокий разбор

Relation — это объявленный в модели метод, который декларативно описывает связь с другой моделью. На основании этого объявления Eloquent генерирует SQL-запросы (SELECT, JOIN, подзапросы) и гидрирует результат в коллекцию связанных моделей.

Преимущества декларативного подхода относительно ручного построения запросов:

• отсутствие дублирования JOIN-логики между контроллерами и сервисами;
• работа с объектной моделью домена ($post->author->name) вместо плоских массивов;
• встроенная оптимизация: with() и load() автоматически устраняют проблему N+1;
• композиция relation с произвольными условиями: $user->posts()->where('published', true)->count().

Eloquent предоставляет десять типов отношений, разделённых на четыре категории по кардинальности и характеру связи: один к одному, один ко многим, многие ко многим и полиморфные.

Каждый тип разбирается по единой схеме: определение, область применения, генерируемый SQL, синтаксис объявления и использования. Порядок изложения: четыре базовых типа, две модификации «через промежуточную модель», четыре полиморфных варианта.

// Таблица profiles: id, user_id, bio, avatar
class User extends Model
{
    public function profile(): HasOne
    {
        return $this->hasOne(Profile::class);
        // эквивалентно: hasOne(Profile::class, 'user_id', 'id')
    }
}

// Использование
$user->profile;             // Profile или null
$user->profile->bio;        // доступ к полю
$user->profile()->create(['bio' => 'Hello']);  // создать привязанный profile

class Post extends Model
{
    public function author(): BelongsTo
    {
        // 2-й параметр — имя FK (если не стандартное user_id)
        return $this->belongsTo(User::class, 'user_id');
    }
}

$post->author;                // User или null
$post->author()->associate($user);    // привязать (set user_id)
$post->author()->dissociate();         // отвязать (user_id = null)

class Post extends Model
{
    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class);
    }
}

$post->comments;                          // Collection<Comment>
$post->comments()->where('approved', true)->get(); // фильтр
$post->comments()->create(['body' => 'Привет']);    // создать привязанный
$post->comments()->count();                  // число коммов (SELECT COUNT)

// Pivot-таблица role_user: user_id + role_id
class User extends Model
{
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class);
    }
}

$user->roles;                          // Collection<Role>
$user->roles()->attach(3);              // добавить роль с id=3
$user->roles()->detach(3);              // отвязать роль с id=3
$user->roles()->sync([1, 2, 5]);       // оставить ровно эти, остальные убрать

// Country → User → Profile
class Country extends Model
{
    public function primaryProfile(): HasOneThrough
    {
        return $this->hasOneThrough(Profile::class, User::class);
        // SQL: SELECT profiles.* FROM profiles
        //      INNER JOIN users ON profiles.user_id = users.id
        //      WHERE users.country_id = ? LIMIT 1
    }
}

$country->primaryProfile;  // Profile или null

class Country extends Model
{
    public function posts(): HasManyThrough
    {
        return $this->hasManyThrough(Post::class, User::class);
    }
}

$country->posts;            // Collection<Post> — все посты всех юзеров страны
$country->posts()->count();   // число одним SQL

// Таблица images: id, imageable_type, imageable_id, url
class User extends Model
{
    public function avatar(): MorphOne
    {
        return $this->morphOne(Image::class, 'imageable');
    }
}

class Post extends Model
{
    public function cover(): MorphOne
    {
        return $this->morphOne(Image::class, 'imageable');
    }
}

$user->avatar->url;
$post->cover->url;

// Таблица comments: id, commentable_type, commentable_id, body
class Post extends Model
{
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}

class Photo extends Model
{
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}

$post->comments;                       // Collection<Comment>
$post->comments()->create(['body' => '!']);  // commentable_type=App\Models\Post автоматически

class Comment extends Model
{
    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }
}

$comment->commentable;     // Post, Photo, или Video — в зависимости от commentable_type

if ($comment->commentable instanceof Post) { ... }

// Pivot polymorphic: taggables (tag_id, taggable_id, taggable_type)
class Post extends Model
{
    public function tags(): MorphToMany
    {
        return $this->morphToMany(Tag::class, 'taggable');
    }
}

class Tag extends Model
{
    // На стороне «общей» сущности — обратная связь morphedByMany
    public function posts(): MorphToMany
    {
        return $this->morphedByMany(Post::class, 'taggable');
    }

    public function photos(): MorphToMany
    {
        return $this->morphedByMany(Photo::class, 'taggable');
    }
}

$post->tags()->attach($tag->id);    // прикрепить тег
$tag->posts;                       // все посты с этим тегом
$tag->photos;                      // все фото с этим тегом

Чтобы продемонстрировать взаимодействие всех изложенных типов отношений, рассмотрим схему многопользовательского блога. Большинство десяти relation встретится в одной модельной структуре.

Сущности предметной области:

• User — зарегистрированный пользователь; автор статей, комментариев и лайков;
• Profile — расширенная информация о пользователе, вынесенная в отдельную таблицу;
• Post — опубликованная статья;
• Comment — комментарий, оставленный к Post или Photo;
• Photo — самостоятельный медиаобъект в галерее;
• Tag — тематическая метка, применимая и к Post, и к Photo;
• Like — реакция, оставленная к Post, Comment или Photo;
• Country — географическая принадлежность пользователя.

// ═══════════════════ User ═══════════════════
class User extends Model
{
    // hasOne — один профиль
    public function profile(): HasOne
    {
        return $this->hasOne(Profile::class);
    }

    // hasMany — много постов
    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }

    // belongsTo — юзер принадлежит стране
    public function country(): BelongsTo
    {
        return $this->belongsTo(Country::class);
    }
}

// ═══════════════════ Post ═══════════════════
class Post extends Model
{
    // belongsTo — автор
    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    // morphMany — комментарии (полиморфные, могут быть и у Photo)
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }

    // morphToMany — теги (общие с Photo)
    public function tags(): MorphToMany
    {
        return $this->morphToMany(Tag::class, 'taggable');
    }

    // morphMany — лайки
    public function likes(): MorphMany
    {
        return $this->morphMany(Like::class, 'likeable');
    }
}

// ═══════════════════ Comment ═══════════════════
class Comment extends Model
{
    // morphTo — к чему привязан комментарий (Post или Photo)
    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }

    // belongsTo — автор коммента
    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }
}

// ═══════════════════ Tag ═══════════════════
class Tag extends Model
{
    // morphedByMany — обратная сторона polymorphic many-to-many
    public function posts(): MorphToMany
    {
        return $this->morphedByMany(Post::class, 'taggable');
    }

    public function photos(): MorphToMany
    {
        return $this->morphedByMany(Photo::class, 'taggable');
    }
}

// ═══════════════════ Country ═══════════════════
class Country extends Model
{
    // hasMany — много юзеров
    public function users(): HasMany
    {
        return $this->hasMany(User::class);
    }

    // hasManyThrough — все посты всех юзеров страны
    public function posts(): HasManyThrough
    {
        return $this->hasManyThrough(Post::class, User::class);
    }

    // hasOneThrough — главный модератор страны (один первый по дате)
    public function leadModerator(): HasOneThrough
    {
        return $this->hasOneThrough(Profile::class, User::class)
            ->where('users.role', 'moderator');
    }
}

Типовые сценарии применения объявленных отношений:

// 1. Страница страны: пользователи, посты, главный модератор — одним набором запросов
$country = Country::with(['users.profile', 'posts.author', 'leadModerator'])
    ->findOrFail(1);

// 2. Лента блога — посты с автором, тегами, числом комментов и лайков
$feed = Post::with(['author.profile', 'tags'])
    ->withCount(['comments', 'likes'])
    ->latest()
    ->paginate(10);

// 3. Привязать тег к посту
$post->tags()->attach($tag->id);
$post->tags()->sync([1, 2, 3]); // заменить все теги на эти

// 4. Оставить комментарий к посту (через morphMany)
$post->comments()->create([
    'body' => 'Привет!',
    'user_id' => auth()->id(),
]);

// 5. На странице коммента узнать, к чему он привязан
if ($comment->commentable instanceof Post) {
    return route('posts.show', $comment->commentable);
} elseif ($comment->commentable instanceof Photo) {
    return route('photos.show', $comment->commentable);
}

// 6. Все посты, отмеченные тегом "laravel"
$posts = Tag::where('name', 'laravel')->first()->posts;

// 7. Юзеры, у которых есть хотя бы один опубликованный пост
User::whereHas('posts', fn($q) => $q->where('status', 'published'))
    ->get();

Отношение «многие ко многим» реализуется в реляционных базах данных через промежуточную таблицу, традиционно называемую pivot-таблицей. Она содержит как минимум два внешних ключа, ссылающихся на связываемые сущности, и может включать дополнительные атрибуты, описывающие саму связь, — временные метки, статус, автор присвоения, дату истечения.

Объявление belongsToMany в модели Eloquent скрывает работу с этой таблицей: при обращении к свойству выполняется JOIN, при вызове методов attach, detach, sync производятся соответствующие INSERT и DELETE. При этом дополнительные колонки pivot-таблицы доступны через специальный атрибут pivot на связанной модели.

Понимание pivot-таблицы как самостоятельного хранилища данных о связи — ключевое отличие промышленного применения отношений от учебных примеров. Большинство реальных задач (управление ролями с истечением, корзина с количеством товара, участники проекта с уровнем доступа) требуют не только факта связи, но и её атрибутов.

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

Схема данных:

// Миграция таблиц
Schema::create('roles', function (Blueprint $table) {
    $table->id();
    $table->string('name')->unique();
    $table->string('description')->nullable();
    $table->timestamps();
});

Schema::create('role_user', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->foreignId('role_id')->constrained()->cascadeOnDelete();
    $table->foreignId('granted_by_user_id')->constrained('users');
    $table->timestamp('expires_at')->nullable();
    $table->timestamps();
    $table->unique(['user_id', 'role_id']);
});

Pivot-модель с инкапсулированной доменной логикой:

class RoleAssignment extends Pivot
{
    protected $table = 'role_user';
    public $incrementing = true;

    protected $casts = [
        'expires_at' => 'datetime',
    ];

    public function isActive(): bool
    {
        return $this->expires_at === null
            || $this->expires_at->isFuture();
    }

    public function grantedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'granted_by_user_id');
    }
}

Объявления отношений на основных моделях:

class User extends Model
{
    // Все назначения, в том числе истёкшие — для аудита.
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(Role::class)
            ->using(RoleAssignment::class)
            ->withPivot(['id', 'expires_at', 'granted_by_user_id'])
            ->withTimestamps();
    }

    // Только действующие роли — для авторизации.
    public function activeRoles(): BelongsToMany
    {
        return $this->roles()->where(function ($q) {
            $q->whereNull('role_user.expires_at')
              ->orWhere('role_user.expires_at', '>', now());
        });
    }
}

Типовые операции и контексты их применения:

// 1. Выдача роли с указанием срока и автора назначения.
$user->roles()->attach($adminRoleId, [
    'expires_at' => now()->addYear(),
    'granted_by_user_id' => auth()->id(),
]);

// 2. Замена набора ролей пользователя в рамках обновления профиля админом.
//    Каждая запись синхронизации получает одного и того же автора.
$user->roles()->syncWithPivotValues(
    $request->input('role_ids', []),
    ['granted_by_user_id' => auth()->id()]
);

// 3. Продление срока действия роли без создания новой записи.
$user->roles()->updateExistingPivot($roleId, [
    'expires_at' => now()->addMonths(6),
]);

// 4. Проверка прав в middleware или политике.
public function hasRole(string $name): bool
{
    return $this->activeRoles()->where('name', $name)->exists();
}

// 5. Журнал назначений конкретной роли с авторами и сроками.
$history = $user->roles()
    ->with('pivot.grantedBy')
    ->orderByPivot('created_at', 'desc')
    ->get();

// 6. Запланированная очистка истёкших назначений из таблицы.
//    Выполняется в Artisan-команде по расписанию.
DB::table('role_user')
    ->whereNotNull('expires_at')
    ->where('expires_at', '<', now()->subMonth())
    ->delete();

Отношения hasOneThrough и hasManyThrough описывают транзитивный обход графа моделей через одну промежуточную сущность. Они применяются, когда между исходной и конечной таблицами отсутствует прямая связь, но существует посредник, через которого связь однозначно прослеживается.

Альтернативный способ получить тот же набор данных — последовательно загрузить промежуточные модели и затем обратиться к их связям. Такой подход порождает либо проблему N+1, либо требует ручной агрегации идентификаторов и составления отдельного запроса. Декларация hasManyThrough сводит весь обход к одному SQL-запросу с JOIN.

Принципиальное ограничение метода — глубина цепочки. Стандартный Eloquent поддерживает ровно одну промежуточную модель. Для более длинных цепочек (например, Country — Region — City — Hotel) применяются либо ручной JOIN, либо специализированные пакеты вроде staudenmeir/eloquent-has-many-deep.

Рассмотрим платформу управления проектами, где организация (Organization) содержит команды (Team), а каждая команда выполняет задачи (Task). Требуется получать сводные данные на уровне организации без последовательного обхода команд.

Схема данных:

organizations: id, name, plan
teams:         id, organization_id, name, leader_id
tasks:         id, team_id, title, status, completed_at

Объявления отношений:

class Organization extends Model
{
    public function teams(): HasMany
    {
        return $this->hasMany(Team::class);
    }

    // Все задачи всех команд организации одним запросом.
    public function tasks(): HasManyThrough
    {
        return $this->hasManyThrough(Task::class, Team::class);
    }

    // Завершённые задачи — с дополнительным условием в той же relation.
    public function completedTasks(): HasManyThrough
    {
        return $this->hasManyThrough(Task::class, Team::class)
            ->whereNotNull('tasks.completed_at');
    }
}

class Team extends Model
{
    public function organization(): BelongsTo
    {
        return $this->belongsTo(Organization::class);
    }

    public function tasks(): HasMany
    {
        return $this->hasMany(Task::class);
    }
}

Типовые операции и контексты их применения:

// 1. Общее число задач организации для шапки дашборда.
//    Один SQL вместо обхода всех команд.
$totalTasks = $organization->tasks()->count();

// 2. Список просроченных задач для письма-уведомления администратору.
$overdue = $organization->tasks()
    ->where('tasks.status', 'in_progress')
    ->where('tasks.due_at', '<', now())
    ->get();

// 3. Eager loading в выборке организаций для админ-панели.
//    withCount по through-связи работает аналогично hasMany.
$organizations = Organization::withCount(['tasks', 'completedTasks'])
    ->orderByDesc('tasks_count')
    ->get();

foreach ($organizations as $org) {
    $percent = $org->tasks_count > 0
        ? round($org->completed_tasks_count / $org->tasks_count * 100)
        : 0;
}

// 4. Поиск задачи с проверкой принадлежности организации текущего пользователя.
//    Используется в политике доступа.
public function view(User $user, Task $task): bool
{
    return $user->organization->tasks()
        ->whereKey($task->id)
        ->exists();
}

// 5. Сравнение с whereHas: выбрать организации, в которых есть хотя бы одна
//    задача со статусом «blocked». Возвращает Organization, а не Task.
$blockedOrgs = Organization::whereHas('tasks', function ($q) {
    $q->where('tasks.status', 'blocked');
})->get();

Полиморфные отношения позволяют единственной таблице обслуживать связи с несколькими различными моделями. В отличие от обычной связи, где внешний ключ ссылается на одну конкретную таблицу, полиморфная связь хранит дополнительную колонку с именем класса родителя. Это даёт возможность сохранить одну запись (например, комментарий или лайк), не привязываясь жёстко к одному типу владельца.

Альтернативой полиморфному подходу было бы создание отдельных таблиц для каждого типа связи: post_comments, photo_comments, video_comments. Такой подход приводит к дублированию схемы, тройной реализации одних и тех же бизнес-операций (создание, валидация, удаление, отображение) и сложной агрегации при выводе универсальных лент.

Полиморфизм реализуется парой колонок: {name}_type хранит имя класса родителя (например, App\Models\Post), а {name}_id — его идентификатор. Eloquent на основе значения _type определяет, в какой таблице искать запись, и инстанцирует соответствующую модель.

Метод применяется в системах комментариев, отметок «нравится», вложений, изображений-обложек, тегов, аудит-логов и любых сценариях, где одна семантика связи распространяется на разнородные сущности.

Спроектируем универсальный модуль комментариев и реакций (likes), применимый к постам, фотографиям и видео. Помимо хранения данных, модуль должен поддерживать вложенные ответы, отображение унифицированной ленты активности пользователя и эффективную выгрузку родительских сущностей одним запросом.

Схема таблиц:

posts:     id, user_id, title, body
photos:    id, user_id, url, caption
videos:    id, user_id, source_url, duration_sec

comments:  id, user_id, parent_id, body, commentable_type, commentable_id
reactions: id, user_id, kind, reactable_type, reactable_id

Морф-карта в провайдере (обязательно):

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    Relation::enforceMorphMap([
        'post'  => Post::class,
        'photo' => Photo::class,
        'video' => Video::class,
    ]);
}

Трейт, инкапсулирующий объявление полиморфных связей для упрощения подключения к нескольким моделям:

trait HasCommentsAndReactions
{
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable')
            ->whereNull('parent_id');
    }

    public function reactions(): MorphMany
    {
        return $this->morphMany(Reaction::class, 'reactable');
    }
}

class Post extends Model  { use HasCommentsAndReactions; }
class Photo extends Model { use HasCommentsAndReactions; }
class Video extends Model { use HasCommentsAndReactions; }

Модель Comment с поддержкой вложенности и обратной связью:

class Comment extends Model
{
    protected $fillable = ['user_id', 'parent_id', 'body'];

    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class, 'user_id');
    }

    public function replies(): HasMany
    {
        return $this->hasMany(self::class, 'parent_id');
    }
}

Типовые операции и их применение:

// 1. Создание комментария к произвольной сущности через её relation.
//    commentable_type и commentable_id заполняются Eloquent автоматически.
$post->comments()->create([
    'user_id' => auth()->id(),
    'body'    => $request->input('body'),
]);

// 2. Дерево комментариев с eager loading вложенных ответов.
$tree = $post->comments()
    ->with(['author', 'replies.author'])
    ->latest()
    ->get();

// 3. Универсальная лента активности пользователя.
//    Возвращает комментарии без знания, к чему они привязаны;
//    morphWith подгружает специфичные relation для каждого типа родителя.
$activity = Comment::where('user_id', $user->id)
    ->with([
        'commentable' => function (MorphTo $q) {
            $q->morphWith([
                Post::class  => ['author'],
                Video::class => ['author'],
            ]);
        },
    ])
    ->latest()
    ->paginate(20);

// 4. Маршрутизация при отображении комментария: определяем URL родителя.
public function parentUrl(Comment $comment): string
{
    return match ($comment->commentable_type) {
        'post'  => route('posts.show',  $comment->commentable_id),
        'photo' => route('photos.show', $comment->commentable_id),
        'video' => route('videos.show', $comment->commentable_id),
    };
}

// 5. Подсчёт числа реакций каждого типа для произвольной сущности.
$counts = $post->reactions()
    ->select('kind', DB::raw('COUNT(*) as total'))
    ->groupBy('kind')
    ->pluck('total', 'kind');

// 6. Удаление всех комментариев и реакций при удалении родителя.
//    Реализуется через observer, поскольку morphMany не поддерживает
//    каскадное удаление на уровне БД (там нет FK).
class CleanupCommentsObserver
{
    public function deleting(Model $model): void
    {
        $model->comments()->delete();
        $model->reactions()->delete();
    }
}

Eager loading — механизм предварительной загрузки связанных моделей единым набором запросов. Решает проблему N+1, возникающую при ленивом доступе к relation: когда для каждой записи родительской коллекции выполняется отдельный SELECT к таблице дочерней модели.

Принципиальное отличие от ленивой загрузки заключается в количестве запросов. Без eager loading выборка из ста пользователей с обращением к их профилям внутри цикла порождает 101 запрос: один на список пользователей и сто индивидуальных запросов на профили. С использованием with('profile') выполняются ровно два запроса: SELECT по таблице users и SELECT по таблице profiles с условием WHERE user_id IN (...), после чего Eloquent распределяет полученные профили между загруженными пользователями.

Eloquent предоставляет несколько вариантов eager loading, различающихся моментом применения (до или после получения коллекции), полнотой загружаемых данных (записи целиком или только агрегаты) и стратегией обработки уже загруженных relation.

Рассмотрим типичную задачу: построить страницу-ленту с пагинацией, в которой для каждого поста отображаются заголовок, автор, число комментариев, число лайков и три первых тега. Без правильного eager loading такой шаблон легко превращается в десятки запросов на страницу.

Структура моделей:

class Post extends Model
{
    public function author(): BelongsTo     { return $this->belongsTo(User::class, 'user_id'); }
    public function comments(): MorphMany  { return $this->morphMany(Comment::class, 'commentable'); }
    public function likes(): MorphMany     { return $this->morphMany(Like::class,    'likeable'); }
    public function tags(): MorphToMany    { return $this->morphToMany(Tag::class,  'taggable'); }
}

Контроллер ленты, выполняющий ровно одну выборку с eager loading и тремя агрегатами:

class FeedController extends Controller
{
    public function __invoke(): View
    {
        $posts = Post::query()
            ->where('status', 'published')
            ->with([
                'author:id,name,avatar_url',
                'tags' => fn($q) => $q->limit(3),
            ])
            ->withCount(['comments', 'likes'])
            ->latest('published_at')
            ->paginate(15);

        return view('feed.index', compact('posts'));
    }
}

Полный набор SQL-запросов на одну страницу ленты — четыре запроса, независимо от числа постов:

-- 1. Основная выборка постов с двумя коррелированными COUNT.
SELECT posts.*,
    (SELECT COUNT(*) FROM comments
     WHERE comments.commentable_id = posts.id
       AND comments.commentable_type = 'post') AS comments_count,
    (SELECT COUNT(*) FROM likes
     WHERE likes.likeable_id = posts.id
       AND likes.likeable_type = 'post') AS likes_count
FROM posts
WHERE status = 'published'
ORDER BY published_at DESC
LIMIT 15 OFFSET 0;

-- 2. Авторы постов одной выборкой.
SELECT id, name, avatar_url FROM users WHERE id IN (...);

-- 3. Связи постов с тегами через polymorphic pivot.
SELECT tags.*, taggables.taggable_id AS pivot_taggable_id
FROM tags
INNER JOIN taggables ON taggables.tag_id = tags.id
WHERE taggables.taggable_type = 'post'
  AND taggables.taggable_id IN (...);

-- 4. SELECT COUNT(*) для пагинатора (если используется LengthAwarePaginator).

При использовании Telescope или Debugbar убедитесь, что отображение страницы со 100 постами укладывается в эти четыре запроса. Любое отклонение свидетельствует о неучтённом обращении к relation в шаблоне.

Casts — механизм автоматического преобразования атрибутов модели между их представлением в базе данных и в коде PHP. При чтении значения из БД Eloquent применяет преобразование «get» (например, превращает JSON-строку в массив), при записи — обратное преобразование «set» (массив сериализуется в JSON).

Без кастов разработчик вынужден повсеместно вручную выполнять json_decode, Carbon::parse, (bool), что приводит к разбросу логики преобразований и ошибкам при их пропуске. Касты централизуют преобразование в декларации модели и гарантируют единообразие во всех точках обращения к полю.

Помимо встроенных типов, Eloquent позволяет создавать собственные классы кастов для произвольных value objects (Money, Color, GeoPoint, EmailAddress). Это даёт возможность хранить в БД примитивы, а в коде работать с типизированными доменными объектами, имеющими методы и инвариантами.

Рассмотрим модель заказа в интернет-магазине, в которой одновременно применяются несколько разновидностей кастов: enum для статуса, кастомный каст Money для суммы, AsCollection для строк заказа, шифрование для адреса доставки, datetime для жизненного цикла.

Схема таблицы:

orders:
  id, user_id,
  status            varchar(20),
  total_amount      bigint,             // в копейках
  total_currency    varchar(3),
  items             json,
  shipping_address  text,                // будет храниться зашифрованным
  placed_at         timestamp,
  paid_at           timestamp nullable,
  cancelled_at      timestamp nullable,
  created_at, updated_at

Объявление модели и сопутствующих типов:

enum OrderStatus: string
{
    case Draft     = 'draft';
    case Placed    = 'placed';
    case Paid      = 'paid';
    case Shipped   = 'shipped';
    case Cancelled = 'cancelled';

    public function canTransitionTo(self $next): bool
    {
        return match ([$this, $next]) {
            [self::Draft,   self::Placed]    => true,
            [self::Placed,  self::Paid]      => true,
            [self::Paid,    self::Shipped]   => true,
            [self::Placed,  self::Cancelled] => true,
            default => false,
        };
    }
}

class Order extends Model
{
    protected function casts(): array
    {
        return [
            'status'           => OrderStatus::class,
            'total'            => MoneyCast::class,
            'items'            => AsCollection::class,
            'shipping_address' => 'encrypted',
            'placed_at'        => 'immutable_datetime',
            'paid_at'          => 'immutable_datetime',
            'cancelled_at'     => 'immutable_datetime',
        ];
    }
}

Типовые операции и контексты их применения:

// 1. Создание заказа: касты применяются автоматически при сохранении.
$order = Order::create([
    'user_id'          => auth()->id(),
    'status'           => OrderStatus::Draft,
    'total'            => Money::usd(12999),
    'items'            => collect([
        ['sku' => 'A1', 'qty' => 2, 'price_cents' => 4999],
        ['sku' => 'B5', 'qty' => 1, 'price_cents' => 3001],
    ]),
    'shipping_address' => $request->input('address'),
    'placed_at'        => now(),
]);

// 2. Бизнес-проверка статуса с использованием метода enum.
if (! $order->status->canTransitionTo(OrderStatus::Paid)) {
    throw new DomainException('Invalid order status transition.');
}

// 3. Изменение коллекции items: AsCollection возвращает Collection, на которой
// доступны map/filter; результат корректно сериализуется обратно в JSON.
$order->items = $order->items->reject(fn($i) => $i['qty'] === 0);
$order->save();

// 4. Работа с зашифрованным адресом доставки.
logger()->info("Ship to: {$order->shipping_address}"); // расшифрованное значение
// В БД хранится непрозрачный шифротекст; даже при утечке дампа
// адреса остаются защищёнными без APP_KEY.

// 5. Сериализация модели в JSON для API.
return response()->json($order);
// Eloquent сериализует status как 'paid', total — как объект (если у Money есть JsonSerializable),
// даты — в формате ISO 8601, items — как массив. Зашифрованные поля попадут в расшифрованном виде,
// поэтому их обычно скрывают через $hidden.

// 6. Применение immutable datetime для предотвращения случайных мутаций.
// $order->placed_at = $order->placed_at->addHour() породит исключение, поскольку
// CarbonImmutable возвращает новый экземпляр; для изменения требуется явное переприсваивание.

Accessor — метод, вычисляющий значение атрибута при его чтении. Используется для производных атрибутов (полное имя из первого и фамилии, абсолютный URL аватара из относительного пути, человекочитаемая длительность из секунд) или для нормализации значения, лежащего в БД, перед выдачей в код.

Mutator — метод, преобразующий значение перед его сохранением в атрибут модели. Применяется для хеширования паролей, обрезки пробелов в email, нормализации регистра, упрощения единиц измерения.

Граница между mutator и cast в Laravel размыта: оба механизма преобразуют значение при чтении/записи. Различие в том, что cast описывает тип атрибута (как сериализовать в БД), а accessor/mutator описывает пользовательскую логику (как вычислить или нормализовать). Для повторно используемых преобразований предпочтителен кастомный cast; для логики, специфичной одной модели, — accessor/mutator.

В Laravel 9 был введён новый API на основе класса Illuminate\Database\Eloquent\Casts\Attribute. Он объединяет accessor и mutator в одном методе, поддерживает многоколоночные mutator (запись в несколько столбцов одним присваиванием) и встроенное кеширование результата. Старый стиль (getXxxAttribute / setXxxAttribute) остаётся работоспособным для обратной совместимости.

Рассмотрим модель User в проекте, где требуется ряд производных атрибутов: полное имя, инициалы, возраст по дате рождения, флаг полной верификации, временный URL аватара. Mutators применяются для нормализации входных данных: тримминг email, хеширование пароля, разбиение полного имени на составляющие.

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Storage;

class User extends Model
{
    protected $fillable = [
        'first_name', 'last_name', 'email', 'password',
        'birth_date', 'avatar_path', 'phone',
        'email_verified_at', 'phone_verified_at',
    ];

    protected $hidden   = ['password', 'remember_token'];
    protected $appends  = ['full_name', 'initials', 'age', 'is_fully_verified'];

    protected function casts(): array
    {
        return [
            'birth_date'         => 'immutable_date',
            'email_verified_at'  => 'datetime',
            'phone_verified_at'  => 'datetime',
        ];
    }

    // ───── Mutators (нормализация при записи) ─────

    protected function email(): Attribute
    {
        return Attribute::set(fn (string $v): string => strtolower(trim($v)));
    }

    protected function phone(): Attribute
    {
        return Attribute::set(fn (?string $v): ?string =>
            $v === null ? null : preg_replace('/\\D+/', '', $v));
    }

    protected function password(): Attribute
    {
        return Attribute::set(fn (string $v): string => Hash::make($v));
    }

    // ───── Accessors (производные атрибуты) ─────

    protected function fullName(): Attribute
    {
        return Attribute::make(
            get: fn ($value, array $attributes): string =>
                trim("{$attributes['first_name']} {$attributes['last_name']}"),

            set: function (string $value): array {
                $parts = explode(' ', trim($value), 2);
                return ['first_name' => $parts[0], 'last_name' => $parts[1] ?? ''];
            },
        );
    }

    protected function initials(): Attribute
    {
        return Attribute::get(fn ($value, array $a): string =>
            mb_substr($a['first_name'], 0, 1) . mb_substr($a['last_name'], 0, 1));
    }

    protected function age(): Attribute
    {
        return Attribute::get(fn (): ?int =>
            $this->birth_date?->diffInYears(now()));
    }

    protected function isFullyVerified(): Attribute
    {
        return Attribute::get(fn (): bool =>
            $this->email_verified_at !== null
            && $this->phone_verified_at !== null);
    }

    protected function avatarUrl(): Attribute
    {
        return Attribute::get(fn (): ?string =>
            $this->avatar_path
                ? Storage::disk('s3')->temporaryUrl($this->avatar_path, now()->addHour())
                : null)->shouldCache();
    }
}

Применение модели в типовых сценариях:

// 1. Регистрация: ввод преобразуется автоматически.
$user = User::create([
    'full_name'  => 'Алиса Браун',                // разобьётся на first_name, last_name
    'email'      => '  Alice@Example.COM  ',        // нормализуется до 'alice@example.com'
    'phone'      => '+7 (701) 555-12-34',           // сохранится как '77015551234'
    'password'   => $request->input('password'),     // захешируется bcrypt
    'birth_date' => '1990-06-15',
]);

// 2. Чтение производных полей.
echo $user->full_name;          // "Алиса Браун"
echo $user->initials;           // "АБ"
echo $user->age;                // 35
echo $user->is_fully_verified;  // false (email/phone ещё не подтверждены)
echo $user->avatar_url;         // S3-URL, кешируется в памяти инстанса

// 3. Сериализация для API: благодаря $appends, производные атрибуты попадают в JSON.
return response()->json($user);
// {
//   "id": 1, "first_name": "Алиса", "last_name": "Браун",
//   "email": "alice@example.com", "phone": "77015551234",
//   "full_name": "Алиса Браун", "initials": "АБ", "age": 35,
//   "is_fully_verified": false
// }

При сериализации модели в массив или JSON Eloquent по умолчанию включает все колонки таблицы, известные накопителю атрибутов, и не включает производные accessor-атрибуты. Свойства $hidden, $visible и $appends позволяют точечно настроить, какие поля попадают в результирующее представление.

Главная задача механизма — предотвращение случайной утечки чувствительных данных (пароли, токены, внутренние пометки) при сериализации модели и явное включение вычисляемых полей, не существующих в БД (полное имя, инициалы, число дочерних записей).

Свойства модели задают поведение по умолчанию для всех её экземпляров; дополнительно существуют методы инстанса, временно изменяющие список видимых полей для конкретного объекта (makeHidden, makeVisible, setHidden, setVisible, append). Для сложных сценариев, в которых форма ответа зависит от прав запрашивающего пользователя или версии API, рекомендуется использовать Eloquent Resource — отдельный класс-преобразователь, явно описывающий структуру выходных данных.

Рассмотрим API, в котором один и тот же ресурс User отдаётся в трёх вариантах: гостю — минимальная карточка с именем и аватаром; самому пользователю — полный профиль без чувствительных полей; администратору — полный набор полей, включая внутренние пометки и оценку риска. Поля для каждого случая декларируются комбинацией $hidden, $appends и динамических вызовов.

class User extends Model
{
    // Скрыты всегда — чувствительные поля, никогда не должны попадать в API.
    protected $hidden = [
        'password',
        'remember_token',
        'two_factor_secret',
        'two_factor_recovery_codes',
        'internal_notes',        // только для админов — раскроется через makeVisible
        'risk_score',            // только для админов
    ];

    // Производные поля, всегда отображаемые в JSON-выводе.
    protected $appends = ['full_name', 'avatar_url'];
}

Контроллер с тремя вариантами представления:

class UserController extends Controller
{
    // Гостевой запрос: минимальное представление через setVisible.
    public function publicShow(User $user): JsonResponse
    {
        return response()->json(
            $user->setVisible(['id', 'full_name', 'avatar_url'])
        );
    }

    // Личный кабинет: всё кроме чувствительных полей.
    public function selfShow(Request $request): JsonResponse
    {
        return response()->json($request->user());
        // password и токены скрыты через $hidden, остальное возвращается как есть.
    }

    // Админ: раскрытие внутренних полей и добавление вычисляемых.
    public function adminShow(User $user): JsonResponse
    {
        return response()->json(
            $user
                ->makeVisible(['internal_notes', 'risk_score'])
                ->append('last_login_at')
                ->loadCount(['posts', 'comments'])
        );
    }
}

Тот же подход применим к коллекциям:

// Для списка пользователей в гостевом справочнике — обнуляем чувствительные поля каждого.
$users = User::latest()->paginate(20);
$users->getCollection()->each->setVisible(['id', 'full_name', 'avatar_url']);
return response()->json($users);

Для проектов, в которых вариантов представления становится много, целесообразен переход на Eloquent Resources — отдельные классы-преобразователи, в которых форма ответа описана явно. Использование $hidden и компании остаётся актуальным как «защитная сетка» от случайной утечки полей при любом способе сериализации.

Scope — именованный фрагмент query builder, инкапсулирующий часто используемое условие или последовательность условий. Применение scope позволяет переиспользовать запросные правила в нескольких местах кода и сделать места их применения декларативными: вместо where('status', 'active')->where('deleted_at', null)->where(...) пишется active().

Eloquent различает два рода scope. Локальные объявляются как методы модели и применяются явно при построении запроса. Глобальные применяются автоматически ко всем запросам модели без дополнительных вызовов; их используют для системных условий, которые должны действовать всегда (фильтр по тенанту, скрытие soft-deleted, ограничение по правам доступа).

Глобальные scopes — основа таких функций Laravel, как Soft Deletes (SoftDeletingScope) и встроенная фильтрация архивных записей. Этот же приём активно применяется в коммерческих пакетах: spatie/laravel-permission, spatie/laravel-multitenancy, tenancy/tenancy.

Рассмотрим типичную многоарендную (multi-tenant) SaaS-платформу, в которой пользователи нескольких организаций работают в одной базе данных, но каждый видит только данные своей. Глобальный TenantScope гарантирует автоматическую изоляцию; локальные scope упрощают повседневные фильтры.

Сервис, хранящий идентификатор текущего арендатора в контейнере:

final class TenantManager
{
    private ?int $tenantId = null;

    public function setCurrentTenantId(?int $id): void  { $this->tenantId = $id; }
    public function currentTenantId(): ?int                  { return $this->tenantId; }
}

// Регистрация как singleton в провайдере.
$this->app->singleton(TenantManager::class);

Middleware определяет арендатора по поддомену запроса и устанавливает его в менеджер:

class SetCurrentTenant
{
    public function handle(Request $request, Closure $next): Response
    {
        $subdomain = explode('.', $request->getHost())[0];
        $tenant    = Tenant::where('slug', $subdomain)->firstOrFail();

        app(TenantManager::class)->setCurrentTenantId($tenant->id);

        return $next($request);
    }
}

Глобальный scope, накладываемый на все тенант-зависимые модели через трейт:

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

final class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $tenantId = app(TenantManager::class)->currentTenantId();
        if ($tenantId !== null) {
            $builder->where($model->qualifyColumn('tenant_id'), $tenantId);
        }
    }
}

trait BelongsToTenant
{
    public static function bootBelongsToTenant(): void
    {
        static::addGlobalScope(new TenantScope());

        // Автоматически подставлять tenant_id при создании.
        static::creating(function (Model $model): void {
            if ($model->tenant_id === null) {
                $model->tenant_id = app(TenantManager::class)->currentTenantId();
            }
        });
    }

    public function tenant(): BelongsTo
    {
        return $this->belongsTo(Tenant::class);
    }
}

class Project extends Model
{
    use BelongsToTenant;

    public function scopeArchived(Builder $query): Builder
    {
        return $query->whereNotNull('archived_at');
    }

    public function scopeOwnedBy(Builder $query, User $user): Builder
    {
        return $query->where('owner_user_id', $user->id);
    }
}

Типовые операции в коде приложения:

// 1. Обычные пользовательские запросы — TenantScope невидим, фильтр накладывается автоматически.
$projects = Project::latest()->paginate(20);
// SELECT * FROM projects WHERE tenant_id = ? ORDER BY ... LIMIT 20

// 2. Комбинация локальных scope с глобальным.
$myArchived = Project::archived()->ownedBy($user)->get();

// 3. Системная задача аналитики, обходящая все тенанты.
Project::withoutGlobalScope(TenantScope::class)
    ->selectRaw('tenant_id, COUNT(*) as cnt')
    ->groupBy('tenant_id')
    ->get();

// 4. Artisan-команда для миграции данных одного конкретного тенанта.
app(TenantManager::class)->setCurrentTenantId($argTenantId);
Project::archived()->chunkById(200, function ($batch) {
    // бизнес-логика
});

// 5. Создание проекта: tenant_id подставляется автоматически из BelongsToTenant.
Project::create(['name' => 'Q4 Roadmap', 'owner_user_id' => auth()->id()]);

Soft Deletes — механизм логического удаления, при котором запись остаётся в таблице, но помечается как удалённая через timestamp в специальной колонке deleted_at. Eloquent автоматически исключает помеченные записи из стандартных выборок, оставляя возможность восстановления и аудита.

Технически реализован через глобальный scope SoftDeletingScope, добавляющий условие deleted_at IS NULL ко всем запросам модели, и переопределённый метод delete(), который вместо SQL DELETE выполняет UPDATE, устанавливая текущее время в deleted_at.

Применяется в нескольких типовых сценариях: пользователю предоставляется возможность отменить удаление (корзина, восстановление аккаунта), система обязана сохранять историю изменений для аудита или регуляторных требований, удаление родительской записи не должно нарушать ссылочную целостность для связанных записей в логах и архивах. Альтернативой soft delete служит выделенная архивная таблица или event-sourcing, однако soft delete сохраняет простоту работы с одной таблицей и сохраняет существующие индексы.

Рассмотрим административную панель CMS, в которой статьи удаляются логически. Пользователю в течение 30 дней доступно восстановление из корзины, после чего отдельная задача физически очищает старые записи. При окончательном удалении статьи освобождаются связанные файлы из хранилища, а при логическом удалении каскадом удаляются комментарии и реакции.

Структура моделей и схемы:

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->string('slug');
    $table->string('title');
    $table->text('body');
    $table->json('attachments')->nullable();
    $table->timestamps();
    $table->softDeletes();

    // Условный (partial) уникальный индекс на slug — только среди активных записей,
    // чтобы освободить slug после soft delete и не блокировать переиспользование.
    // Синтаксис специфичен СУБД: для PostgreSQL ниже, для MySQL 8 — generated column.
});

// PostgreSQL partial unique index
DB::statement('CREATE UNIQUE INDEX posts_slug_unique ON posts(slug) WHERE deleted_at IS NULL');

class Post extends Model
{
    use SoftDeletes;

    protected $casts = [
        'attachments' => 'array',
    ];

    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class);
    }
}

class Comment extends Model
{
    use SoftDeletes;
}

Observer, реализующий каскадное поведение:

use Illuminate\Support\Facades\Storage;

class PostObserver
{
    public function deleting(Post $post): void
    {
        if ($post->isForceDeleting()) {
            // Окончательное удаление — освобождаем хранилище и удаляем связанные.
            foreach ((array) $post->attachments as $path) {
                Storage::delete($path);
            }
            $post->comments()->withTrashed()->forceDelete();
        } else {
            // Логическое удаление — каскад только в пределах живых дочерних.
            $post->comments()->delete();
        }
    }

    public function restored(Post $post): void
    {
        // При восстановлении возвращаем комментарии, удалённые именно вместе с постом.
        $post->comments()
            ->onlyTrashed()
            ->where('deleted_at', '>=', $post->deleted_at)
            ->where('deleted_at', '<=', $post->deleted_at->addSeconds(5))
            ->restore();
    }
}

Контроллер корзины и операций восстановления:

class TrashController extends Controller
{
    // 1. Просмотр корзины: только удалённые записи текущего пользователя.
    public function index(Request $request): View
    {
        $posts = Post::onlyTrashed()
            ->where('user_id', $request->user()->id)
            ->orderByDesc('deleted_at')
            ->paginate(20);

        return view('trash.index', compact('posts'));
    }

    // 2. Восстановление: поиск по withTrashed, чтобы найти даже удалённую запись.
    public function restore(int $id): RedirectResponse
    {
        $post = Post::withTrashed()->findOrFail($id);
        $post->restore();

        return redirect()->route('posts.show', $post);
    }

    // 3. Окончательное удаление по запросу пользователя.
    public function forceDelete(int $id): RedirectResponse
    {
        Post::withTrashed()->findOrFail($id)->forceDelete();

        return redirect()->route('trash.index');
    }
}

Запланированная Artisan-команда, очищающая корзину старше 30 дней:

class PruneOldTrash extends Command
{
    protected $signature = 'trash:prune {--days=30}';

    public function handle(): int
    {
        $threshold = now()->subDays((int) $this->option('days'));

        Post::onlyTrashed()
            ->where('deleted_at', '<', $threshold)
            ->chunkById(200, function (Collection $batch) {
                $batch->each->forceDelete();
                // Через каждый экземпляр — чтобы сработал observer с очисткой файлов.
            });

        return self::SUCCESS;
    }
}

// app/Console/Kernel.php
$schedule->command('trash:prune')->dailyAt('03:00');

Стандартные методы Query Builder (where, join, orderBy) покрывают большую часть запросов. Однако в продакшен-задачах регулярно требуется встроить подзапрос в SELECT-список, наложить условие EXISTS, выполнить арифметическое выражение или агрегатную функцию, для которых нет специализированного метода. Для таких случаев Eloquent предоставляет API подзапросов и сырых SQL-выражений.

Подзапросы (addSelect, selectSub, whereExists, fromSub) позволяют декларативно встроить SELECT внутрь SELECT, при этом сохраняя биндинг параметров и защиту от SQL-инъекций. Сырые выражения (DB::raw, selectRaw, whereRaw, orderByRaw) дают возможность вставить произвольный фрагмент SQL для случаев, когда даже API подзапросов недостаточен.

Сырой SQL — обоюдоострый инструмент. С одной стороны, он раскрывает полную мощь СУБД (оконные функции, выражения CASE, JSON-операторы PostgreSQL, специфичные функции). С другой стороны, при некорректном использовании он открывает уязвимость SQL-инъекции и ломает переносимость кода между разными СУБД. Главное правило: пользовательский ввод всегда передаётся через биндинг параметров, никогда не конкатенируется в строку SQL.

Рассмотрим страницу отчёта в админ-панели: для каждого пользователя необходимо отобразить число заказов, общую сумму, дату последнего заказа, число неудачных попыток входа за последние 7 дней, среднюю оценку оставленных отзывов. Все эти данные должны быть получены одним SQL-запросом, без N+1 и без множественных eager loadings.

Реализация на построителе с подзапросами:

use App\Models\Login;
use App\Models\Order;
use App\Models\Review;

class UserReportController extends Controller
{
    public function __invoke(Request $request): View
    {
        $users = User::query()
            ->addSelect([
                // Сумма всех оплаченных заказов.
                'orders_total' => Order::selectRaw('COALESCE(SUM(amount), 0)')
                    ->whereColumn('orders.user_id', 'users.id')
                    ->whereNotNull('paid_at'),

                // Количество оплаченных заказов.
                'orders_count' => Order::selectRaw('COUNT(*)')
                    ->whereColumn('orders.user_id', 'users.id')
                    ->whereNotNull('paid_at'),

                // Дата последнего оплаченного заказа.
                'last_order_at' => Order::select('paid_at')
                    ->whereColumn('orders.user_id', 'users.id')
                    ->whereNotNull('paid_at')
                    ->orderByDesc('paid_at')
                    ->limit(1),

                // Число неудачных логинов за последние 7 дней.
                'failed_logins_7d' => Login::selectRaw('COUNT(*)')
                    ->whereColumn('logins.user_id', 'users.id')
                    ->where('success', false)
                    ->where('created_at', '>=', now()->subWeek()),

                // Средняя оценка оставленных отзывов.
                'avg_review_rating' => Review::selectRaw('AVG(rating)')
                    ->whereColumn('reviews.user_id', 'users.id'),
            ])
            ->// Фильтр: только активные пользователи с хотя бы одним заказом.
            ->where('status', 'active')
            ->whereExists(function (Builder $q) {
                $q->selectRaw(1)
                  ->from('orders')
                  ->whereColumn('orders.user_id', 'users.id')
                  ->whereNotNull('paid_at');
            })
            ->// Сортировка по подзапросу — наиболее ценные клиенты сверху.
            ->orderByDesc(
                Order::selectRaw('COALESCE(SUM(amount), 0)')
                    ->whereColumn('orders.user_id', 'users.id')
                    ->whereNotNull('paid_at')
            )
            ->paginate(50);

        return view('admin.reports.users', compact('users'));
    }
}

Альтернативная реализация через fromSub для группировки данных, когда логика отчёта сложнее и требует промежуточной агрегации:

// Топ-10 продуктов по объёму продаж за квартал, с долей в общем обороте.
$totals = DB::table('order_items')
    ->selectRaw('product_id, SUM(qty * price) as revenue')
    ->whereBetween('created_at', [now()->subQuarter(), now()])
    ->groupBy('product_id');

$report = DB::query()
    ->fromSub($totals, 't')
    ->join('products', 'products.id', '=', 't.product_id')
    ->select('products.name', 't.revenue')
    ->selectRaw('t.revenue / SUM(t.revenue) OVER () * 100 AS share_pct')
    ->orderByDesc('t.revenue')
    ->limit(10)
    ->get();

Стандартные методы get() и all() загружают полный результат запроса в память приложения. При выборках в десятки тысяч и миллионы строк это приводит к исчерпанию памяти PHP, длительной задержке перед началом обработки и невозможности параллельной работы. Eloquent предоставляет четыре механизма потоковой обработки больших выборок: chunk, chunkById, lazy и cursor.

Эти механизмы решают одну задачу — обработать большой набор данных, не загружая его полностью в память — но реализуют её разными способами и имеют разные ограничения. Различия касаются количества выполняемых SQL-запросов, расхода памяти, безопасности при модификации обрабатываемых записей и интерфейса доступа (массив порциями, итератор по одному, ленивая коллекция).

Выбор метода критически важен для корректности и производительности bulk-операций. Неправильно выбранный механизм может пропускать или дублировать записи, исчерпать память на длинных циклах, либо заблокировать таблицу на время обработки.

Рассмотрим запланированную Artisan-команду, которая еженощно генерирует CSV-отчёт о транзакциях за прошедший месяц, отправляет уведомления пользователям с подозрительной активностью и архивирует записи старше двух лет. Для каждой подзадачи используется наиболее подходящий механизм обхода.

use Illuminate\Console\Command;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Storage;

class MonthlyTransactionReport extends Command
{
    protected $signature = 'reports:transactions {--month=}';

    public function handle(): int
    {
        $month = Carbon::parse($this->option('month') ?? 'last month');
        $this->exportToCsv($month);
        $this->notifySuspiciousAccounts($month);
        $this->archiveOldTransactions();

        return self::SUCCESS;
    }

    // 1. Экспорт: только чтение, миллионы строк, минимальная память — используем cursor().
    private function exportToCsv(Carbon $month): void
    {
        $path   = storage_path("reports/transactions-{$month->format('Y-m')}.csv");
        $handle = fopen($path, 'w');
        fputcsv($handle, ['id', 'user_id', 'amount', 'currency', 'created_at']);

        foreach (Transaction::whereBetween('created_at', [
            $month->copy()->startOfMonth(),
            $month->copy()->endOfMonth(),
        ])->cursor() as $tx) {
            fputcsv($handle, [
                $tx->id,
                $tx->user_id,
                $tx->amount,
                $tx->currency,
                $tx->created_at->toIso8601String(),
            ]);
        }

        fclose($handle);
        $this->info("CSV сохранён: {$path}");
    }

    // 2. Рассылка уведомлений: обходим пользователей партиями, модификация не задевает обходимых.
    //    Подходит обычный chunk().
    private function notifySuspiciousAccounts(Carbon $month): void
    {
        User::whereHas('transactions', function ($q) use ($month) {
            $q->whereBetween('created_at', [$month->startOfMonth(), $month->endOfMonth()])
              ->where('amount', '>', 10000);
        })->chunk(200, function (Collection $users) use ($month) {
            foreach ($users as $user) {
                $user->notify(new SuspiciousActivityNotification($month));
            }
        });
    }

    // 3. Архивация: каждая обработанная запись удаляется → используем chunkById,
    //    чтобы не пропускать «сдвинувшиеся» строки.
    private function archiveOldTransactions(): void
    {
        Transaction::where('created_at', '<', now()->subYears(2))
            ->chunkById(500, function (Collection $batch) {
                DB::transaction(function () use ($batch) {
                    ArchivedTransaction::insert($batch->map->toArchiveArray()->all());
                    Transaction::whereIn('id', $batch->modelKeys())->delete();
                });
            });
    }
}

Использование lazyById для случая, когда требуется сначала отфильтровать записи по полю, не индексированному в БД, а затем выполнить дальнейшую обработку:

// Поиск дублирующихся email-адресов среди миллионов пользователей
// без загрузки всех в память.
$duplicateGroups = User::lazyById(2000)
    ->groupBy(fn (User $u) => strtolower($u->email))
    ->filter(fn (LazyCollection $group) => $group->count() > 1);

Стандартные методы Eloquent для создания записи (create, save) работают через цикл гидрации модели: вызываются события, observers, mutators, casts, проставляются timestamps. Это удобно для одиночных операций, но неэффективно для массовых: вставка тысячи записей по одной займёт тысячи SQL-запросов и значительное время.

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

• insert() — bulk-вставка через Query Builder, минуя цикл Eloquent;
• upsert() — вставка с автоматическим обновлением при конфликте уникального индекса (INSERT ... ON CONFLICT/DUPLICATE KEY UPDATE);
• firstOrCreate(), firstOrNew(), updateOrCreate() — идемпотентное создание единичной записи на основе условия поиска.

Выбор между ними определяется характером задачи: разовое создание/обновление с активной бизнес-логикой (используется firstOrCreate/updateOrCreate) или массовая операция без бизнес-обработки (используется insert/upsert). Эти методы критичны при импорте данных, синхронизации с внешними системами, обновлении справочников и подобных задачах.

Рассмотрим запланированную задачу, которая загружает свежий прайс-лист поставщика (CSV с несколькими тысячами товаров), обновляет каталог: добавляет новые позиции, обновляет цены и остатки существующих, помечает отсутствующие как недоступные. Реализация комбинирует upsert для массового обновления и updateOrCreate для случаев, требующих бизнес-логики.

use Illuminate\Console\Command;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\LazyCollection;

class SyncSupplierCatalog extends Command
{
    protected $signature = 'catalog:sync {file}';

    public function handle(): int
    {
        $file = $this->argument('file');
        $now  = now();

        // 1. Считываем файл лениво, чтобы не загружать его в память целиком.
        $rows = LazyCollection::make(function () use ($file) {
            $h = fopen($file, 'r');
            $headers = fgetcsv($h);
            while (($line = fgetcsv($h)) !== false) {
                yield array_combine($headers, $line);
            }
            fclose($h);
        });

        // 2. Массовое обновление каталога через upsert по партиям.
        //    Для каждой партии формируется ровно один SQL.
        $processedSkus = [];

        $rows->chunk(500)->each(function (LazyCollection $batch) use ($now, &$processedSkus) {
            $payload = $batch->map(fn (array $row): array => [
                'sku'          => $row['sku'],
                'name'         => $row['name'],
                'price'        => (int) $row['price_cents'],
                'stock'        => (int) $row['stock'],
                'is_available' => true,
                'created_at'   => $now,
                'updated_at'   => $now,
            ])->all();

            Product::upsert(
                $payload,
                uniqueBy: ['sku'],
                update:   ['name', 'price', 'stock', 'is_available', 'updated_at'],
            );

            $processedSkus = array_merge($processedSkus, array_column($payload, 'sku'));
        });

        // 3. Товары, отсутствующие в файле — помечаются недоступными.
        //    Здесь требуется не bulk-операция, а обработка с событием Eloquent (для индексации).
        Product::whereNotIn('sku', $processedSkus)
            ->where('is_available', true)
            ->chunkById(200, function ($batch) {
                foreach ($batch as $product) {
                    $product->update(['is_available' => false]);
                    // событие updated сработает → search index пересчитается через observer
                }
            });

        return self::SUCCESS;
    }
}

Дополнительные сценарии применения idempotent-методов:

// 1. Регистрация подписки на email-рассылку — не создаёт дубликат.
NewsletterSubscriber::firstOrCreate(
    ['email' => $email],
    ['subscribed_at' => now(), 'source' => 'landing-page'],
);

// 2. Идемпотентная обработка webhook платёжной системы:
//    повторная доставка не создаст дубликат, но обновит статус.
PaymentEvent::updateOrCreate(
    ['provider' => $provider, 'external_id' => $webhook->id()],
    ['status' => $webhook->status(), 'received_at' => now()],
);

// 3. Импорт CSV-справочника валютных курсов: тысячи строк, один SQL.
ExchangeRate::upsert(
    $rates,
    uniqueBy: ['pair', 'date'],
    update:   ['rate'],
);

Жизненный цикл модели Eloquent включает несколько этапов: чтение из БД, создание, обновление, удаление, восстановление. На каждом из них Eloquent публикует событие, к которому может быть привязана реакция: логирование, отправка уведомлений, инвалидация кэша, синхронизация со сторонними системами, проверка прав доступа.

Механизм событий моделей реализует pattern Domain Events: бизнес-логика побочных эффектов отделяется от основной операции записи и выносится в independent reaction. Это позволяет добавлять и снимать слушателей без модификации модели, тестировать побочные эффекты изолированно, переиспользовать одни и те же реакции в разных контекстах.

Eloquent предоставляет четыре способа подписки на события: статические методы в booted() модели (для самой модели), Observer-классы (для группировки нескольких реакций в одном файле), bootable traits (для переиспользования между моделями), свойство $dispatchesEvents (для интеграции с системой Event/Listener Laravel и преобразования в полноценные события приложения).

Рассмотрим модель Article в CMS, использующую события для нескольких задач одновременно: автоматическая генерация slug, аудит изменений, инвалидация кэша, отправка уведомлений редактору, контроль за допустимыми переходами статусов.

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Str;

class Article extends Model
{
    protected $fillable = ['title', 'slug', 'body', 'status', 'published_at'];

    protected $dispatchesEvents = [
        'created' => ArticleCreated::class,
        'updated' => ArticleUpdated::class,
    ];

    protected static function booted(): void
    {
        // 1. Перед сохранением: автогенерация slug, если не задан.
        static::saving(function (Article $article): void {
            $article->slug ??= Str::slug($article->title);
        });

        // 2. Перед обновлением: проверка допустимости перехода статуса.
        static::updating(function (Article $article): ?bool {
            if (! $article->isDirty('status')) {
                return null;
            }

            $from = $article->getOriginal('status');
            $to   = $article->status;
            if (! ArticleStatus::canTransition($from, $to)) {
                throw new InvalidStateTransition($from, $to);
            }

            // При публикации проставляем дату.
            if ($to === 'published') {
                $article->published_at = now();
            }

            return null;
        });

        // 3. После сохранения: аудит изменений в журнале.
        static::updated(function (Article $article): void {
            $changes = $article->getChanges();
            if (! empty($changes)) {
                AuditLog::create([
                    'auditable_type' => Article::class,
                    'auditable_id'   => $article->id,
                    'action'         => 'updated',
                    'changes'        => $changes,
                    'user_id'        => auth()->id(),
                ]);
            }
        });

        // 4. После любого сохранения — инвалидация кэшей.
        static::saved(function (Article $article): void {
            Cache::forget("article:{$article->slug}");
            Cache::tags(['articles'])->flush();
        });

        // 5. Перед удалением — запрет на удаление опубликованных статей с комментариями.
        static::deleting(function (Article $article): ?bool {
            if ($article->status === 'published' && $article->comments()->exists()) {
                return false;
            }
            return null;
        });

        // 6. После удаления — освобождение прикреплённых файлов.
        static::deleted(function (Article $article): void {
            $article->attachments()->each->delete();
        });

        // 7. При репликации — очищаем уникальный slug, чтобы он сгенерировался заново.
        static::replicating(function (Article $article): void {
            $article->slug         = null;
            $article->published_at = null;
            $article->status       = 'draft';
        });
    }
}

Стороннее использование событий через $dispatchesEvents и Event/Listener:

class SendPublishedNotification implements ShouldQueue
{
    public function handle(ArticleUpdated $event): void
    {
        if ($event->article->wasChanged('status')
            && $event->article->status === 'published') {

            $event->article->author->notify(new ArticlePublishedNotification($event->article));
        }
    }
}

// Регистрация в EventServiceProvider или через атрибут #[OnEvent].

Observer — класс, группирующий обработчики нескольких событий жизненного цикла одной модели в едином файле. По функциональности эквивалентен набору подписок через booted(), но даёт лучшую структуру кода и поддерживает Dependency Injection в методы.

Применяется, когда количество обработчиков события превышает 2-3, либо когда логика реакций тесно связана между собой и должна развиваться как единое целое: подсистема аудита, нормализация данных, каскадные операции по жизненному циклу.

Observer не подменяет $dispatchesEvents и Event/Listener — они решают разные задачи. Observer удобен для логики, привязанной к модели и её жизненному циклу (создал User — создай Profile). Event/Listener подходит для широких доменных событий, на которые подписывается множество независимых слушателей (OrderPlaced — отправь email, обнови inventory, обнови аналитику). Часто оба механизма используются параллельно: observer выполняет «инфраструктурную» логику, а $dispatchesEvents диспетчит event для бизнес-реакций.

Рассмотрим модель User, для которой требуется обширная инфраструктурная логика: при создании автоматически формируется профиль, отправляется welcome-email, генерируется API-токен; при изменении email сбрасывается верификация и логируется событие; при удалении пользователя соблюдаются регуляторные требования по сохранности данных; при смене пароля очищаются все активные сессии и оповещаются ответственные администраторы. Использование двух observers разделяет ответственности.

// app/Observers/UserLifecycleObserver.php — инфраструктурная логика
namespace App\Observers;

use App\Models\User;
use App\Notifications\PasswordChangedNotification;
use App\Notifications\WelcomeNotification;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class UserLifecycleObserver
{
    // 1. Перед сохранением — нормализация email и автогенерация UUID при создании.
    public function creating(User $user): void
    {
        $user->uuid  ??= (string) Str::uuid();
        $user->email   = strtolower(trim($user->email));
    }

    // 2. После создания — создание зависимых сущностей в одной транзакции.
    public function created(User $user): void
    {
        DB::afterCommit(function () use ($user) {
            $user->profile()->create(['bio' => '']);
            $user->apiTokens()->create(['name' => 'default', 'token' => Str::random(60)]);
            $user->notify(new WelcomeNotification());
        });
    }

    // 3. При смене email — сброс верификации и логирование.
    public function updating(User $user): void
    {
        if ($user->isDirty('email')) {
            $user->email_verified_at = null;
        }
    }

    // 4. При смене пароля — очистка всех сессий и уведомление пользователя.
    public function updated(User $user): void
    {
        if ($user->wasChanged('password')) {
            DB::table('sessions')->where('user_id', $user->id)->delete();
            $user->notify(new PasswordChangedNotification());
        }
    }

    // 5. При удалении — анонимизация и сохранение для отчётности.
    public function deleting(User $user): void
    {
        if (! $user->isForceDeleting()) {
            // soft delete — анонимизируем PII, сохраняя структурную целостность.
            $user->forceFill([
                'email' => "deleted-{$user->id}@example.invalid",
                'name'  => '(deleted)',
                'phone' => null,
            ])->saveQuietly();
        }
    }
}

// app/Observers/UserAuditObserver.php — отдельный observer для аудита.
class UserAuditObserver
{
    public function created(User $user): void
    {
        AuditLog::record('user.created', $user);
    }

    public function updated(User $user): void
    {
        AuditLog::record('user.updated', $user, [
            'changes' => $user->getChanges(),
        ]);
    }

    public function deleted(User $user): void
    {
        AuditLog::record('user.deleted', $user);
    }
}

Подключение обоих observers через атрибут на модели:

use Illuminate\Database\Eloquent\Attributes\ObservedBy;

#[ObservedBy([UserLifecycleObserver::class, UserAuditObserver::class])]
class User extends Authenticatable
{
    use SoftDeletes;
}

Bootable trait — механизм автоматической инициализации поведения модели при её загрузке. Если в трейте определён статический метод с именем boot{TraitName}(), Eloquent вызывает его автоматически при первой загрузке использующей модели. Это позволяет инкапсулировать как обработчики событий жизненного цикла, так и регистрацию scopes, в переиспользуемом виде.

На этом механизме реализованы все встроенные трейты Eloquent: SoftDeletes, HasFactory, Notifiable, MassPrunable, HasUuids. Каждый из них — обычный PHP-трейт с методом boot{Name}(), регистрирующим необходимые scopes и обработчики событий.

Применение собственных bootable traits оправдано, когда одно и то же поведение требуется на нескольких моделях: автогенерация slug, проставление UUID, аудит изменений, кеширование, привязка к тенанту, поддержка тегов. Альтернативы — абстрактные базовые классы (нарушают возможность наследования от Authenticatable) или копирование кода в каждую модель (нарушает DRY).

Помимо boot{Name}(), трейт может определять метод initialize{TraitName}(), вызываемый для каждого инстанса модели при его создании — это полезно для проставления значений по умолчанию, не зависящих от события creating.

Рассмотрим набор трейтов, типичный для среднего и крупного приложения: HasUuid для публичных идентификаторов, HasSlug для URL-friendly строк, TracksUserActivity для проставления автора создания и последнего изменения. Каждый трейт самодостаточен, не конфликтует с другими и может быть подключён к произвольной модели.

// app/Models/Concerns/HasUuid.php
namespace App\Models\Concerns;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;

trait HasUuid
{
    public function initializeHasUuid(): void
    {
        $this->mergeCasts(['uuid' => 'string']);
    }

    public static function bootHasUuid(): void
    {
        static::creating(function (Model $model): void {
            $model->uuid ??= (string) Str::uuid();
        });
    }

    // Для маршрутизации по UUID вместо id.
    public function getRouteKeyName(): string
    {
        return 'uuid';
    }
}

// app/Models/Concerns/HasSlug.php
trait HasSlug
{
    public static function bootHasSlug(): void
    {
        static::saving(function (Model $model): void {
            if (empty($model->slug) || $model->isDirty($model->getSlugSourceColumn())) {
                $model->slug = $model->generateUniqueSlug(
                    $model->getAttribute($model->getSlugSourceColumn())
                );
            }
        });
    }

    public function getSlugSourceColumn(): string
    {
        return 'title';
    }

    protected function generateUniqueSlug(string $source): string
    {
        $base  = Str::slug($source);
        $slug  = $base;
        $count = 2;

        while (static::where('slug', $slug)
            ->when($this->exists, fn ($q) => $q->whereKeyNot($this->getKey()))
            ->exists()
        ) {
            $slug = "{$base}-{$count}";
            $count++;
        }

        return $slug;
    }
}

// app/Models/Concerns/TracksUserActivity.php
trait TracksUserActivity
{
    public static function bootTracksUserActivity(): void
    {
        static::creating(function (Model $model): void {
            $model->created_by_user_id ??= auth()->id();
            $model->updated_by_user_id = auth()->id();
        });

        static::updating(function (Model $model): void {
            $model->updated_by_user_id = auth()->id();
        });
    }

    public function createdBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'created_by_user_id');
    }

    public function updatedBy(): BelongsTo
    {
        return $this->belongsTo(User::class, 'updated_by_user_id');
    }
}

Использование всех трёх трейтов на модели Article:

use App\Models\Concerns\HasSlug;
use App\Models\Concerns\HasUuid;
use App\Models\Concerns\TracksUserActivity;

class Article extends Model
{
    use HasUuid, HasSlug, TracksUserActivity;

    protected $fillable = ['title', 'body', 'status'];

    // Никакой кастомизации для трейтов не требуется — используются дефолты:
    // HasUuid → колонка uuid с автогенерацией
    // HasSlug → колонка slug на основе title
    // TracksUserActivity → колонки created_by_user_id, updated_by_user_id
}

// Кастомизация: использовать другую колонку как источник slug.
class Project extends Model
{
    use HasUuid, HasSlug, TracksUserActivity;

    public function getSlugSourceColumn(): string
    {
        return 'name';
    }
}