PHP DateTime ve DateTimeImmutable ile Tarih ve Saat İşlemleri

DateTime ile DateTimeImmutable farkı

Kılavuz DateTimeImmutable sınıfını, DateTime ile aynı davranan ama modify() gibi değiştirme metotları çağrıldığında yeni nesne döndüren sınıf olarak tanımlar. Bu küçük fark, nesnelerin PHP'de referans semantiğiyle taşınması nedeniyle büyük sonuçlar doğurur:

<?php
$tz = new DateTimeZone('Europe/Istanbul');

$baslangic = new DateTime('2026-11-07 09:00', $tz);
$bitis = $baslangic;              // aynı nesne, kopya değil
$bitis->modify('+2 hours');
echo $baslangic->format('H:i'), "\n";   // çıktı: 11:00 (başlangıç da değişti!)

$bas = new DateTimeImmutable('2026-11-07 09:00', $tz);
$son = $bas->modify('+2 hours');  // yeni nesne döner
echo $bas->format('H:i'), ' - ', $son->format('H:i'), "\n";   // çıktı: 09:00 - 11:00

$bitis = $baslangic ataması bir kopya oluşturmadı; iki değişken de aynı nesneyi gösteriyor. DateTime üzerinde modify() çağrıldığında nesnenin kendisi değiştiği için başlangıç saati de 11:00 oldu. Bu tür hatalar özellikle bir tarihi fonksiyona parametre olarak verdiğinizde ortaya çıkar: fonksiyon içinde yapılan bir hesap, çağıran tarafın değişkenini sessizce bozar. DateTimeImmutable ile her değişiklik yeni bir nesne üretir ve özgün değer korunur. Nesnelerin referans davranışı ve clone için PHP clone ve nesne karşılaştırma yazısına bakabilirsiniz.

İki sınıf arasında geçiş yapmanız gerekirse DateTimeImmutable::createFromMutable() ve DateTimeImmutable::createFromInterface() metotları vardır. Fonksiyon parametrelerinde her iki türü de kabul etmek istiyorsanız ortak arayüz olan DateTimeInterface tipini yazabilirsiniz.

Varsayılan saat dilimi ve format()

Saat dilimi verilmeden oluşturulan her tarih nesnesi varsayılan saat dilimini kullanır. Kılavuza göre date_default_timezone_get() önce date_default_timezone_set() ile ayarlanan değere, sonra date.timezone yapılandırma ayarına bakar; ikisi de yoksa UTC döndürür. Bu örneklerin çalıştırıldığı ortamda yapılandırma dosyası olmadığı için varsayılan UTC'dir. Sunucuda bu ayarın nasıl yapıldığı için PHP hosting rehberine bakabilirsiniz; kod tarafında ise saat dilimini her nesneye açıkça vermek, ayarın sunucudan sunucuya değişmesinden etkilenmemenin en güvenli yoludur.

<?php
echo date_default_timezone_get(), "\n";   // php.ini yoksa: UTC

$an = new DateTimeImmutable('2026-11-07 14:05:09', new DateTimeZone('Europe/Istanbul'));
echo $an->format('d.m.Y H:i'), "\n";
echo $an->format('Y-m-d\TH:i:sP'), "\n";
echo $an->format(DATE_ATOM), "\n";
echo $an->format('l, j F Y'), "\n";
echo $an->format('N W t L'), "\n";
echo $an->format('U'), "\n";
echo $an->format('\S\a\a\t: G'), "\n";

UTC
07.11.2026 14:05
2026-11-07T14:05:09+03:00
2026-11-07T14:05:09+03:00
Saturday, 7 November 2026
6 45 30 0
1794049509
Saat: 14

format() her karakteri bir tarih bileşeniyle değiştirir; tanımadığı karakterleri olduğu gibi bırakır ve tanıdığı bir karakteri harf olarak yazdırmak isterseniz önüne ters eğik çizgi koyarsınız (örnekteki \S\a\a\t). Kılavuz bu metodun yerel ayarları kullanmadığını, tüm çıktının İngilizce olduğunu özellikle belirtir; l ve F bu yüzden Saturday ve November yazdı. DATE_ATOM gibi hazır sabitler ISO 8601 ve RFC biçimlerini tek adımda üretir.

