Метод timestampTz

Метод timestampTz применяется в миграциях Laravel для создания колонки типа TIMESTAMP WITH TIME ZONE. Этот метод позволяет хранить дату и время вместе с информацией о часовом поясе. В отличие от метода timestamp, который хранит время без учёта часового пояса, timestampTz автоматически преобразует время в часовой пояс базы данных при сохранении и обратно при извлечении. Метод может принимать параметр точности (precision) для указания количества дробных знаков в секундах.

Синтаксис

<?php
	Schema::table('table_name', function (Blueprint $table) {
		$table->timestampTz($column, $precision = 0);
	});
?>

Пример с миграцией

Давайте создадим миграцию для таблицы 'events' с колонкой 'started_at', которая будет хранить временную метку с часовым поясом:

<?php
	use Illuminate\Database\Migrations\Migration;
	use Illuminate\Database\Schema\Blueprint;
	use Illuminate\Support\Facades\Schema;

	return new class extends Migration
	{
		public function up(): void
		{
			Schema::create('events', function (Blueprint $table) {
				$table->id();
				$table->string('name');
				$table->timestampTz('started_at');
				$table->timestamps();
			});
		}

		public function down(): void
		{
			Schema::dropIfExists('events');
		}
	};
?>

Результат выполнения миграции:

"Table events created successfully"

Пример с указанием точности

Давайте создадим миграцию с колонкой, которая будет хранить время с точностью до миллисекунд:

<?php
	use Illuminate\Database\Migrations\Migration;
	use Illuminate\Database\Schema\Blueprint;
	use Illuminate\Support\Facades\Schema;

	return new class extends Migration
	{
		public function up(): void
		{
			Schema::create('measurements', function (Blueprint $table) {
				$table->id();
				$table->string('device');
				$table->timestampTz('measured_at', 3);
				$table->timestamps();
			});
		}

		public function down(): void
		{
			Schema::dropIfExists('measurements');
		}
	};
?>

Результат выполнения миграции:

"Table measurements created successfully"

Пример работы с моделью

Давайте создадим модель Event и сохраним запись с временной меткой:

<?php
	namespace App\Models;

	use Illuminate\Database\Eloquent\Model;

	class Event extends Model
	{
		protected $fillable = ['name', 'started_at'];
		
		protected $casts = [
			'started_at' => 'datetime',
		];
	}
?>

<?php
	namespace App\Http\Controllers;

	use App\Models\Event;
	use Carbon\Carbon;

	class EventController extends Controller
	{
		public function store()
		{
			$event = Event::create([
				'name' => 'Conference 2026',
				'started_at' => Carbon::now('Europe/Moscow'),
			]);
			
			echo $event->id;
		}
	}
?>

Результат выполнения кода:

"1"

Пример извлечения данных

Давайте получим все события и выведем их время с учётом часового пояса:

<?php
	namespace App\Http\Controllers;

	use App\Models\Event;

	class EventController extends Controller
	{
		public function index()
		{
			$events = Event::all();
			
			foreach ($events as $event) {
				echo $event->name . ': ' . $event->started_at->toDateTimeString();
			}
		}
	}
?>

Результат выполнения кода:

"Conference 2026: 2026-01-01 10:00:00"

Пример с использованием nullable

Давайте создадим колонку, которая может содержать значение NULL:

<?php
	use Illuminate\Database\Migrations\Migration;
	use Illuminate\Database\Schema\Blueprint;
	use Illuminate\Support\Facades\Schema;

	return new class extends Migration
	{
		public function up(): void
		{
			Schema::create('schedules', function (Blueprint $table) {
				$table->id();
				$table->string('task');
				$table->timestampTz('completed_at')->nullable();
				$table->timestamps();
			});
		}

		public function down(): void
		{
			Schema::dropIfExists('schedules');
		}
	};
?>

Результат выполнения миграции:

"Table schedules created successfully"

Смотрите также

метод timestamp,
который создаёт колонку с временной меткой без часового пояса
метод dateTimeTz,
который создаёт колонку с датой и временем с часовым поясом
метод date,
который создаёт колонку только для хранения даты
метод time,
который создаёт колонку только для хранения времени