Визначення спеціалізованого Query Builder у Laravel 12 із використанням PHP-атрибутів

Випуск Laravel 12.19 представив атрибут UseEloquentBuilder, який дозволяє визначити кастомний запитний будівельник для вашої моделі. Хоча моделі зазвичай не потребують кастомного запитного будівельника, ви можете скористатися цією можливістю, щоб спростити моделі, зосередити області в одному місці та включити методи кастомного запитного будівельника, які ви будете повторно використовувати у вашому додатку.

До виходу Laravel 12.19, щоб перевизначити запитний будівельник моделі, потрібно було переопределити метод newEloquentBuilder() і повернути екземпляр вашого кастомного запитного будівельника.

public function newEloquentBuilder($query)
{
    return new CustomBuilder($query);
}

Коли ви визначаєте кастомний запитний будівельник, ваш клас Builder повинен реалізовувати контракт Builder. Найпростіший спосіб — наслідувати клас Builder Laravel:

namespace App\Builder;
 
use Illuminate\Database\Eloquent\Builder;
 
class PostBuilder extends Builder
{
    public function wherePublished()
    {
        $this->whereNotNull('published_at');
 
        return $this;
    }
 
    /* ... */
}

Ось як можна налаштувати свій кастомний екземпляр будівельника, використовуючи атрибут UseEloquentBuilder замість переопределення методу newEloquentBuilder() у базовій моделі:

namespace App\Models;
 
use App\Builder\PostBuilder;
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
use Illuminate\Database\Eloquent\Model;
 
#[UseEloquentBuilder(PostBuilder::class)]
class Post extends Model
{
    /* ... */
}
 
// Використання
Post::query()->wherePublished()->get();

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

# Дізнайтеся більше

Щоб дізнатися більше про UseEloquentBuilder, ознайомтеся з нотатками про випуск у Laravel 12.19 та Pull Request #56025 для деталей реалізації. Ви також можете дізнатися більше про запитний будівельник бази даних Laravel у документації.