Download the PHP package mixudev/laravel-timezone without Composer

Laravel Timezone (mixudev/laravel-timezone)

Sistem resolusi dan konversi timezone otomatis, akurat, ringan, dan universal untuk aplikasi Laravel.

Dirancang dengan prinsip client-first, tanpa migrasi database, tanpa dependensi API eksternal, dan hemat beban server. Mendukung penuh aplikasi Monolith (Blade), REST API, SPA, Inertia.js (Vue/React), Livewire, Queue Worker, hingga Laravel Octane.

Fitur Utama

• Tanpa Perubahan Database: Tidak memerlukan migrasi atau penambahan kolom pada tabel database.
• Tanpa Request Eksternal: Tidak melakukan lookup Geo-IP atau panggilan API jaringan pada siklus HTTP standar.
• Deteksi Akurat Berbasis Browser: Menggunakan Intl.DateTimeFormat() pada sisi klien dan mengirimkannya secara efisien melalui HTTP header.
• Aman untuk Octane & Queue Worker: Menggunakan lifecycle container scoped untuk menjamin isolasi state antar-request tanpa risiko kebocoran memori.
• Operasi Tanggal Immutable: Mendukung Carbon, CarbonImmutable, DateTimeInterface, format string ISO-8601, serta timestamp Unix tanpa mengubah objek tanggal asli.
• Validasi IANA Ketat: Memvalidasi seluruh identifier timezone terhadap standar resmi IANA menggunakan cache in-memory berkecepatan tinggi.
• Integrasi Universal: Kompatibel langsung dengan Blade, Fetch API, Axios, Inertia.js, dan Livewire.

Instalasi

Pasang package melalui Composer:

Publikasikan konfigurasi, view Blade, dan aset JavaScript (opsional):

Atau publikasikan file tertentu saja:

Konfigurasi Ringkas

File konfigurasi config/timezone.php menyediakan pengaturan yang bersih dan siap pakai:

Urutan Resolusi Timezone

Resolver bekerja berdasarkan hierarki prioritas berurutan:

1. Explicit Override: Ditentukan langsung oleh developer melalui Timezone::in() atau Timezone::setExplicit().
2. Client HTTP Header: Header X-Timezone yang dikirim dari browser atau API client.
3. Client Cookie: Cookie timezone yang tersimpan pada browser pengguna.
4. Authenticated User: Provider timezone pengguna via Timezone::useUserProvider() atau atribut $user->timezone.
5. Session Storage: Data timezone pada session session('timezone') (jika diaktifkan).
6. IP Geolocation: Resolver kustom IP (jika diaktifkan).
7. Config Default: Nilai dari config('timezone.default') atau config('app.timezone').
8. UTC Fallback: UTC sebagai jaminan akhir server.

Integrasi Sisi Browser (JavaScript Client)

Muat skrip klien berukuran kurang dari 2KB tanpa dependensi eksternal di layout utama Anda (misal resources/views/layouts/app.blade.php):

Atau impor ke dalam file bundle JavaScript (Vite / Webpack):

Mekanisme Otomatis Script Klien:

1. Membaca timezone browser lokal menggunakan Intl.DateTimeFormat().resolvedOptions().timeZone.
2. Menyimpan timezone di localStorage dan cookie berstatus SameSite=Lax.
3. Menambahkan header X-Timezone pada setiap request fetch() dan axios.
4. Mendukung auto-header pada event visit Inertia.js dan melakukan hidrasi elemen DOM pada navigasi Livewire.

Penggunaan pada Blade

1. Komponen Progressive Enhancement

Gunakan komponen <x-local-time> untuk merender elemen HTML <time>. Komponen ini menampilkan teks server-side sebagai fallback dan langsung terhidrasi ke waktu lokal browser saat JavaScript aktif:

2. Direktif Blade

Global Helper

Facade API

Provider Timezone Pengguna

Jika aplikasi Anda menyimpan preferensi timezone pada model User, daftarkan provider kustom di dalam method boot() pada AppServiceProvider:

Middleware

Untuk memastikan timezone diinisialisasi sebelum kontroler atau middleware lain dijalankan:

Keamanan untuk Octane, Queue, dan CLI

Aplikasi dengan worker jangka panjang (Laravel Octane, RoadRunner, FrankenPHP, Swoole, dan Queue Worker) menggunakan memori yang persisten lintas request.

Package ini didaftarkan dengan scoped container lifecycle:

• Setiap request HTTP baru mendapatkan instance TimezoneManager yang terisolasi.
• Bebas dari kebocoran state antar-request.
• Untuk task pada Queue Worker atau Command CLI yang memproses data lintas zona waktu, gunakan method Timezone::in():

Perintah Artisan

Perintah CLI diagnostik dan pemeliharaan:

Dokumentasi Lengkap

Panduan mendalam tersedia pada folder docs/:

• 1. Panduan Instalasi dan Konfigurasi
• 2. Arsitektur dan Pipeline Resolver
• 3. Integrasi Blade dan Komponen View
• 4. Penggunaan Helper dan Facade API
• 5. Integrasi Frontend (JS, Axios, Inertia, Livewire)
• 6. Provider User dan Fallback Session
• 7. Panduan Octane, Queue Worker, dan CLI
• 8. Keamanan, Validasi, dan Optimasi Performa

Pengujian

Jalankan rangkaian unit & feature test:

Jalankan analisis statis PHPStan:

Lisensi

Lisensi MIT. Silakan merujuk ke file LICENSE untuk informasi lebih lanjut.