Arabicable Laravel Package

Getting Started

1. composer require goodm4ven/laravel-arabicable and let Laravel's package discovery register the service provider. Publish config only if you need to change defaults: php artisan vendor:publish --tag="arabicable-config".
2. Read the README's method list first — the package is a thin, fluent wrapper around Laravel's Str/Stringable, so the fastest mental model is "everything Str does, plus Arabic-aware normalization and transliteration."
3. First use case to try: normalizing user input before comparison/search. Store Arabic names, city names, or product titles as typed, but normalize on the way in to comparisons:

use GoodM4ven\Arabicable\Facades\Arabic;

Arabic::normalize('أَحْمَد');   // strips tashkeel, unifies alef variants
Arabic::removeTashkeel('مُحَمَّد'); // مُحَمَّد -> محمد

4. Second use case: transliteration for URL slugs and search keys — Arabic::transliterate('رحمة').

Start with normalize() + removeTashkeel() on a single form request and verify against your own fixture list before rolling it out across models.

Implementation Patterns

Normalize once, store twice. The highest-value pattern is a normalized_name (or search_key) column populated via a model observer or a creating/saving hook. Keep the original for display; query against the normalized column so احمد, أحمد, and أَحْمَد all hit the same row.

protected static function booted(): void
{
    static::saving(function ($model) {
        $model->search_key = Arabic::normalize($model->name);
    });
}

Custom Eloquent cast for display-safe output. A cast that returns a normalized/cleaned string keeps controllers free of formatting logic, but only apply it to fields where the canonical form is what you actually want persisted — see the gotchas.

Slug generation. Wrap route-model binding or a slug column with transliteration plus Laravel's Str::slug() on the Latin output. This is where the transliteration API earns its keep, and where the v1.2.7 "rahmah" change is directly relevant.

Validation rules. Pair the package's Arabic-aware helpers with Laravel validation for form input (e.g. accepting Arabic-Indic digits from users but storing ASCII). Normalize in prepareForValidation() on the FormRequest so downstream code never sees variant characters.

Search/filter pipeline. For a LIKE-based search endpoint, normalize the search term and the column identically. If you need fuzzy matching, transliterate both sides and compare Latin forms — cheaper than pulling in a full-text engine for small datasets.

Numbers and digits. If the package exposes Arabic-Indic digit conversion, keep a single conversion point (a cast or a helper) rather than sprinkling str_replace calls — mixed digit systems in one column are a common source of broken sorting.

Testing seam. Build a small fixture array of [input, expected] pairs and run it as a data provider. This doubles as your regression suite when the package ships transliteration tweaks like the one in v1.2.7.

Gotchas and Tips

• Transliteration is not a canonical standard. Different schemes render ة as h, t, or nothing. v1.2.7 explicitly made the word "rahmah" resolve both ways — meaning output for words ending in ة can now differ from earlier versions. Never assert exact transliterated string equality in tests; assert membership in an accepted set, or pin the version.
• Don't mutate stored user data destructively. Normalizing on write is convenient but lossy — you lose the diacritics the user typed. Store raw + normalized, never overwrite the raw column.
• Normalization order matters. Strip tashkeel and tatweel before unifying alef/ya/ta-marbuta variants, or you'll leave orphaned combining marks. If the package exposes a single normalize() that does this for you, prefer it over chaining primitives by hand.
• Homoglyph and invisible-character bugs. Arabic text copied from Word or PDFs often carries zero-width joiners and RTL marks. Log the raw bytes (bin2hex) when a comparison inexplicably fails — it's usually an invisible character, not the package.
• Byte vs. character length. Anything measuring Arabic string length must be mb_*-based. If you use the package's length helpers, confirm they count grapheme clusters, not bytes, before enforcing max-length validation.
• Config quirks around locale/fallback. Transliteration settings typically live in the published config; after vendor:publish, config changes require php artisan config:clear in cached environments. Cache the config in production but remember the cache is stale after upgrades.
• Upgrade hygiene for patch releases. v1.2.6 → v1.2.7 is a behavior tweak, not a breaking change, but if you have snapshot tests around transliteration, expect diffs. Run your fixture suite before merging the bump.
• Extension points. Look for a transliteration map/character table in the config or a bindable contract in the container — that's the correct place to add domain-specific vocabulary (names, brand terms) rather than post-processing the package's output with str_replace.
• Where it stops. The package handles orthography, not morphology. For stemming, root extraction, or diacritization generation, you need a dedicated NLP library. Don't bend this package into that role.