Saat dilimleri arasında dönüşüm

Bir DateTimeImmutable nesnesi mutlak bir anı ve o anın hangi saat diliminde ifade edildiğini birlikte saklar. setTimezone() anı değiştirmez, yalnızca aynı anı başka bir saat diliminde ifade eden yeni bir nesne döndürür:

<?php
$istanbul = new DateTimeZone('Europe/Istanbul');
$utc = new DateTimeZone('UTC');

$toplanti = new DateTimeImmutable('2026-11-07 15:00', $istanbul);
echo $toplanti->format('Y-m-d H:i T P'), "\n";
echo $toplanti->setTimezone($utc)->format('Y-m-d H:i T P'), "\n";
echo $toplanti->setTimezone(new DateTimeZone('America/New_York'))->format('Y-m-d H:i T P'), "\n";

echo $istanbul->getName(), ' ', $istanbul->getOffset($toplanti), "\n";
echo $toplanti->getTimestamp() === $toplanti->setTimezone($utc)->getTimestamp() ? "aynı an\n" : "farklı\n";

2026-11-07 15:00 +03 +03:00
2026-11-07 12:00 UTC +00:00
2026-11-07 07:00 EST -05:00
Europe/Istanbul 10800
aynı an

Üç satır da aynı anı gösteriyor, bu yüzden Unix zaman damgaları eşit. getOffset() saat diliminin verilen andaki UTC farkını saniye cinsinden döndürür; 10800 saniye üç saate karşılık gelir. Kalıcı bir kayıt tutarken genellikle tercih edilen yol, tarihi UTC olarak ya da UTC farkını içeren ISO 8601 biçiminde (DATE_ATOM) saklamak ve kullanıcıya gösterirken yerel saat dilimine çevirmektir. Geçersiz bir saat dilimi adı verirseniz, aşağıda göreceğiniz gibi PHP 8.3'ten beri bir istisna fırlatılır; geçerli adların listesini DateTimeZone::listIdentifiers() verir.

modify, add ve sub ile tarih aritmetiği

modify() İngilizce göreli ifadeler kabul eder (+1 day, next monday, last day of next month). add() ve sub() ise bir DateInterval nesnesi alır. Aşağıdaki örnek 31 Ocak'tan başlayarak bu yöntemlerin bazı şaşırtıcı sonuçlarını gösteriyor:

<?php
$tz = new DateTimeZone('Europe/Istanbul');
$d = new DateTimeImmutable('2026-01-31 10:00', $tz);

echo $d->modify('+1 day')->format('Y-m-d'), "\n";
echo $d->modify('+1 month')->format('Y-m-d'), "\n";
echo $d->modify('last day of next month')->format('Y-m-d'), "\n";
echo $d->modify('first day of next month')->format('Y-m-d'), "\n";
echo $d->modify('next monday')->format('Y-m-d H:i'), "\n";
echo $d->modify('tomorrow')->format('Y-m-d H:i'), "\n";

echo $d->add(new DateInterval('P1Y2M3DT4H'))->format('Y-m-d H:i'), "\n";
echo $d->sub(new DateInterval('PT90M'))->format('Y-m-d H:i'), "\n";

2026-02-01
2026-03-03
2026-02-28
2026-02-01
2026-02-02 00:00
2026-02-01 00:00
2027-04-03 14:00
2026-01-31 08:30

İkinci satır en sık karşılaşılan tuzaktır: 31 Ocak'a bir ay eklemek 31 Şubat'ı verir, böyle bir gün olmadığı için tarih taşar ve 3 Mart olur. Kılavuz bunu ayrıca belgeler ve artık yılda sonucun 2 Mart olacağını belirtir. Ayın son gününü istiyorsanız last day of next month, ilk gününü istiyorsanız first day of next month ifadesini kullanın. next monday ve tomorrow ifadelerinin saati gece yarısına sıfırladığına da dikkat edin; saat bilgisini korumak istiyorsanız +1 day tercih edin.

