README

حزمة احترافية ومتقدمة للبحث الذكي والمرن في النصوص العربية لتطبيقات لارافيل.
A high-performance, flexible Arabic search and text-matching library for Laravel with Eloquent macros, model traits, diacritics removal, and multi-database support.

🌟 المميزات الرئيسية | Features

مطابقة مرنة لجميع أشكال الحروف العربية (Interchangeable Characters):
- الألف: [أ، إ، آ، ا، ٱ]
- التاء المربوطة والهاء: [ة، ه، ۀ]
- الياء والألف المقصورة والنبرة: [ي، ى، ئ، ی]
- الواو المهموزة والواو: [ؤ، و]
- الكاف العربية والفارسية: [ك، ک]
إزالة التشكيل والكشيدة تلقائياً (Tashkeel & Tatweel Removal):
- تجريد الحركات (فتحة، ضمة، كسرة، سكون، تنوين، شدة...).
- إزالة الكشيدة (ـ) (Tatweel/Kashida).
دعم مدمج للـ Eloquent Query Builder:
- User::whereArabic('name', 'احمد')->get();
- User::orWhereArabic('bio', 'مهندس')->get();
Trait جاهز للـ Models (SearchableArabic):
- بحث في حقول متعددة وعلاقات Model (category.name) بسطر واحد:
- Post::searchArabic($keyword)->paginate();
ماكرو للـ Collections:
- $collection->whereArabic('title', 'فاطمه');
دعم متعدد لقواعد البيانات (Cross-Database Compatibility):
- MySQL / MariaDB: عبر مشغل REGEXP.
- PostgreSQL: عبر مشغل POSIX ~*.
- SQLite: تسجيل تلقائي لدالة REGEXP في PDO لضمان عمل الاختبارات (Unit Tests) بسلاسة فائقة دون أي أخطاء!
تطبيع النصوص السريع (Normalization):
- دالة ArabicSearch::normalize($text) لتجهيز الأعمدة المفهرسة (Indexed Shadow Columns).
ميزة تجاهل "الـ" التعريف اختيارياً (Ignore "ال" Prefix):
- مطابقة "كتاب" مع "الكتاب" والعكس.

📦 التثبيت | Installation

يمكنك تثبيت الحزمة عبر Composer:

composer require shammaa/laravel-arabic-search

إذا كنت تستخدم ميزة الـ Package Discovery في Laravel، فسيتم تسجيل الـ ServiceProvider والـ Facade تلقائياً.

نشر ملف الإعدادات (اختياري) | Publish Config (Optional)

php artisan vendor:publish --tag="arabic-search-config"

سينتج الملف config/arabic-search.php.

🚀 طريقة الاستخدام | Usage

1. الاستعلام المباشر عبر Eloquent | Direct Eloquent Query

تستطيع استخدام الماكرو whereArabic أو orWhereArabic مباشرة على أي استعلام:

use App\Models\User;

// البحث عن "احمد" سيطابق: أحمد، احمد، إحمد، آحمد
$users = User::whereArabic('name', 'احمد')->get();

// دمج شروط متعددة
$products = Product::where('status', 'active')
    ->whereArabic('name', 'مؤسسة') // يطابق مؤسسة وموسسه
    ->orWhereArabic('description', 'هندسة')
    ->paginate(15);

2. استخدام الـ Trait في الموديل | Using Model Trait

أضف الـ Trait SearchableArabic إلى الموديل وحدد الحقول القابلة للبحث:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Shammaa\LaravelArabicSearch\Traits\SearchableArabic;

class Article extends Model
{
    use SearchableArabic;

    // الحقول المشمولة في البحث (تدعم العلاقات أيضاً!)
    protected array $searchableArabic = [
        'title',
        'content',
        'category.name', // بحث في جدول التصنيفات المرتبط
    ];
}

ثم نفّذ البحث بكل بساطة في الـ Controller:

