مقارنة بين Scopes + Traits × UseEloquentBuilder في Laravel

يوليو 13, 2025

في Laravel، بنحتاج دايمًا نكتب استعلامات شبه بعض في أكتر من مكان. Laravel بتوفر طريقتين أساسيين نقدر نستخدمهم علشان نرتّب الاستعلامات دي: Scopes + Traits، أو Custom Builder باستخدام #[UseEloquentBuilder].

🔹 أولًا: استخدام Scopes مع Traits

الـ Scope هو مجرد دالة في الموديل بتبدأ بكلمة scope، وبتساعدك تعيد استخدام شروط الاستعلام. أما Trait فهي مكان بتجمع فيه أكتر من Scope علشان تقدر تستخدمهم في موديلات مختلفة بسهولة.

مثال عملي على Trait فيها Scopes:

// app/Traits/ArticleScopes.php
namespace App\Traits;

trait ArticleScopes {
    public function scopePublished($query) {
        return $query->where('is_published', true);
    }

    public function scopeRecent($query, $days = 7) {
        return $query->whereDate('created_at', '>=', now()->subDays($days));
    }

    public function scopeByAuthor($query, $authorId) {
        return $query->where('author_id', $authorId);
    }
}

واستخدامها في الموديل:

// app/Models/Article.php
use App\Traits\ArticleScopes;

class Article extends Model {
    use ArticleScopes;
}

واستخدامها في الكود:

$articles = Article::published()->recent(30)->byAuthor(5)->paginate(10);

✅ مميزات الطريقة دي:

  • سهلة وسريعة في المشاريع الصغيرة والمتوسطة.
  • تقدر تعيد استخدامها في موديلات تانية بسهولة.
  • مش محتاج تكتب كود كتير.

❌ العيوب:

  • الاستعلامات ممكن تنتشر في كذا Trait، وده يخلي تتبعها أصعب.
  • الـ IDE مش دايمًا بيديك مساعدة قوية (Autocomplete ضعيف).
  • صعب تختبر كل Scope لوحده بسهولة.

🔹 ثانيًا: استخدام #[UseEloquentBuilder] في Laravel 12.19

الميزة دي بتخليك تعرف Builder class خاص بالموديل، وده بيخلي كل منطق الاستعلام يتجمع في مكان واحد. Laravel بقت تدعم ده رسميًا عن طريق Attribute اسمه #[UseEloquentBuilder].

مثال عملي:

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

use Illuminate\Database\Eloquent\Builder;

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

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

    public function byAuthor(int $authorId): static {
        return $this->where('author_id', $authorId);
    }
}
// app/Models/Article.php
namespace App\Models;

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

#[UseEloquentBuilder(ArticleBuilder::class)]
class Article extends Model {
    // مش محتاج تعمل override لـ newEloquentBuilder
}
// الاستخدام:
$articles = Article::query()->published()->recent(15)->byAuthor(2)->get();

✅ مميزات Custom Builder:

  • كل الاستعلامات متجمعة في Class واحد – سهل التتبع والتنظيم.
  • Autocomplete ممتاز في IDE.
  • سهل تكتب عليه اختبارات (unit tests).
  • الأسامي مش مرتبطة بـ scope – تقدر تسمي بحرية.

❌ العيوب:

  • محتاج تكتب كود أكتر.
  • ممكن يكون Overkill في مشاريع صغيرة.

📊 مقارنة سريعة:

الميزة Scopes + Traits #[UseEloquentBuilder]
سهولة البدء ✅ سهلة جدًا 🔸 تحتاج تعريف Builder
تنظيم الكود 🔸 متوسط ✅ عالي جدًا
الدعم في IDE 🔸 محدود ✅ قوي
الاختبارات 🔸 أصعب شوية ✅ أسهل في العزل
مناسب للمشاريع الكبيرة 🔸 قابل للتشابك ✅ الأنسب

🧠 الخلاصة:

لو مشروعك بسيط، وبتحتاج شرطين أو تلاتة بيتكرروا – Scopes + Traits هتنجز وتكفيك. لكن لو بتشتغل على مشروع كبير، وفيه استعلامات معقدة أو متكررة كتير – الـ Custom Builder باستخدام #[UseEloquentBuilder] هيكون أنسب بكتير من حيث التنظيم والمرونة والتوسّع.

المدونة

حلل مشروع Laravel بـ Introspect

يوليو 01, 2025

حلل كود Laravel باستخدام Laravel Introspect لو بتعمل Refactor كبير أو بتبني أدوات Dev‪، Laravel Introspect بيسمحلك تستعلم عن الكود: فيوز، مودلز، رو...

دليل للأنيميشن المتحركة بالسكّول بس بـ CSS

يونيو 26, 2025

دليل للأنيميشن المتحركة بالسكّول بـ CSS دلوقتي تقدر تربط الأنيميشن بتاعتك بـ السكّول من غير جافاسكريبت — كله CSS بحت. 1. التلات مكونات بتوع...

إتقان CSS الحديثة: قوة if()، Popover Hints، والتنسيقات الذكية

يوليو 16, 2025

🌐 إتقان CSS الحديثة: قوة if()، Popover Hints، والتنسيقات الذكية CSS دلوقتي بقت أذكى بكتير. دالة if()، وميزة popover="hint"، وازاي نكتب تنسيقات متج...

الدليل الكامل لتحديثات ECMAScript 2025 للمطورين

يوليو 06, 2025

📘 شرح تفصيلي لتحديثات ECMAScript 2025 جميع مميزات ECMAScript 2025، مع أمثلة عملية وفهم ليه الميزة دي مهمة لأي مبرمج واجهة أمامية. ١. مجموعات مسما...

إتقان التكرار غير المتزامن في JavaScript باستخدام Array.fromAsync()

يوليو 27, 2025

🔍 ما هي Array.fromAsync() بالضبط؟ Array.fromAsync() هي دالة static من كائن Array، شبيهة بالدالة Array.from()، لكن الفرق الجوهري هو أن Array.fromAs...

استدعاء ملفات JavaScript عند الحاجة فقط لتحسين أداء موقعك

يوليو 24, 2025

🧠 يعني إيه Dynamic Import؟ الديناميـك إمبورت ببساطة هو إنك تحمّل ملف أو موديول JavaScript "وقت الحاجة بس" مش من أول الصفحة. الميزة دي بتقلل حجم ال...