README

Smart Arabic compound name detection, parsing, shortening, and normalization for PHP.

Handles 200+ compound Arabic name patterns including:

• Prefix compounds: عبد الله، أبو بكر، ابن خلدون، ذو الفقار
• Suffix compounds: صلاح الدين، نصر الله، سيف الإسلام، قمر الزمان
• Stuck compounds: عبدالله → عبد الله

Why ArabicName?

Arabic names frequently contain compound constructs — two or more words that form a single logical name. Naive splitting breaks these names:

"عبد الله محمد أبو عليم"
  ❌ Naive:  first="عبد"  last="عليم"
  ✅ Smart:  first="عبد الله"  last="أبو عليم"

"نور الدين أحمد صلاح الدين"
  ❌ Naive:  first="نور"  last="الدين"
  ✅ Smart:  first="نور الدين"  last="صلاح الدين"

ArabicName solves this by understanding compound name patterns and treating them as single logical units.

Installation

composer require osamaqazan/arabic-name

Quick Start

use OsamaQazan\ArabicName\ArabicName;

// Shorten a name (first + last logical name)
ArabicName::shorten("عبد الله محمد أحمد صلاح الدين");
// → "عبد الله صلاح الدين"

// Parse into parts
$name = ArabicName::parse("عبد الله محمد أحمد صلاح الدين");
$name->first();    // "عبد الله"
$name->middle();   // ["محمد", "أحمد"]
$name->last();     // "صلاح الدين"
$name->short();    // "عبد الله صلاح الدين"
$name->initials(); // "ع.ص"

// Detect compound names
ArabicName::isCompound("عبد الله");     // true
ArabicName::isCompound("صلاح الدين");   // true
ArabicName::isCompound("محمد");          // false

// Normalize (fix spacing, remove tashkeel)
ArabicName::normalize("عبدالله");        // "عبد الله"
ArabicName::normalize("عَبْدُ اللَّهِ"); // "عبد الله"

// Detect gender
ArabicName::gender("عبد الله محمد");  // "male"
ArabicName::gender("فاطمة أحمد");     // "female"

// Transliterate to Latin
ArabicName::transliterate("عبد الله محمد"); // "Abdullah Mohammed"
ArabicName::transliterate("صلاح الدين");    // "Salahuddin"

// Compare names
ArabicName::areSame("عبدالله", "عبد الله");   // true
ArabicName::areSame("فاطمة", "فاطمه");        // true
ArabicName::similar("أحمد", "احمد");           // 1.0

Features

API Reference

ArabicName::parse(string $name): NameResult

Parses a full name into logical parts.

$r = ArabicName::parse("عبد الله محمد أحمد أبو عليم");
$r->first();     // "عبد الله"
$r->middle();    // ["محمد", "أحمد"]
$r->last();      // "أبو عليم"
$r->full();      // "عبد الله محمد أحمد أبو عليم"
$r->short();     // "عبد الله أبو عليم"
$r->initials();  // "ع.أ"
$r->gender();    // "male"
$r->greeting();  // "السيد عبد الله" (auto-detects السيد/السيدة)
$r->toArray();   // ['first' => ..., 'middle' => ..., 'last' => ..., ...]

ArabicName::shorten(string $name): string

Shortens a full name to first + last logical name.

ArabicName::shorten("محمد أحمد خالد أبو عليم");  // "محمد أبو عليم"
ArabicName::shorten("سيف الدين أحمد أبو البصل"); // "سيف الدين أبو البصل"
ArabicName::shorten("محمد أحمد نصر الله");        // "محمد نصر الله"
ArabicName::shorten("عبدالله محمد خالد");          // "عبد الله خالد"

ArabicName::isCompound(string $name): bool

Checks if a name string is a compound name.

ArabicName::isCompound("عبد الله");    // true
ArabicName::isCompound("أبو بكر");     // true
ArabicName::isCompound("صلاح الدين");  // true
ArabicName::isCompound("محمد");         // false
ArabicName::isCompound("أحمد خالد");   // false

ArabicName::normalize(string $name): string

Normalizes Arabic name text.

ArabicName::normalize("عبدالله");           // "عبد الله"
ArabicName::normalize("عبدالرحمن");         // "عبد الرحمن"
ArabicName::normalize("أبوالقاسم");          // "أبو القاسم"
ArabicName::normalize("عَبْدُ اللَّهِ");    // "عبد الله"
ArabicName::normalize("  محمد   أحمد  ");  // "محمد أحمد"

ArabicName::gender(string $name): string

Detect the likely gender of a name. Returns 'male', 'female', or 'unknown'.

ArabicName::gender("محمد أحمد");      // "male"
ArabicName::gender("عبد الله");       // "male"
ArabicName::gender("فاطمة");          // "female"
ArabicName::gender("أم كلثوم");       // "female"

ArabicName::isMale("خالد محمد");      // true
ArabicName::isFemale("مريم أحمد");    // true

ArabicName::transliterate(string $name, string $standard = 'common'): string

Convert Arabic names to Latin script.

// Common standard (widely recognized spellings)
ArabicName::transliterate("محمد");              // "Mohammed"
ArabicName::transliterate("عبد الله");          // "Abdullah"
ArabicName::transliterate("صلاح الدين");        // "Salahuddin"
ArabicName::transliterate("عبد الله محمد أحمد"); // "Abdullah Mohammed Ahmed"
ArabicName::transliterate("ابن خلدون");         // "Ibn Khaldun"