public function search(Request $request)
{
    $query = $request->input('q');

    return Article::searchArabic($query)->paginate(20);
}

يمكنك أيضاً تمرير حقول محددة أثناء الاستعلام:

Article::searchArabic('حلب', ['title', 'summary'])->get();

3. استخدام الـ Collection Macro

إذا كانت لديك مجموعة بيانات في الذاكرة (Collection):

$collection = collect([
    ['id' => 1, 'name' => 'أحمد إبراهيم'],
    ['id' => 2, 'name' => 'محمد علي'],
    ['id' => 3, 'name' => 'فاطمة الزهراء'],
]);

// سيعيد السطر الأول
$results = $collection->whereArabic('name', 'ابراهيم');

// سيعيد السطر الثالث (يطابق التاء المربوطة والهاء)
$fatima = $collection->whereArabic('name', 'فاطمه');

4. استخدام الـ Facade مباشرة | Facade Helpers

use Shammaa\LaravelArabicSearch\Facades\ArabicSearch;

// 1. توليد Regex نمطي مرن
$regex = ArabicSearch::toRegex('أحمد');
// النتيجة: [أإآاٱ]حمد

// 2. فحص مطابقة نص في الذاكرة
$matched = ArabicSearch::matches('مُؤَسَّسَةُ النُّورِ', 'موسسه النور');
// true

// 3. تطبيع نص كامل (مفيد لإنشاء أعمدة مفهرسة في قاعدة البيانات)
$clean = ArabicSearch::normalize('إِعْلَانٌ عَنْ وَظِيفَةٍ');
// النتيجة: اعلان عن وظيفه

// 4. إزالة التشكيل أو الكشيدة
$text = ArabicSearch::stripTashkeel('سَلَامٌ عَلَيْكُمْ'); // سلام عليكم
$clean = ArabicSearch::stripTatweel('مـحـمـد');           // محمد

5. خيارات وأوضاع البحث المتقدمة | Search Modes & Options

تستطيع تمرير مصفوفة خيارات للدوال:

// مطابقة مطابقة تامة (Exact Match)
User::whereArabic('username', 'احمد', 'and', ['mode' => 'exact'])->first();

// يبدأ بـ (Starts with)
User::whereArabic('name', 'عبد', 'and', ['mode' => 'starts_with'])->get();

// تجاهل "الـ" التعريف (البحث عن 'كتاب' يجد 'الكتاب' والعكس)
Product::whereArabic('title', 'كتاب', 'and', ['ignore_al_prefix' => true])->get();

⚙️ ملف الإعدادات | Configuration

محتوى ملف config/arabic-search.php:

return [
    // نمط البحث الافتراضي: 'contains', 'exact', 'starts_with', 'ends_with'
    'mode' => 'contains',

    // قواعد مطابقة الحروف المتبادلة
    'interchangeable' => [
        'alef' => true,         // أ, إ, آ, ا, ٱ
        'taa_marbouta' => true, // ة, ه, ۀ
        'yaa' => true,          // ي, ى, ئ, ی
        'waw' => true,          // ؤ, و
        'kaf' => true,          // ك, ک
    ],

    // إزالة الحركات والكشيدة
    'strip_tashkeel' => true,
    'strip_tatweel' => true,

    // التعامل المرن مع المسافات المتعددة
    'flexible_spaces' => true,

    // تجاهل "الـ" التعريف
    'ignore_al_prefix' => false,
];

🧪 تشغيل الاختبارات | Running Tests

تم بناء الحزمة وتغطيتها بالكامل باختبارات Unit و Feature باستخدام Orchestra Testbench:

composer test

🤝 المساهمة | Contributing

المساهمات مرحب بها دائماً! لا تتردد في فتح Issue أو إرسال Pull Request.

📄 الترخيص | License

هذه الحزمة مرخصة تحت رخصة MIT License. المؤلف: شادي شماع (Shadi Shammaa).

shammaa / laravel-arabic-search

Package info

Security

Statistics