Ar Php Laravel Laravel Package

Technical Evaluation

Architecture fit. still-code/ar-php-laravel is a thin Laravel service-provider wrapper around the upstream Ar-PHP library (Arabic text processing: glyph shaping/joining, Arabic↔Hijri date conversion, number-to-Arabic-words, transliteration, Arabic-aware sorting and text normalisation). Architecturally it is a stateless, side-effect-free utility layer: no persistence, no queues, no external services, no bootstrapping beyond package auto-discovery and a publishable config file. That is a favourable profile for a TPM — it can be adopted as an application-level helper without touching domain models, infrastructure, or the deployment topology, and it can be removed again with a composer command plus a sweep of facade call sites.

Integration feasibility. Single composer require, auto-discovered provider, optional config publish. Release 3.0.0's only functional line item is "support for Laravel 13 with PHP ^8.2"; the remaining eight entries are Dependabot bumps to GitHub Actions used in CI (actions/checkout, ramsey/composer-install, fetch-metadata, laravel-pint-action, git-auto-commit-action). Those CI changes are invisible to consumers. The significant signal is the major version bump: the changelog does not state what was dropped, but the "PHP ^8.2" phrasing strongly implies the floor moved up (likely off PHP 8.1, and plausibly off older Laravel majors). The absence of a documented breaking-change section is itself a finding to raise with the maintainer before planning an upgrade.

Technical risk. Low-to-moderate, concentrated in four areas:

• Changelog opacity. A 3.0.0 tag with no "Breaking Changes" section means the compatibility surface must be inferred from composer.json constraints rather than trusted from the release notes. Treat the version bump as potentially breaking until proven otherwise.
• Output correctness over exceptions. This library's failure mode is wrong text, not a thrown error. Incorrect glyph joining, an off-by-one Hijri conversion, or a mis-spelled Arabic numeral in an invoice or contract will not surface in logs or health checks.
• Upstream bus factor. The wrapper is a small community package; the underlying Ar-PHP library is maintained by a single author. Neither carries a commercial SLA.
• Licensing. Ar-PHP has historically shipped under LGPL-3.0. For a commercially distributed Laravel product this is normally acceptable (dynamic use via Composer), but it should be confirmed by legal rather than assumed, and it is a genuine gating item for redistribution or on-premise appliance packaging.

Key questions for the maintainer / engineering spike.

1. Which Laravel and PHP versions does 3.0.0 drop versus 2.0.4? Please publish the composer.json constraint diff.
2. Is the 2.x line still receiving security and bug fixes, and for how long? This determines whether teams can defer the upgrade.
3. Are there any behavioural changes in shaping, Hijri conversion, or number spelling between 2.0.4 and 3.0.0 — or is this purely a support-matrix change?
4. What is the confirmed license of the transitive Ar-PHP dependency, and does it conflict with our distribution model?
5. Which PHP extensions are required or recommended (mbstring, iconv), and are they present in all target runtime images?

Integration Approach

Stack fit. Best fit is a Laravel 11/12 application on PHP 8.2+ that already needs Arabic-language output — invoices and receipts with spelled-out amounts, Hijri/Gregorian dual dating, Arabic search normalisation, or Arabic PDF rendering. Poor fit for teams whose only need is Arabic pluralisation or locale strings: Laravel's own translation layer plus intl handles that with fewer moving parts.

Overlap decision first. Before choosing this package, decide which component is the system of record for each concern. PHP's intl extension already offers NumberFormatter and IntlDateFormatter with Arabic locale support, and ICU covers Islamic calendars. Ar-PHP's differentiators are Arabic glyph shaping for non-Unicode-aware renderers, number-to-words in Arabic, and transliteration. Adopting both without an explicit boundary produces two sources of truth for the same formatted string. Publish a one-page decision matrix: shaping → this package; numerals/dates → pick one and forbid the other in code review.

Migration path.

