Laravel 12.19: استخدام Attributes تنظّم Query Builder

في Laravel 12.19، دلوقتي تقدر تستخدم Attribute اسمه #[UseEloquentBuilder] علشان تحدد Query Builder خاص بالموديل، من غير ما تبقى محتاج تعمل override للـ newEloquentBuilder() — ده بيخلي الكود أوضح وأسهل في الصيانة.

ليه تستخدم "Query Builder" خاص؟

• خلي الموديلات مركزة — ركّز على العلاقات، مش على استعلامات معقدة.
• جمّع المنطق القابل لإعادة الاستخدام زي wherePublished() في مكان واحد.
• ارتّب الكود أكتر وتجميع الاستعلامات يخليه أوضح.

الطريقة القديمة

// app/Models/Article.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Builders\ArticleBuilder;

class Article extends Model {
  public function newEloquentBuilder($query) {
    return new ArticleBuilder($query);
  }
}

الطريقة الجديدة

// app/Models/Article.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Builders\ArticleBuilder;
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;

#[UseEloquentBuilder(ArticleBuilder::class)]
class Article extends Model {
  // مش محتاجين Override
}

مثال على Builder

// app/Builders/ArticleBuilder.php
namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

class ArticleBuilder extends Builder {
  public function whereActive(): static {
    return $this->where('is_active', true);
  }

  public function recent(int $days = 7): static {
    return $this->whereDate('created_at', '>=', now()->subDays($days));
  }

  public function byCategory(string $slug): static {
    return $this->whereHas('category', fn($q) => $q->where('slug', $slug));
  }
}

إزاي تستخدمه

$articles = Article::query()
  ->whereActive()
  ->recent(14)
  ->byCategory('tech')
  ->orderByDesc('published_at')
  ->paginate(10);

نصائح احترافية

1. ✅ استخدمه بس لما الكود بتاعك تتكرر فيه الاستعلامات.
2. ⚙️ خلي الأسامي مرنة، زي recent(int $days).
3. 🧪 اكتب tests لكل دالة في الـ Builder.
4. 📘 ممكن تخلطها مع Global Scopes لو حابب تنظف الكود أكتر.

الميزة دي جات ضمن إصدار Laravel 12.19 اللي كمان ضمّت: نوع Casting جديد AsFluent، Middleware للـ Job اسمه FailOnException، ودوال assertions جديدة للـ redirect back.