gnireeg/laravel-timezoned

A lightweight Laravel package that provides a trait to automatically convert all date attributes of an Eloquent model from the database timezone to the user's timezone - and convert incoming user-provided dates back to the database timezone as well.

1.0.0 2025-11-23 02:13 UTC

Requires

• php: >=8.1
• illuminate/database: ^10.0 || ^11.0 || ^12.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0
• nesbot/carbon: ^2.0 || ^3.0

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• phpunit/phpunit: ^10.0 || ^11.0

MIT

• Joel Geering

README

A lightweight Laravel package that automatically converts Eloquent model date attributes between the database timezone and the user's timezone.

• DB → User timezone when reading attributes
• User → DB timezone when writing attributes

This ensures consistent and intuitive date handling across different user timezones.

Installation

composer require gnireeg/laravel-timezoned

Optionally publish the config:

php artisan vendor:publish --tag=config

Usage

use Gnireeg\LaravelTimezoned\HasTimezoneConversion;

class Event extends Model
{
    use HasTimezoneConversion;

    protected array $timezonedAttributes = ['starts_at', 'ends_at'];
}

Reading Attributes

// Automatically converted to user's timezone
$event->starts_at; // Returns Carbon in user's timezone

Writing Attributes

// Automatically converted to database timezone
$event->starts_at = '2025-03-10 15:00';
$event->save();

Raw Attribute Access

// Get the value in database timezone (bypass conversion)
$event->getRawAttribute('starts_at');

Configuration

The package config (config/timezoned.php) has two options:

Timezone Resolver

Determines the user's timezone. Receives the model instance as a parameter.

// Default: uses authenticated user's timezone
'timezone_resolver' => function ($model) {
    return auth()->user()?->timezone ?? 'UTC';
},

// Or use session
'timezone_resolver' => fn() => session('timezone', 'UTC'),

// Or request header
'timezone_resolver' => fn() => request()->header('X-Timezone', 'UTC'),

Database Timezone

The timezone your database stores dates in. Set to null to use config('app.timezone').

'database_timezone' => null, // Uses app.timezone
'database_timezone' => 'UTC', // Explicit UTC

How It Works

The trait overrides two Eloquent methods:

• getAttribute() - converts dates from database timezone to user's timezone
• setAttribute() - converts dates from user's timezone to database timezone

Both Carbon and CarbonImmutable instances are supported.

Requirements

• PHP >= 8.1
• Laravel 10, 11, or 12
• Carbon >= 2

Testing

composer test

License

MIT