1. Inventory. Grep for the facade alias and any injected class across the codebase. Produce a call-site list — this is also the test-coverage target list.
2. Characterisation tests. Capture current 2.0.4 output for a representative Arabic corpus: diacritised and undiacritised strings, mixed Arabic/Latin, RTL punctuation, edge dates (Hijri month boundaries, leap years, timezone-shifted midnight), and amounts across the 0–1,000,000 range. Store as golden files. This suite is the single highest-value artefact of the whole effort and it is reusable for every future bump.
3. Branch upgrade. Bump to 3.0.0 on a branch, republish the config, and diff golden files. Any change is either an intended fix (accept and version the expectation) or a regression (block).
4. Pilot. Land on one low-blast-radius service — an internal admin tool or a read-only reporting surface — for one release cycle before touching customer-facing documents.
5. Roll forward. Then schedule the Laravel 13 jump as a separate, later change. Do not couple "upgrade the Arabic helper" with "upgrade the framework"; 3.0.0 makes the second possible, not necessary.

Compatibility and sequencing. Resolve Composer constraints against the rest of the lock file early — a narrowed illuminate/support range can conflict with packages pinned to older Laravel majors and force an unplanned framework upgrade. Confirm the CI images ship mbstring and iconv. If any service must stay on PHP 8.1, pin it to 2.0.4 and record it as tracked technical debt with a dated review, rather than leaving the constraint implicit.

Operational Impact

Maintenance. Low ongoing effort; the cost is not in the code but in attention. This release illustrates the pattern: eight of nine entries are automated CI dependency bumps that carry zero runtime meaning, and the one substantive change is buried at the bottom. A TPM should not read these changelogs line-by-line — instead, watch the composer.json constraint diff and the upstream Ar-PHP repository, and treat the wrapper primarily as a version-pinning convenience.

Support. Community-maintained, single primary contributor on the wrapper and effectively a single author upstream. There is no vendor to escalate to. The pragmatic mitigation is a documented internal policy: we can vendor the upstream library and carry a local patch if needed, and we accept that a critical Arabic-text defect may require us to fix it ourselves. Budget for that possibility rather than assuming vendor response.

Scaling. Stateless and CPU-bound: shaping, transliteration, and number spelling are linear in string length with modest constants. Horizontal scaling is unproblematic — no shared state, no connection pools, no cache keys to invalidate. Two practical notes: (a) these operations are deterministic, so formatted output (Hijri date strings, spelled-out amounts, normalised search terms) is a natural cache target when generating documents at volume; (b) batch document generation — bulk invoices, PDF report runs — is where per-request cost actually accumulates, so benchmark against a realistic batch size rather than a single-request smoke test.

Failure modes to instrument.

• Silent wrongness. The dominant risk. Garbled joining, wrong Hijri day, or incorrect numeral appears in a customer-facing artefact with no error signal. Mitigation: golden-file regression suite in CI, plus a post-deploy spot check on a rendered document for any release touching this dependency.
• Missing extensions. Absent mbstring/iconv produces hard failures or degraded output; assert extension presence in the health check so the runtime image can't drift silently.
• Config drift. A published config file that is not refreshed after a major bump can produce behaviour that differs from the package defaults with no warning.
• Boundary dates. Hijri conversion around month and year boundaries, and any timezone offset crossing midnight, is the highest-density defect area. Test these explicitly rather than relying on happy-path samples.
• Facade/alias collision. Rare, but a duplicate alias registration fails at boot — cheap to detect, so catch it in the pilot rather than in the roll-forward.

Ramp-up. A Laravel developer is productive with this package in well under a day; the API surface is small and the facade is conventional. The real ramp-up is linguistic, not technical: acceptance criteria for shaping, numeral form (Eastern Arabic versus Western digits), and date convention cannot be judged by the implementing engineer. Secure a native Arabic-speaking reviewer for the golden-file corpus and for sign-off on any user-visible output. That reviewer is the critical-path resource, and the TPM should book their time before the pilot starts, not after the branch is ready.