erag/laravel-datetime-format

Format Eloquent date and datetime values consistently across models, Blade, and APIs.

v1.0.0 2026-05-27 20:45 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• illuminate/database: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0
• nesbot/carbon: ^2.72|^3.0

Requires (Dev)

• laravel/pint: ^1.13
• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• pestphp/pest: ^2.0|^3.0|^4.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0|^4.0

MIT

• Er Amit Gupta

• date
• format
• laravel
• datetime
• carbon
• cast

README

A powerful Laravel package for centralized and consistent date/time formatting across your application. Automatically format Eloquent model dates, API responses, Blade output, and Carbon instances without repeating manual ->format(...) calls everywhere.

Key Features 🔥

• 👤 Automatic Eloquent model datetime formatting
• 🧠 Centralized datetime formatter service
• 🧩 Custom cast support with FormattedDateTimeCast
• 🎨 Blade directive support via @dateTimeFormat(...)
• ⏱️ Carbon macro support using toConfiguredFormat()
• 📦 API resource helper macros
• 🌍 Timezone and locale support
• 🧱 Laravel 10, 11, 12, and 13 support
• ✅ PHP 8.2+ support

Install 🚀

composer require erag/laravel-datetime-format
php artisan erag:install-datetime-format

Config ⚙️

Published file: config/datetime-format.php

return [
    'format' => 'd-m-Y H:i:s',
    'timezone' => env('APP_TIMEZONE', 'UTC'),
    'locale' => env('APP_LOCALE', 'en'),
    'null_value' => null,
    'auto_apply' => true,
    'date_format' => 'd-m-Y',
    'time_format' => 'H:i:s',
];

What timezone and locale do 🌍

• timezone: defines the timezone used for formatted output.
  Example: the input can be UTC, but output can be converted to Asia/Kolkata.
• locale: sets Carbon’s language/context before formatting.
  This is useful when using month/day names, such as 28 May 2026 or localized month labels.

Quick Understanding (Before vs After) 👀

Without package (common output):

{
  "created_at": "2026-05-27T15:39:13.000000Z"
}

With package + trait:

{
  "created_at": "27-05-2026 21:09:13"
}

Usage

1) Model Auto Format (Recommended) 👤

use LaravelDateTimeFormat\Concerns\HasFormattedDateTimes;

class User extends Model
{
    use HasFormattedDateTimes;
}

Controller:

return response()->json([
    'user' => User::first(),
]);

Response example:

{
  "user": {
    "id": 1,
    "name": "Kaden Herring",
    "email": "[e-mail]",
    "created_at": "27-05-2026 21:09:13",
    "updated_at": "27-05-2026 21:09:13"
  }
}

2) Custom Cast (When you only want specific columns formatted) 🧩

use LaravelDateTimeFormat\Casts\FormattedDateTimeCast;

protected function casts(): array
{
    return [
        'email_verified_at' => FormattedDateTimeCast::class,
    ];
}

Example output:

{
  "email_verified_at": "28-05-2026 15:45:30"
}

3) Blade Directive 🎨

@dateTimeFormat($user->created_at)

Rendered output:

27-05-2026 21:09:13

4) Formatter Service 🧠

use LaravelDateTimeFormat\Formatters\DateTimeFormatter;

public function show(DateTimeFormatter $formatter)
{
    return [
        'datetime' => $formatter->format('2026-05-28 10:15:30'),
        'date' => $formatter->formatDate('2026-05-28 10:15:30'),
        'time' => $formatter->formatTime('2026-05-28 10:15:30'),
    ];
}

Response example:

{
  "datetime": "28-05-2026 15:45:30",
  "date": "28-05-2026",
  "time": "15:45:30"
}

5) Facade Usage 🛠️

use DateFormat;

DateFormat::format(now());
DateFormat::format(now(), 'd/m/Y H:i');

6) Carbon Macro ⏱️

Carbon::now()->toConfiguredFormat();
Carbon::now()->toConfiguredFormat('d M Y, h:i A');

7) API Resource Macro 📦

return [
    'created_at' => $this->formatDateTime($this->created_at),
];

Resource output example:

{
  "created_at": "27-05-2026 21:09:13"
}

Real Demo Style Response ✅

If you want to see mixed output (service + blade + model):

{
  "source_utc": "2026-05-28 10:15:30 UTC",
  "formatter_service": "28-05-2026 15:45:30",
  "date_only": "2026-05-28",
  "time_only": "15:45:30",
  "facade": "28/05/2026 15:45",
  "carbon_macro": "28 May 2026, 03:45 PM",
  "blade_directive": "28-05-2026 15:45:30",
  "user_date": {
    "data": [
      {
        "created_at": "27-05-2026 21:09:13",
        "updated_at": "27-05-2026 21:09:13"
      }
    ]
  }
}

Service Provider Discovery 🔍

The package uses Composer auto-discovery, so manual service provider registration is usually not required.

Practical Integration Flow

1. Publish the config.
2. Set global format/timezone.
3. Add HasFormattedDateTimes to your models.
4. Use directive/macro in Blade and API resources.
5. Keep controllers lean and let the package handle formatting.