Ar Php Laravel Laravel Package

Getting Started

Install via Composer and publish the config:

composer install still-code/ar-php-laravel
php artisan vendor:publish --tag=ar-php-config

The wrapper exposes the underlying ar-php classes through Laravel-friendly bindings. Look first at:

• config/ar-php.php — default charset, direction, and locale-ish settings consumed by the bindings.
• The package's Facade / service provider registration — this is where the ArPHP classes are bound into the container.
• The upstream ar-php library docs (this package is a thin Laravel adapter; most behavior lives upstream).

First use case — normalize and inspect an Arabic string:

use StillCode\ArPHP\Facades\ArPHP; // confirm the actual facade namespace from the package

$text = 'السلام عليكم';

$charset = ArPHP::charset();            // Arabic character utilities
$clean   = $charset->utf8Glyphs($text); // reshape/join glyphs for rendering edge cases

A more realistic day-one task is Hijri date conversion, since that's the most common reason Laravel apps pull this in:

use ArPHP\Date\ArabicDate;

$hijri = new ArabicDate();
echo $hijri->date('en', time());  // formatted Hijri output

If you're using the facade binding instead, check the package README for the exact method names it proxies — the wrapper does not reimplement the API, so signatures track ar-php upstream.

Implementation Patterns

Facade-first for shared state. The wrapper binds the ar-php classes so they resolve from the container. Prefer the facade inside controllers/services so you can swap implementations in tests; instantiate upstream classes directly only inside isolated value-object code.

Text pipeline pattern. Arabic processing is usually a chain, not a single call. A workable order:

1. Normalize (remove tashkeel/diacritics if you need matching behavior).
2. Reshape glyphs for display or comparison.
3. Convert digits (Arabic-Indic ↔ Latin) if you store/search by number.
4. Transliterate only at the presentation boundary, never in storage.

$charset = ArPHP::charset();
$normalized = $charset->stripTatweel($input);
$normalized = $charset->utf8Glyphs($normalized);

Wrap this in a small ArabicText service so it's testable and cacheable.

Date handling. Hijri conversion is the integration with the most surprising behavior. Treat it as a formatter, not a timezone system — pass Unix timestamps (or DateTime you convert to timestamp yourself) and format at the edge. Keep canonical dates in Gregorian UTC in your DB and convert on read.

Number formatting. Use the Arabic number utilities when rendering prices, counts, or pagination for Arabic-facing UI, rather than hand-rolling digit tables:

use ArPHP\Numbers\ArabicNumbers;

$n = new ArabicNumbers();
echo $n->int2str(1234); // Arabic word/numeral form

Search/index integration. For Arabic full-text search, run normalization before indexing, using the same normalizer in both directions. If you don't apply identical preprocessing on write and read, diacritics and glyph-form differences will silently break matches.

Blade presentation. Register a Blade directive or component that wraps transliteration/number formatting so views don't instantiate library classes directly.

Testing. Because this is a thin adapter, your tests should assert your normalization policy, not upstream behavior. Set a fixed charset in the config and assert stable output.

Gotchas and Tips

Character encoding drift. Almost every "wrong output" bug with ar-php traces back to mixing UTF-8 and Windows-1256. Confirm both your DB and response encoding are UTF-8, and set the charset in config/ar-php.php to match. The library will happily produce mojibake rather than error.

Glyph reshaping is for display only. utf8Glyphs()-style output is presentation form; storing or comparing reshaped strings against unshaped input will fail. Keep storage normalized, reshape at render time.

Hijri conversion is approximate. Calendar alignment differences mean you should not use this for legally binding dates. For user-facing Hijri labels it's fine; for compliance/scheduling logic, treat the output as a display value and pin an explicit reference date in tests.

Facade method names aren't invented by this package. If a method is missing, it hasn't been proxied — check whether the wrapper exposes the class you need, and if not, instantiate the upstream class directly. Don't file upstream bugs against this repo for library-level behavior.

Version 3.0.0 is a Laravel 13 / PHP 8.2+ release. Despite the major version bump, the substantive change is framework compatibility; the rest is CI/tooling bumps. Treat the upgrade as: verify PHP is ≥8.2, confirm the service provider registration still works on Laravel 13, and re-run your Arabic output tests to catch any charset default changes. If you're on Laravel 11/12, there's no functional gain in upgrading — but there's also no API churn suggested by the notes, so the risk is low.

Extension points are limited by design. Want to override normalization? Don't fork the package — bind your own service and call it, wrapping the library. Keeping the adapter at arm's length makes future major upgrades (like this one) trivial.

Debugging tip. When output looks correct in tinker but wrong in the browser, it's nearly always the HTTP header or a Blade escaping issue, not the library. Dump raw bytes with bin2hex() on both ends to isolate.