ℹ️ Eloquent Query Classes: дать важному запросу имя

Eloquent отличный слой работы с БД, и большую часть времени where()->with()->paginate() прямо в контроллере или джобе — это нормально. Лишняя абстракция на каждый чих только мешает.

Но проект растёт, и часть запросов перестаёт быть деталью реализации. Они становятся частью бизнес-логики.

Один и тот же фильтр всплывает в дашборде, экспорте, отчёте, фоновой джобе и API. Дублируешь — копии разъезжаются. Прячешь в модель, она пухнет от скоупов и статиков.

В этот момент запросу пора дать имя.

🔹 Что это

Query Class — это Action-паттерн, применённый к запросам. Один публичный вход — handle(). Принимает параметры, строит/выполняет запрос, возвращает результат: коллекцию, пагинатор, агрегат, число затронутых строк или Builder, если вызывающему нужно продолжить композицию.

final readonly class PendingOrdersQuery
{
    public function handle(?int $merchantId = null, int $perPage = 50): LengthAwarePaginator
    {
        return Order::query()
            ->with(['customer', 'payment'])
            ->whereIn('status', [OrderStatus::Pending, OrderStatus::PaymentFailed])
            ->where('created_at', '<=', now()->subMinutes(15))
            ->when($merchantId !== null,
                fn (Builder $q) => $q->where('merchant_id', $merchantId))
            ->latest()
            ->paginate($perPage);
    }
}

Контроллер больше не знает определения «заказов, требующих внимания». Это определение теперь называется PendingOrdersQuery.

🔹 Это НЕ репозиторий

Репозиторий обычно оборачивает каждый метод модели в generic-CRUD и притворяется, что БД нет. Query Class делает обратное: не прячет Eloquent, а централизует один конкретный важный запрос. Репозиторий = источник данных. Query Class = одна операция против БД с чёткой целью.

🔹 А чем плохи local scopes?

Ничем. Для переиспользуемого ограничения, которое естественно принадлежит модели, скоуп — первый инструмент. Query Class уместен, когда запрос перерос простое ограничение: координирует несколько скоупов, тащит кучу опциональных фильтров, рулит eager loading под конкретный экран, возвращает агрегаты, используется из нескольких точек или требует отдельных тестов.

И они отлично работают вместе: модель владеет доменным ограничением (needingAttention()), Query Class — сценарием использования БД.

🔹 handle() возвращает результат или Builder?

Единый результат — выполняй внутри (->count(), ->paginate()). Один запрос нужен разным потребителям с разными типами результата — верни Builder:

$articles = new PublishedArticlesQuery()->handle()->paginate(12);
$urls     = new PublishedArticlesQuery()->handle()->get();

Только не превращай класс в свалку публичных методов — это снова тот самый generic-репозиторий. Хорошие Query Classes скучные и сфокусированные.

🔹 Писать тоже умеют

Если ценность именно в самой операции с БД, запрос на запись тоже подходит:

final readonly class ExpireAbandonedOrdersQuery
{
    public function handle(CarbonImmutable $expiredBefore): int
    {
        return Order::query()
            ->where('status', OrderStatus::Pending)
            ->where('created_at', '<=', $expiredBefore)
            ->update(['status' => OrderStatus::Expired, 'expired_at' => now()]);
    }
}

Но если запись часть бизнес-воркфлоу (сайд-эффекты, диспатч джоб, смена стейта), её место в Action, а не здесь.

🔹 Когда использовать

Когда у операции есть бизнес-смысл: CustomersEligibleForDiscountQuery, InvoicesReadyToBeChargedQuery. Когда запрос повторяется, тяжёлый по фильтрам/eager loading, живёт в отчётах и фоне, должен тестироваться отдельно, а модель уже захлёбывается скоупами. Бонус — онбординг: новичок найдёт SearchOrdersQuery быстрее, чем цепочку в недрах контроллера.

🔹 Когда НЕ использовать

Article::findOrFail($id) не нуждается в FindArticleByIdQuery. Если имя класса просто дублирует метод Eloquent, если запрос в одном месте и прост, если скоуп уже всё выражает — не плоди классы. Начинай с чистого Eloquent. Выделяй Query Class, когда запрос это заслужил.

🔹 Тесты

Тестируем не Eloquent (его уже протестировали в Laravel), а наши правила: какие записи попадают, какие отсекаются, в каком порядке. Один тест на дефолтное поведение + точечные на важные фильтры и рискованные края. Комбинаторика всех фильтров не нужна.

🔹 Пять правил на каждый день

— Имя по бизнес-вопросу (PendingOrdersQuery), а не по операции (GetOrdersQuery)
— С записями избирательно: бизнес-правила → Action
— Без абстрактных базовых классов, пока нет реального дублирования
— Один публичный метод handle(), остальное private
— Не прячь Eloquent ради пряток. Возвращать Builder нормально

Ценность паттерна не в количестве классов, а в том, что код становится легче понимать, менять и доверять ему со временем.

✔️ PHP-тест: статус, которого нет в коде

Деплоя и релиза ещё не было, а 500-е посыпались сами собой 👇

📦 Задание

Интернет-магазин. Поддержка через админку добавила новый статус заказа refunded (возврат). Нужно было для отчётности, в БД просто появилось новое значение. Через час часть страниц «Мои заказы» начала отдавать 500. Падают только заказы, которым проставили новый статус.

// src/Order/OrderStatusLabel.php
class OrderStatusLabel
{
    public function render(string $status): string
    {
        return match ($status) {
            'new'       => 'Новый',
            'paid'      => 'Оплачен',
            'shipped'   => 'Отправлен',
            'delivered' => 'Доставлен',
            'cancelled' => 'Отменён',
        };
    }
}