DateInterval kurucusu ISO 8601 süre biçimini kullanır: P ile başlar, ardından yıl (Y), ay (M), gün (D) gelir; saat bileşenleri T harfinden sonra yazılır (H, M, S). M harfinin T öncesinde ay, sonrasında dakika anlamına geldiğini unutmayın. Birimler büyükten küçüğe sıralanmalıdır: P1Y4D geçerli, P4D1Y geçersizdir. Hafta için W kullanılabilir ve PHP 8.0'dan beri D ile birleştirilebilir.

diff ile iki tarih arasındaki fark

diff() iki tarih arasındaki farkı bir DateInterval nesnesi olarak döndürür. Bu nesnenin y, m, d, h, i, s özellikleri farkı bileşenlerine ayırır; days ise toplam tam gün sayısını verir. Sonuç DateInterval::format() ile yazdırılır; buradaki biçim karakterleri % ile başlar ve tarih format() karakterlerinden farklıdır.

<?php
$tz = new DateTimeZone('Europe/Istanbul');
$kayit = new DateTimeImmutable('2024-02-15 08:00', $tz);
$bugun = new DateTimeImmutable('2026-11-07 17:30', $tz);

$fark = $kayit->diff($bugun);
echo $fark->format('%y yıl %m ay %d gün %h saat %i dakika'), "\n";
echo 'Toplam gün: ', $fark->days, "\n";
echo $fark->format('%R%a gün'), "\n";

$ters = $bugun->diff($kayit);
echo $ters->format('%R%a gün'), ' invert=', $ters->invert, "\n";
echo $bugun->diff($kayit, true)->format('%R%a gün'), "\n";

var_dump($kayit < $bugun);
var_dump($kayit == new DateTimeImmutable('2024-02-15 05:00', new DateTimeZone('UTC')));

2 yıl 8 ay 23 gün 9 saat 30 dakika
Toplam gün: 996
+996 gün
-996 gün invert=1
+996 gün
bool(true)
bool(true)

Burada üç noktaya dikkat edin. %d yalnızca aylardan arta kalan günleri verir; toplam gün sayısı için %a ya da days özelliğini kullanmalısınız. Kılavuzun örneğinde 1 Ocak ile 1 Şubat arasındaki fark için %a 31, %m ay %d gün ise "1 ay 0 gün" verir. İkincisi, tarihleri ters sırada verdiğinizde invert özelliği 1 olur ve %R eksi işareti yazar; ikinci parametre true verilirse sonuç her zaman pozitiftir. Üçüncüsü, tarih nesneleri <, > ve == ile doğrudan karşılaştırılabilir ve karşılaştırma saat dilimini hesaba katar: İstanbul saatiyle 08:00 ile UTC 05:00 aynı andır. DateInterval nesneleri ise kılavuza göre karşılaştırılamaz.

Kılavuz bir ayrıntıyı daha belirtir: diff() sonucu, başlangıç nesnesinden hedefe ulaşmak için uygulanacak saat farkıdır ve yaz saati geçişlerini hesaba katar. Mutlak süre (örneğin tam saat sayısı) hesaplamak istiyorsanız iki nesneyi önce UTC'ye çevirmeniz önerilir.

DatePeriod ile tekrarlayan tarihler

DatePeriod bir başlangıç tarihi, bir aralık ve bir bitiş tarihi ya da tekrar sayısıyla oluşturulur ve foreach ile dolaşılabilir. Haftalık rapor tarihleri, aylık fatura günleri veya bir takvim görünümündeki günler için kullanışlıdır.

<?php
$tz = new DateTimeZone('Europe/Istanbul');
$bas = new DateTimeImmutable('2026-11-02', $tz);
$son = new DateTimeImmutable('2026-11-30', $tz);

