Arabicdatetime Laravel Package

Getting Started

Install the package with Composer:

composer require maherelgamil/arabicdatetime

On Laravel 5.5+ service provider auto-discovery should register it. If you are on an older Laravel version, add the provider and alias manually in config/app.php:

'providers' => [
    Maherelgamil\Arabicdatetime\ArabicdatetimeServiceProvider::class,
],

'aliases' => [
    'ArabicDateTime' => Maherelgamil\Arabicdatetime\Facades\ArabicDateTime::class,
],

Look first at the package README and vendor/maherelgamil/arabicdatetime/src to confirm the exact facade method names for your installed version. The package is small enough to inspect directly, which is useful because its API is intentionally narrow.

The first day-to-day use case is formatting a stored timestamp for display:

use Maherelgamil\Arabicdatetime\Facades\ArabicDateTime;

echo ArabicDateTime::format('l، j F Y', $post->created_at);
// Example output: الأحد، 1 يناير 2023

If your installed version exposes date() instead of format(), the call shape is usually the same; use the method listed in the facade/source. Treat the package as a presentation helper: keep your Eloquent date attributes as normal Carbon instances and only convert to Arabic text at the edge, such as Blade views, API resources, invoices, and notifications.

Implementation Patterns

Format at the presentation layer, not in the database. Keep created_at, published_at, etc. as standard Laravel/Carbon dates. Add Arabic formatting in Blade, API resources, or dedicated view models.

{{ ArabicDateTime::format('l، j F Y', $post->published_at) }}

Use API resources for localized output. Avoid appending Arabic date attributes to every model by default; it bloats JSON and makes the model responsible for presentation.

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'published_at' => $this->published_at?->toIso8601String(),
            'published_at_arabic' => $this->published_at
                ? ArabicDateTime::format('l، j F Y', $this->published_at)
                : null,
        ];
    }
}

Convert timezone before formatting. Store UTC, then convert to the user’s timezone before handing the date to the package.

$local = $order->created_at
    ->copy()
    ->setTimezone($user->timezone ?? config('app.timezone'));

echo ArabicDateTime::format('l، j F Y h:i A', $local);

Set locale and timezone explicitly in queued jobs and mailables. Queue workers may not inherit the same locale or timezone as the HTTP request.

app()->setLocale('ar');
date_default_timezone_set($user->timezone);

$message->line(ArabicDateTime::format('l، j F Y', $invoice->due_at));

Use a Blade component or helper to avoid repetition. If you format dates in many views, wrap the package call in a small component so the format string lives in one place.

{{-- resources/views/components/arabic-date.blade.php --}}
<time datetime="{{ $date->toIso8601String() }}">
    {{ ArabicDateTime::format($format ?? 'l، j F Y', $date) }}
</time>

Keep sorting and filtering on the raw timestamp. Arabic month names and localized numerals are for display only. Do not sort or filter by the formatted Arabic string; query the underlying created_at column.

Use the package for display, Carbon for arithmetic. Date math, comparisons, intervals, and “is past” checks should stay on Carbon. Convert to Arabic text only when rendering.

$isOverdue = $invoice->due_at->isPast();

$label = ArabicDateTime::format('l، j F Y', $invoice->due_at);

Test with frozen time. Arabic output is easy to assert once the timestamp is fixed.

Carbon::setTestNow('2023-01-01 12:00:00');

$this->get('/posts')
    ->assertSee('الأحد');

Gotchas and Tips

Check Laravel compatibility before adopting it broadly. The last release was in 2021, so verify that the package installs and auto-discovers correctly on your Laravel version. If you are on a newer Laravel release, inspect composer.json constraints and be prepared to fork or register the provider manually.

Confirm the facade method and namespace casing. Small packages sometimes expose format(), date(), or a helper function depending on version. Read the facade class in vendor/maherelgamil/arabicdatetime/src rather than guessing from examples online.

Arabic-Indic digits are not guaranteed. Depending on config/version, the package may render 1 or ١. If your UI or tests expect a specific numeral style, verify it and normalize explicitly.

UTF-8 everywhere. Arabic output requires UTF-8 end to end: database collation such as utf8mb4_unicode_ci, response charset, mail templates, and PDF fonts. The package formats text; it does not fix encoding or RTL layout.

PDFs need more than formatting. DomPDF and similar tools need an Arabic-capable font and RTL CSS (direction: rtl; text-align: right;). Formatting the string is only half the job.

Timezone drift causes off-by-one-day dates. Set config/app.php timezone correctly, store UTC, and convert before formatting. This is especially visible for dates near midnight.

Do not assume Hijri conversion. The package description emphasizes Arabic characters; whether it converts Gregorian dates to Hijri depends on the version/configuration. If you need Hijri dates for official or religious purposes, verify the conversion method and accuracy rather than assuming Umm al-Qura behavior.

After config changes, clear caches. Run php artisan config:clear and, if needed, php artisan cache:clear after changing timezone, locale, or package config.

Consider Carbon localization as a fallback. Laravel’s Carbon integration can often do the same job:

$post->created_at->locale('ar')->translatedFormat('l، j F Y');

If the package becomes a maintenance burden, this is usually the lowest-friction replacement. The package is best treated as a small convenience wrapper, not a full Arabic localization layer.