// src/Order/OrderCard.php
class OrderCard
{
    public function __construct(private readonly OrderStatusLabel $label) {}

    public function build(Order $order): array
    {
        return [
            'id'     => $order->getId(),
            'status' => $this->label->render($order->getStatus()),
        ];
    }
}

🔹 Задачи

— Объяснить, чем поведение match тут отличается от switch и почему это привело к 500
— Предложить способ сделать код устойчивым к новым значениям, но НЕ замаскировать реальные баги

Ставьте → 🔥 если нравится формат. Если нет → 🌚

💬 Решения пишите в комменты под спойлер — сравним подходы.

⌨️ Топ-вакансий по PHP за неделю

PHP-разработчик — удалёнка/гибрид (Москва) — Гринсайт

PHP-разработчик (Laravel) — офис (Калининград) — ЖилиБыли

Tech Lead (PHP / Laravel) — 3 500 - 4 700 $ — удалёнка — Global Trads

➡️ Еще больше топовых вакансий — в нашем канале PHP Jobs

📊 UUID vs автоинкремент в качестве первичного ключа

Спор древний, но решается не вкусовщиной, а тем, кто и когда генерирует ключ.

🔹 Автоинкремент хорош, когда:

— Ключ нужен только внутри одной БД
— Важна плотная индексация и предсказуемый порядок вставки (B-tree счастлив)
— Не страшно, что /users/42 выдаёт размер таблицы наружу

🔹 UUID (а лучше UUIDv7) уместен, когда:

— ID нужно сгенерировать на клиенте/в другом сервисе до записи в БД
— Идёт шардирование или слияние данных из нескольких источников
— Последовательный ID — это утечка бизнес-метрики

⚠️ Частая ловушка

Случайный UUIDv4 как кластерный ключ в InnoDB. Вставки идут вразнобой по индексу → фрагментация страниц, распухание, просадка на записи. Именно поэтому появился UUIDv7, он временно-упорядоченный, ложится в индекс почти как автоинкремент, но остаётся глобально уникальным.

Практичный компромисс: автоинкремент как внутренний PK + UUIDv7 как публичный идентификатор в URL и API. Внутри — быстро, наружу — безопасно.

⚙️ Pest 

Элегантный фреймворк для тестирования, специально разработанный, чтобы вернуть удовольствие в процесс написания тестов. Фокусируется на простоте и читаемости кода.

Pest использует минимальный, понятный синтаксис и позволяет писать тесты с фокусом на то, что действительно важно — логику приложения. Отличается прогрессивным подходом: вы можете постепенно переходить с PHPUnit, без необходимости переписывать все тесты с нуля. Поддерживает параллельное выполнение тестов, browser testing с Playwright, и интеграцию со всеми популярными CI/CD платформами.

🔗 GitHub · Документация 

Библиотека пхпшника

✔️ PHP-тест: комментарий, который рассыпался на «кракозябры»

Превью комментария обрывается на половине эмодзи. А валидация то пропускает мусор, то режет нормальный текст 👇

📦 Задание

Сервис отзывов. Комментарий — VARCHAR(255) (255 символов в utf8mb4). Валидатор ограничивает длину, сервис делает короткое превью для карточки. Полгода всё работало, пока аудитория была русскоязычной с короткими текстами. После запуска в новых регионах посыпались жалобы: эмодзи и иероглифы в превью превращаются в ?, а форма то ругается на короткий текст, то молча режет данные при сохранении.

// src/Comment/CommentValidator.php
class CommentValidator
{
    private const MAX_LENGTH = 255;

    public function validate(string $text): void
    {
        if (strlen($text) > self::MAX_LENGTH) {
            throw new ValidationException('Слишком длинный комментарий');
        }
    }
}

// src/Comment/CommentPreview.php
class CommentPreview
{
    public function make(string $text): string
    {
        if (strlen($text) <= 100) {
            return $text;
        }

        return substr($text, 0, 100) . '…';
    }
}

🔹 Задачи

— Объяснить, почему эмодзи/иероглифы в превью бьются в «кракозябры»
— Объяснить, почему один и тот же текст то проходит валидацию, то нет, и как это расходится с лимитом колонки в БД
— Исправить и валидатор, и превью

Ставьте → 🔥 если нравится формат. Если нет → 🌚

💬 Решения пишите в комменты под спойлер — сравним подходы

🙈 Shared-nothing был киллер-фичей PHP. А мы его выкидываем, чтобы косплеить Node.js.

Двадцать лет «PHP в проде» означало одно: процесс на запрос, чистая таблица символов, в конце всё уничтожается. Никаких утечек, никакого состояния, любой стажёр не уронит прод глобалом.

Теперь модно иначе. FrankenPHP worker mode, RoadRunner, Swoole — держим приложение в памяти, экономим на бутстрапе, гоним 15k rps вместо 4k. Красиво в бенчмарках. А в реальности worker mode просто включает обратно все баги, от которых shared-nothing нас защищал. Статики, синглтоны, живые коннекты, $_SESSION, забытый static $cache в вендоре — теперь это не безобидный код, а мина между запросами разных юзеров.

Мы поменяли модель, где невозможно накосячить с состоянием, на модель, где косячить с состоянием — норма, просто «будьте аккуратнее».

💬 Где для вас граница? Воркеры — это зрелая эволюция или мы дружно ломаем главное преимущество языка ради цифры, которую видит только wrk?