$haftalik = new DatePeriod($bas, new DateInterval('P1W'), $son);
foreach ($haftalik as $gun) {
    echo $gun->format('d.m.Y D'), "\n";
}

echo "--\n";
$uc = new DatePeriod($bas, new DateInterval('P1D'), 2, DatePeriod::EXCLUDE_START_DATE);
foreach ($uc as $gun) {
    echo $gun->format('Y-m-d'), "\n";
}

02.11.2026 Mon
09.11.2026 Mon
16.11.2026 Mon
23.11.2026 Mon
--
2026-11-03
2026-11-04

Birinci dönem 2 Kasım'dan başlayıp haftalık ilerliyor ve 30 Kasım da bir pazartesi olduğu halde listeye girmiyor, çünkü bitiş tarihi varsayılan olarak dahil edilmez. Bitişi dahil etmek için PHP 8.2 ile gelen DatePeriod::INCLUDE_END_DATE seçeneğini verirsiniz. İkinci dönem tekrar sayısıyla oluşturuldu ve EXCLUDE_START_DATE başlangıç gününü dışarıda bıraktı. Kılavuz bu konuda ince bir ayrıntıyı belirtir: tekrar sayısı verildiğinde dönen tarih sayısı, başlangıç tarihi dışlanmadıysa bir fazladır. PHP 8.4 ile ISO 8601 metni alan eski kurucu biçimi deprecated oldu; onun yerine DatePeriod::createFromISO8601String() kullanılır.

createFromFormat ile metinden tarih ayrıştırmak

Kurucu ve modify() birçok metin biçimini otomatik tanır, ama bu esneklik kullanıcı girdisinde risklidir: 07.11.2026 gibi bir değerin hangi sırayla yorumlanacağını kendiniz belirlemek istersiniz. createFromFormat() metni verdiğiniz biçime göre ayrıştırır ve uymazsa false döndürür:

<?php
$tz = new DateTimeZone('Europe/Istanbul');

$d = DateTimeImmutable::createFromFormat('d.m.Y H:i', '07.11.2026 14:30', $tz);
echo $d->format('Y-m-d H:i:s'), "\n";

$sadeceTarih = DateTimeImmutable::createFromFormat('!d.m.Y', '07.11.2026', $tz);
echo $sadeceTarih->format('Y-m-d H:i:s'), "\n";

$hatali = DateTimeImmutable::createFromFormat('d.m.Y', '2026-11-07', $tz);
var_dump($hatali);

$tasan = DateTimeImmutable::createFromFormat('d.m.Y', '31.02.2026', $tz);
echo $tasan->format('Y-m-d'), "\n";
print_r(DateTimeImmutable::getLastErrors());

2026-11-07 14:30:00
2026-11-07 00:00:00
bool(false)
2026-03-03
Array
(
    [warning_count] => 1
    [warnings] => Array
        (
            [10] => The parsed date was invalid
        )

    [error_count] => 0
    [errors] => Array
        (
        )

)

Biçimde saat bulunmadığında kılavuza göre eksik bileşenler o anki sistem saatiyle doldurulur. Bu, iki tarihi karşılaştırırken beklenmedik saniye farklarına yol açar. Biçimin başına ! koymak tüm alanları Unix başlangıcına (gece yarısı) sıfırlar; örnekteki ikinci satır bu yüzden 00:00:00 gösteriyor. Biçime uymayan metin false döndürdü, bu yüzden dönüş değerini her zaman kontrol edin.

Son iki satır en ince tuzağı gösteriyor: 31 Şubat biçime uyduğu için ayrıştırma başarılı oldu, ama tarih taşarak 3 Mart'a dönüştü. Kılavuz bu tür taşmaları yakalamak için DateTimeImmutable::getLastErrors() fonksiyonunu önerir; dönen dizideki warning_count değeri sıfırdan büyükse "The parsed date was invalid" uyarısı vardır. Bir doğum tarihi veya randevu gibi kullanıcı girdisini doğrularken hem false dönüşünü hem de uyarı sayısını kontrol etmeniz gerekir. Genel girdi doğrulama için PHP filter_var ile veri doğrulama yazısına da bakabilirsiniz.

