Ar Php Laravel Laravel Package

Technical Evaluation

What actually shipped in 3.0.0. The changelog is dominated by eight Dependabot PRs, seven of which touch GitHub Actions only (actions/checkout 4→6, ramsey/composer-install 3→4, dependabot/fetch-metadata 2.3→3.0, laravel-pint-action 2.5→2.6, git-auto-commit-action 5→7). Exactly one change is runtime-relevant: PR #56 adds Laravel 13 support with a PHP ^8.2 floor. There are no new features, no new configuration surface, and no documented deprecations.

Architecture fit. still-code/ar-php-laravel is a thin ServiceProvider + Facade wrapper around the upstream Ar-PHP library. That is a favourable shape: it is a leaf dependency with a small surface area, no persistence layer, no queue or event integration, and no bootstrapping side effects beyond container binding. It will slot into an existing Laravel application without imposing architectural constraints — no migrations, no middleware, no route registration. The decision is therefore low-consequence architecturally and reduces to a build-constraint question rather than a design question. It is appropriate where the product needs Arabic text normalisation (transliteration, spelling/hijri dates, Arabic-Indic numerals, Quranic text handling) and would be overkill for a team that only needs intl-based NumberFormatter and IntlDateFormatter.

Integration feasibility. Straightforward: composer require still-code/ar-php-laravel, package discovery registers the provider, an optional config publish exposes defaults, and usage is via the facade in application or domain services. The real feasibility work is verifying the composer solver against our matrix. A major-version bump accompanying a Laravel 13 addition almost certainly means the Laravel constraint floor moved and older Laravel/PHP combinations were dropped — the changelog does not say so explicitly.

Technical risk. Ranked:

The CI action bumps (checkout 4→6, composer-install 3→4) carry no runtime risk but do indicate the release pipeline is being kept current, which is a mildly positive maintenance signal.

Key questions. (1) What exactly does 3.0.0's composer.json require and conflict with — which Laravel and PHP versions were dropped relative to 2.0.4? (2) Is the 3.0.0 tag a semver-major solely because of the constraint change, and is a 2.x patch line still maintained for teams on Laravel 10/11? (3) Does the wrapper pin an upstream Ar-PHP version range, and what is that range's security posture? (4) Is there a documented deprecation path or upgrade guide, or is the diff the documentation? (5) Who is the maintainer of record, and is there a stated support policy for Laravel release windows?

Integration Approach

Stack fit. Native Laravel package — ServiceProvider, Facade, publishable config — so it fits any standard Laravel 10/11/12/13 application with autodiscovery enabled. No assumptions about front-end, queue driver, database, or hosting topology. Only meaningful compatibility axis beyond Laravel is PHP ^8.2, which aligns with Laravel 12/13's own baselines and with PHP's supported-branch policy.

Migration path. Treat this as a build-matrix migration, not a code migration. Steps: (1) diff the 2.0.4 and 3.0.0 composer.json to extract the exact illuminate/* and php constraints; (2) if upgrading an app already on Laravel 12/13 and PHP ≥ 8.2, this should be a no-op composer update — expect no source changes; (3) if the app is on Laravel 10/11 or PHP 8.1, do not move to 3.0.0; remain on the 2.0.x line and confirm with the maintainer that it still receives fixes; (4) run the application's Arabic-language acceptance tests, not just the package's own suite, because the facade's output shape is what the product consumes.

Compatibility. Two contracts to verify: the Facade binding name and optional config keys must be unchanged (likely, given no feature work), and the upstream Ar-PHP API must be unchanged behind the wrapper. Verify both by running the package's existing tests plus a smoke test on one representative call per feature the product uses. If the product only touches one or two capabilities, assert those explicitly rather than relying on full-suite green.

Sequencing. Do not bundle this with other dependencies. Order: PHP runtime upgrade to 8.2+ on all environments (including CI images and local dev) → framework upgrade if applicable → this package → application acceptance tests. Upgrade in a single isolated PR so that if Arabic output regresses, the bisect is trivial. Pin exact versions in composer.lock and merge to staging before main; the constraint shift is the kind of change that fails at install time in one environment and not another if images are inconsistent.

Effort. For an app already on PHP 8.2+ and Laravel 12/13: well under a day, mostly verification. For an app behind on either: gate it — schedule alongside the framework upgrade, not before.

Operational Impact

Maintenance. Expect a low-touch dependency. The release history is maintenance-shaped — automated dependency PRs plus one contributor change — which means low churn but also low responsiveness if we hit a defect. Set a quarterly review rather than continuous tracking, and pin to a minor range with a lockfile so an unattended composer update cannot drag us across a major boundary.

Support. Support comes from the upstream Ar-PHP project and the Laravel community, not a commercial vendor. Anything Arabic-language-specific that breaks is our problem to diagnose or fix. Budget for one engineer with PHP competence but not necessarily Arabic fluency, plus a native-Arabic reviewer available on demand for output validation. If Arabic localisation is on a regulated or revenue-critical path, consider whether an internal fork or a direct dependency on upstream Ar-PHP is preferable — the wrapper is thin enough that owning it is not onerous.

Scaling. Negligible runtime contribution: pure PHP string and date transformation, no I/O, no network, no state. Scaling concerns are CPU-bound and only materialise if the package is used inside hot loops — e.g. formatting thousands of records per request during batch export or report generation. In that case memoise results or precompute at write time rather than at render time. No scaling constraint at the infrastructure layer.

Failure modes. (1) Install-time: composer constraint conflict after a framework upgrade — loud, caught in CI. (2) Startup: missing mbstring or wrong default encoding — Arabic text arrives corrupted or normalisation silently no-ops; this is the most dangerous class because it is quiet. (3) Output: Hijri date conversions near month boundaries, or numeral formatting diverging from product expectation; caught only by acceptance tests with known-good fixtures. (4) Config: an unpublished config file meaning defaults apply where the product assumed tuned behaviour. (5) Upstream: composer update pulls a new Ar-PHP patch with changed transliteration output, breaking stored keys or search indexes derived from that output. Mitigate by pinning upstream through the lockfile and by treating any output-derived persisted data as needing a backfill plan.

Ramp-up. Low. A developer can be productive against the facade in a few hours using the README; there is no learning curve around lifecycle, container semantics, or configuration. The genuine ramp-up cost is domain knowledge — which Arabic normalisation, calendar, and numeral conventions the product must honour — and that knowledge lives with the localisation owner, not with this package. Document the specific capabilities the product depends on at integration time so future upgrade decisions can be assessed against a short, concrete list instead of a vague "we use the Arabic library."

Recommendation. Adopt 3.0.0 only where PHP is already 8.2+ and Laravel is 12/13; otherwise hold on 2.0.x pending confirmation of that line's support. Treat the upgrade as a low-risk, verification-heavy housekeeping change, and gate it on reading the composer constraints and re-running Arabic acceptance tests — the changelog alone is not sufficient evidence that nothing else moved.