Как навести порядок в запросах Laravel с помощью кастомных Query Builders / Habr

Написано уже не мало статей о том как всё же укротить строители запросов в Laravel чтобы вся команда понимала "Что происходит?" на проекте. Но даже в 2026 году я всё ещё встречаю проекты, где программисты продолжают писать запросы везде где только можно, но не в одном обозначенном месте.

Да я раньше тоже писал запросы в Serviсe, Controller, Model - да и вообще, где только приходилось. Но все мы развиваемся и хотим создать вокруг себя сообщество, я бы даже сказал команду, команду которая будет писать код понятный каждому.

Поэтому я решил снова осветить данную тематику. В данной статье я покажу на личном примере, где я храню эти Builder и как использую. Также мы рассмотрим связку с Repository чтобы ваш код стал ещё лучше.

Рассмотрим банальный пример на модели User. Но мы с вами сделаем так чтобы мы могли пользоваться нашими Builder быстро и легко.

Для этого я предлагаю первым шагом реализовать trait. Чтобы не писать каждый раз в модели данный код в будущем.

Сразу хочу сказать эта реализация имеет некоторые ограничения вы можете перенести данные метод в модель для которой пишите Builder.

<?php

declare(strict_types=1);

namespace App\Models\Traits;

use Illuminate\Database\Eloquent\Builder;

trait HasCustomEloquentBuilder
{
    /**
     * Путь к папке с билдерами
     */
    private const string ELOQUENT_BUILDER_PATH = 'EloquentBuilders';

    /**
     * Метод для создания билдера
     * 
     * @return Builder<static>
     */
    public function newEloquentBuilder($query): Builder
    {
        /** @var Builder<static> */
        return new (str_replace('Models', self::ELOQUENT_BUILDER_PATH, static::class).'Builder')($query);
    }
}

Далее можем создать папку EloquentBuilders внутри app и далее создать там наш первый кастомный Builder.

<?php

declare(strict_types=1);

namespace App\EloquentBuilders;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

/**
 * @extends Builder<User>
 */
final class UserBuilder extends Builder
{
    public function whereActive(bool $isActive = true): self
    {
        return $this->where('is_active', $isActive);
    }
}

Далее мы можем создать модель и перейти к использованию нашего trait.

<?php

declare(strict_types=1);

namespace App\Models;

use App\EloquentBuilders\UserBuilder;
use App\Traits\HasCustomEloquentBuilder;
use Database\Factories\UserFactory;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

/**
 * User model
 *
 * @property int $id
 * @property string $name
 * @property bool $is_active
 *
 * @method static UserBuilder query()
 */
class User extends Authenticatable
{
    use HasApiTokens;
    use HasCustomEloquentBuilder;

    /** @use HasFactory<UserFactory> */
    use HasFactory;

    protected $fillable = [
        'name',
        'is_active',
    ];
}

Обычно после этого все идут в контроллер и пишут там примерно такое:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use App\UseCases\FetchUserList\FetchUseListHandler;
use Illuminate\Http\JsonResponse;

class UserController
{
    public function index(): JsonResponse
    {
        return new JsonResponse(User::query()->whereActive()->get());
    }
}

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

Нам надо пойти дальше и реализовать репозиторий, куда мы вынесем с вами наш код.

<?php

declare(strict_types=1);

namespace App\Repositories;

use App\Models\User;
use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Support\Collection;

class UserRepository implements UserRepositoryInterface
{
    /**
     * @return Collection<int, User>
     */
    public function fetchListActive(): Collection
    {
        /** @var Collection<int, User> */
        return User::query()->whereActive()->get();
    }
}

Теперь всё стало намного лучше и контроллер может выглядеть вот так:

<?php

declare(strict_types=1);

namespace App\Http\Controllers\Api;

use App\Repositories\Contracts\UserRepositoryInterface;
use Illuminate\Http\JsonResponse;

class UserController
{
    public function index(UserRepositoryInterface $repository): JsonResponse
    {
        return new JsonResponse($repository->fetchListActive());
    }
}

Но я прибегну к использованию UseCase и напишу код ещё чище. Реализацию полной версии вы сможете посмотреть в проекте примере: https://github.com/palachX/laravel-usecase

<?php

namespace App\Http\Controllers\Api;

use App\UseCases\FetchUserList\FetchUseListHandler;
use Illuminate\Http\JsonResponse;

class UserController
{
    public function index(FetchUseListHandler $fetchUseListHandler): JsonResponse
    {
        return new JsonResponse($fetchUseListHandler->handle());
    }
}

В последствии вы можете добавить разные фильтры в ваш Builder и это всё будет в ручном управлении и в одном месте. Если вдруг вам надо будет написать чистые запросы у вас есть прослойка репозитория. Если вдруг какие-то join с поисками то пишите это в Builder.

Пример метода фильтрации и более сложных запросов.

<?php

declare(strict_types=1);

namespace App\EloquentBuilders;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

/**
 * @extends Builder<User>
 */
final class UserBuilder extends Builder
{
    public function whereActive(bool $isActive = true): self
    {
        return $this->where('is_active', $isActive);
    }

    public function filter(?UserFilterData $filter = null): self
    {
        if ($filter === null) {
            return $this;
        }

        if ($filter->name !== null) {
            $this->where('name', 'like', "%{$filter->name}%");
        }

        if ($filter->isActive !== null) {
            $this->where('is_active', $filter->isActive);
        }

        return $this;
    }

    public function withOrdersCount(): self
    {
        return $this->withCount('orders');
    }

    public function whereHasActiveSubscription(): self
    {
        return $this->whereHas('subscriptions',
            fn($q) => $q->where('active', true)
        );
    }
}

Главное правило - чтобы это всё было в одном месте.

Итог

Со временем я пришёл к тому, что держать запросы где попало - плохая идея. Сначала это кажется удобным, но по мере роста проекта превращается в хаос: одинаковые условия копируются, логика размазывается по коду, а разобраться “что происходит” становится всё сложнее.

Кастомные Query Builders для меня стали точкой, где вся работа с запросами наконец-то собралась в одном месте. В связке с Repository и UseCase это дало понятную структуру: где данные, где запросы, где бизнес-логика.

Мне это дало несколько вещей:

Я всегда знаю, где искать нужный запрос
Могу переиспользовать фильтры без копипаста
Код стал читаться проще и быстрее

Но важно понимать - это не серебряная пуля. Если проект маленький, можно спокойно жить и без этого. Такой подход начинает реально окупаться, когда проект растёт и в нём работает несколько человек.

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

Полезные ссылки:

Проект пример: https://github.com/palachX/laravel-usecase
Статья которую я прочитал в 2024: https://martinjoo.dev/build-your-own-laravel-query-builders
Статья перевод: https://laravel.su/p/kastomnye-query-builders-v-laravel
Статья по UseCase: https://habr.com/ru/articles/1012988/