Tarih istisnaları (PHP 8.3)

PHP 8.3 sürüm notlarına göre tarih eklentisi, uyarılar ve genel istisnalar yerine kendine özgü istisna ve hata sınıfları kullanmaya başladı. DateException dalı altında DateMalformedStringException, DateInvalidTimeZoneException, DateMalformedIntervalStringException, DateMalformedPeriodStringException ve DateInvalidOperationException bulunur; DateError dalı ise Error sınıfından türer.

<?php
try {
    $d = new DateTimeImmutable('2026-13-45 99:99');
} catch (DateMalformedStringException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

try {
    $yarin = (new DateTimeImmutable('2026-11-07'))->modify('yarın');
} catch (DateMalformedStringException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

try {
    new DateTimeZone('Turkey/Ankara');
} catch (DateInvalidTimeZoneException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

try {
    new DateInterval('5 gün');
} catch (DateMalformedIntervalStringException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

DateMalformedStringException: Failed to parse time string (2026-13-45 99:99) at position 6 (3): Unexpected character
DateMalformedStringException: DateTimeImmutable::modify(): Failed to parse time string (yarın) at position 0 (y): The timezone could not be found in the database
DateInvalidTimeZoneException: DateTimeZone::__construct(): Unknown or bad timezone (Turkey/Ankara)
DateMalformedIntervalStringException: Unknown or bad format (5 gün)

modify() ve DateInterval sayfalarının sürüm tablolarına göre bu davranış 8.3'te değişti: modify() eskiden geçersiz metinde false döndürüp uyarı veriyordu, DateInterval kurucusu ise genel bir Exception fırlatıyordu. Örnekteki "yarın" ifadesi de bir uyarı niteliğinde: göreli ifadeler yalnızca İngilizce anlaşılır. Kullanıcı girdisini kurucuya veriyorsanız try/catch ile sarmalayın; istisnaların genel kuralları için PHP try/catch ve exception yazısına bakabilirsiniz.

Sonucu kullanmayı unutmak (PHP 8.5 uyarısı)

DateTimeImmutable ile en sık yapılan hata, değiştirme metodunun döndürdüğü yeni nesneyi bir değişkene atamayı unutmaktır. Kılavuzdaki sınıf özetinde add(), sub(), modify(), setDate(), setTime(), setTimezone() gibi metotlar PHP 8.5 ile gelen #[\NoDiscard] özniteliğiyle işaretlidir. PHP 8.5.12'de sonucu kullanılmayan çağrı şu uyarıyı üretiyor:

<?php
$d = new DateTimeImmutable('2026-11-07 09:00');
$d->modify('+1 day');   // sonuç kullanılmadı
echo $d->format('Y-m-d'), "\n";

Warning: The return value of method DateTimeImmutable::modify() should either be used or intentionally ignored by casting it as (void), as DateTimeImmutable::modify() does not modify the object itself in /yol/ornek.php on line 3
2026-11-07

Uyarı tam olarak sorunu söylüyor: metot nesnenin kendisini değiştirmez. Doğrusu $d = $d->modify('+1 day'); yazmaktır. Daha eski PHP sürümlerinde bu uyarı yoktur ve hata sessizce geçer; sürümünüz 8.5'in altındaysa bu kalıba kod incelemesinde özellikle dikkat edin. Yeni öznitelik hakkında ayrıntı için PHP 8.5 yenilikleri yazısına bakabilirsiniz.

Türkçe ay ve gün adları

format() yerel ayarları kullanmadığı için Türkçe ay ve gün adları üretmez. Kılavuz başka dillerde biçimlendirme için IntlDateFormatter::format() metodunu önerir. Bu sınıf intl eklentisinin parçasıdır; sunucunuzda eklentinin etkin olması gerekir.

<?php
$an = new DateTimeImmutable('2026-11-07 14:05', new DateTimeZone('Europe/Istanbul'));
$f = new IntlDateFormatter('tr_TR', IntlDateFormatter::FULL, IntlDateFormatter::SHORT, 'Europe/Istanbul');
echo $f->format($an), "\n";

$f2 = new IntlDateFormatter('tr_TR', IntlDateFormatter::NONE, IntlDateFormatter::NONE, 'Europe/Istanbul', null, 'd MMMM y, EEEE');
echo $f2->format($an), "\n";

7 Kasım 2026 Cumartesi 14:05
7 Kasım 2026, Cumartesi

İlk biçimlendirici hazır uzun tarih ve kısa saat stilini kullanıyor, ikincisi ise ICU kalıbıyla (d MMMM y, EEEE) özel bir biçim üretiyor. ICU kalıp harfleri format() karakterlerinden farklıdır; örneğin MMMM tam ay adı, EEEE tam gün adıdır. Para ve sayı biçimlendirme için ise PHP sprintf ve number_format yazısına göz atabilirsiniz.

Sık yapılan hatalar

• DateTime nesnesini paylaşıp değiştirmek. Atama kopya oluşturmaz; DateTimeImmutable kullanın.
• Immutable metodunun dönüşünü atamamak. $d->modify(...) tek başına hiçbir şey değiştirmez; sonucu bir değişkene atayın.
• Saat dilimini sunucuya bırakmak. Varsayılan ayar ortama göre değişir; nesneleri açık bir DateTimeZone ile oluşturun.
• +1 month ile ay sonu hesaplamak. 31 Ocak + 1 ay 3 Mart olur; last day of next month kullanın.
• %d ile toplam gün okumak. Toplam gün için %a veya days özelliği gerekir.
• createFromFormat sonucunu kontrol etmemek. Hem false dönüşünü hem getLastErrors() uyarılarını denetleyin; biçimde saat yoksa ! ekleyin.
• Türkçe göreli ifade yazmak. modify('yarın') geçersizdir; göreli ifadeler İngilizcedir.

Sık Sorulan Sorular

date() fonksiyonu ile DateTimeImmutable arasındaki fark nedir?

date() bir Unix zaman damgasını biçimlendiren prosedürel bir fonksiyondur ve aynı biçim karakterlerini kullanır. Saat dilimi dönüşümü, aritmetik ve fark hesabı gerektiğinde nesne tabanlı API çok daha açık ve güvenlidir. Ayrıca date() tamsayı zaman damgasıyla çalıştığından u karakteri her zaman 000000 üretir.

İki tarih arasındaki gün sayısını nasıl bulurum?

$a->diff($b)->days toplam tam gün sayısını verir. Kılavuzun belirttiği gibi 1 Ocak ile 31 Aralık arasındaki fark artık yıl olmayan bir yılda 364 gündür, 365 değil; aradaki günleri sayıyorsanız uçları dahil edip etmeyeceğinize karar verin.

Tarihi veritabanında nasıl saklamalıyım?

format('Y-m-d H:i:s') çoğu veritabanının tarih sütunlarıyla uyumludur; saat dilimi bilgisini kaybetmemek için ya UTC'ye çevirip saklayın ya da DATE_ATOM biçimini kullanın. Parametreli sorgularla kaydetme için PHP PDO veritabanı bağlantısı yazısına bakın.

Tarihi JSON'a nasıl yazarım?

Nesneyi doğrudan json_encode() ile kodlarsanız iç alanlarıyla bir nesne elde edersiniz. Bunun yerine format(DATE_ATOM) ile ISO 8601 metnine çevirin; ayrıntılar PHP json_encode ve json_decode yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: PHP öğrenme rehberi · PHP json_encode ve json_decode · PHP clone ve nesne karşılaştırma · PHP sprintf ve number_format · PHP 8.5 yenilikleri