// Formal standard (systematic transliteration)
ArabicName::transliterate("محمد", "formal");     // "Mhmd"

ArabicName::similar(string $name1, string $name2): float

Calculate similarity between two Arabic names (0.0 - 1.0).

ArabicName::similar("أحمد", "احمد");              // 1.0 (hamza variation)
ArabicName::similar("فاطمة", "فاطمه");             // 1.0 (taa marbuta vs haa)
ArabicName::similar("مصطفى", "مصطفي");             // 1.0 (alef maqsura vs yaa)
ArabicName::similar("عبدالله", "عبد الله");         // 1.0 (stuck compound)
ArabicName::similar("محمد أحمد", "محمد أحمد خالد"); // ~0.7

ArabicName::areSame(string $name1, string $name2, float $threshold = 0.9): bool

Check if two Arabic names are effectively the same.

ArabicName::areSame("عبدالله", "عبد الله");  // true
ArabicName::areSame("فاطمة", "فاطمه");       // true
ArabicName::areSame("محمد", "فاطمة");         // false

Helper Methods

ArabicName::firstName("عبد الله محمد أحمد");   // "عبد الله"
ArabicName::lastName("محمد أحمد أبو عليم");    // "أبو عليم"
ArabicName::middleNames("عبد الله محمد القاضي"); // ["محمد"]
ArabicName::initials("عبد الله محمد صلاح الدين"); // "ع.ص"

Custom Patterns

Register additional compound patterns at runtime:

ArabicName::addPrefixes('شيخ');      // "شيخ محمد" → compound
ArabicName::addSuffixes('الأول');    // "محمد الأول" → compound
ArabicName::addPrefixes(['سيدي', 'مولاي']); // Multiple at once

Laravel Integration

ArabicName includes built-in Laravel support with auto-discovery.

Blade Directives

<h1>@arabicShorten($user->name)</h1>
<p>@arabicFirst($user->name)</p>
<p>@arabicInitials($user->name)</p>
<p>@arabicNormalize($user->name)</p>
<p>@arabicTransliterate($user->name)</p>

Validation Rules

use OsamaQazan\ArabicName\Laravel\Rules\ArabicCompoundName;
use OsamaQazan\ArabicName\Laravel\Rules\ArabicNameRule;

// Validate compound name
$request->validate([
    'name' => ['required', new ArabicCompoundName],
]);

// Validate Arabic name with minimum parts
$request->validate([
    'name' => ['required', new ArabicNameRule(minParts: 3)],
]);

// Using string rules
$request->validate([
    'name' => 'required|arabic_name',
    'family_name' => 'required|arabic_compound',
]);

Facade

use OsamaQazan\ArabicName\Laravel\Facades\ArabicName;

ArabicName::shorten($name);
ArabicName::parse($name)->first();

Supported Compound Patterns

Prefixes (bind forward)

Suffixes (bind backward)

Requirements

• PHP >= 7.4
• mbstring extension
• Laravel >= 8.0 (optional, for Laravel integration)

Testing

composer install
composer test

Static Analysis

composer analyse

Contributing

Please see CONTRIBUTING.md for details.

Changelog

Please see CHANGELOG.md for recent changes.

License

MIT License - see LICENSE file.

Author

Eng.Osama Qazan — osamaqazan89@gmail.com

بالعربي

مكتبة PHP ذكية للتعامل مع الأسماء العربية المركبة. تكتشف وتعالج أكثر من 200 نمط تركيب في الأسماء العربية.

المشكلة

عند اختصار الأسماء العربية، التقسيم البسيط يكسر الأسماء المركبة:

"عبد الله محمد أبو عليم"
  ❌ الطريقة الخاطئة: "عبد عليم"
  ✅ الطريقة الصحيحة: "عبد الله أبو عليم"

"نور الدين أحمد صلاح الدين"
  ❌ الطريقة الخاطئة: "نور الدين"
  ✅ الطريقة الصحيحة: "نور الدين صلاح الدين"

المميزات

• تحليل الأسماء: تقسيم الاسم الكامل إلى أول ووسط وأخير مع احترام التركيب
• اختصار الأسماء: استخراج الاسم الأول والأخير بذكاء
• تطبيع الكتابة: إزالة التشكيل وإصلاح المسافات
• كشف الجنس: تحديد جنس صاحب الاسم (ذكر/أنثى)
• التحويل للاتينية: تحويل الأسماء العربية إلى حروف لاتينية
• مقارنة الأسماء: مقارنة الأسماء مع تجاهل الاختلافات الكتابية
• دعم Laravel: مزود خدمة وموجهات Blade وقواعد تحقق

الاستخدام

use OsamaQazan\ArabicName\ArabicName;

// اختصار الاسم
ArabicName::shorten("عبد الله محمد أحمد صلاح الدين");
// ← "عبد الله صلاح الدين"

// تقسيم الاسم
$name = ArabicName::parse("عبد الله محمد أحمد صلاح الدين");
$name->first();    // "عبد الله"
$name->middle();   // ["محمد", "أحمد"]
$name->last();     // "صلاح الدين"

// كشف التركيب
ArabicName::isCompound("صلاح الدين"); // true

// تطبيع الكتابة
ArabicName::normalize("عبدالله"); // "عبد الله"

// كشف الجنس
ArabicName::gender("محمد");   // "male"
ArabicName::gender("فاطمة");  // "female"

// التحويل للاتينية
ArabicName::transliterate("عبد الله"); // "Abdullah"

// مقارنة الأسماء
ArabicName::areSame("فاطمة", "فاطمه"); // true