Tarih ve Saat

Nette, tarih ve saatle çalışmak için iki sınıf sunar: Nette\Utils\DateTimeImmutable (değişmez, önerilen) ve Nette\Utils\DateTime (değişebilir). İkisi de PHP'nin yerleşik sınıflarını genişletir, dolayısıyla tüm yerleşik metotlar kullanılabilir kalır; üstüne aynı iki iyileştirmeyi eklerler.

Birincisi, katıdırlar. PHP 0000-00-00 (-0001-11-30 yapar) veya 2024-02-31 (2024-03-02 yapar) gibi geçersiz tarihleri sessizce kabul ederken, bu sınıflar bunun yerine istisna fırlatır.

İkincisi, yaz saati uygulamasına (DST) geçişlerdeki davranışı düzeltirler; yerleşik PHP'de göreli bir süre eklemek (örneğin +100 dakika), daha kısa bir süre eklemekten (örneğin +50 dakika) daha erken bir zaman verebiliyor. Bu sınıflar aritmetiğin sezgisel çalışmasını sağlar ve +100 dakika her zaman +50 dakikadan fazladır.

Kurulum:

composer require nette/utils

Değişmez mi, Değişebilir mi?

DateTimeImmutable sınıfı 4.1.5 sürümünden beri kullanılabilir ve önerilen seçimdir. Değişiklik yapan her metot, özgün nesneyi değiştirmek yerine yeni bir örnek döndürür; böylece sakladığınız veya bir fonksiyona aktardığınız bir nesne asla beklenmedik şekilde değişmez:

use Nette\Utils\DateTimeImmutable;

$date = new DateTimeImmutable('2024-02-26');
$next = $date->modify('+1 day');
echo $date; // 2024-02-26 00:00:00  (değişmedi)
echo $next; // 2024-02-27 00:00:00  (yeni bir nesne)

DateTime ise değişebilirdir: aynı çağrı nesneyi yerinde değiştirir. Kullanımdan kaldırılmış değildir, ama yeni kodda değişmez varyant tercih edilir.

use Nette\Utils\DateTime;

$date = new DateTime('2024-02-26');
$date->modify('+1 day');
echo $date; // 2024-02-27 00:00:00  (özgün nesne değişti)

Her iki sınıf da yerleşik sınıfları genişlettiğinden, zaten bildiğiniz metotları kullanmayı sürdürürsünüz: format(), getTimestamp(), add(), sub(), diff(), setTimezone(), karşılaştırma operatörleri vb. DateTimeImmutable üzerinde değişiklik yapanların tümü yeni bir örnek döndürür. Bu sayfanın kalanı yalnızca Nette'nin bunlara eklediklerini anlatır; aksi belirtilmedikçe her şey iki sınıfta da aynı şekilde çalışır.

Nesne Oluşturma

static from (string|int|\DateTimeInterface|null $time): static

Bir dizeden, UNIX zaman damgasından veya başka bir DateTimeInterface nesnesinden nesne oluşturur. null geçerli zamanı belirtir. Tarih ve saat geçerli değilse istisna fırlatır.

DateTimeImmutable::from(1_138_013_640); // UNIX zaman damgasından, varsayılan saat dilimiyle
DateTimeImmutable::from('1994-02-26 04:15:32'); // dizeden
DateTimeImmutable::from('1994-02-26'); // tarihten, saat 00:00:00 olur
DateTimeImmutable::from(null); // geçerli tarih ve saat

static fromParts (int $year, int $month, int $day, int $hour=0, int $minute=0, float $second=0.0): static

Nesneyi tek tek parçalarından oluşturur; tarih ve saat geçerli değilse istisna fırlatır.

DateTimeImmutable::fromParts(1994, 2, 26, 4, 15, 32);

static createFromFormat (string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false

Yerleşik DateTime::createFromFormat metodunu, saat dilimini dize olarak belirtme olanağıyla genişletir.

DateTimeImmutable::createFromFormat('d.m.Y', '26.02.1994', 'Europe/London');

Katı Doğrulama

Geçersiz bir tarih ya da saat asla sessizce düzeltilmez; her zaman istisna fırlatılır. Bu, nesnenin oluşturulduğu veya değiştirildiği her yol için geçerlidir: yapıcı, from(), fromParts() ile setDate() ve setTime() metotları.

new DateTimeImmutable('2024-02-31');         // istisna (şubatın 31'i yok)
DateTimeImmutable::fromParts(2024, 2, 31);   // istisna
$date->setDate(2024, 2, 31);                 // istisna
$date->setTime(25, 0);                       // istisna (25. saat diye bir şey yok)

Dize Çıktısı ve JSON

__toString(), tarih ve saati Y-m-d H:i:s biçiminde döndürür; böylece nesne doğrudan yazdırılabilir veya birleştirilebilir:

echo $date; // '2017-02-03 04:15:32'

Her iki sınıf da JsonSerializable uygular ve JavaScript'te yaygın olarak kullanılan ISO 8601 biçiminde serileştirilir:

echo json_encode($date); // '"2017-02-03T04:15:32+01:00"'

DateTime'ın Ek Özellikleri

Değişebilir DateTime, yalnızca değişebilir bir nesne için anlamlı olan ve bu yüzden DateTimeImmutable'da yer almayan birkaç ek üye taşır.

Onun from() metodu, küçük bir sayıyı geçerli zamandan itibaren saniye cinsinden bir kayma olarak da ele alır. Değişmez varyant bu kısayolu bilinçli olarak dışarıda bırakır; orada bir sayı her zaman gerçek bir zaman damgasıdır.

DateTime::from(42); // geçerli zaman artı 42 saniye

modifyClone(string $modify=''): static, değiştirilmiş bir kopya döndürür ve özgün nesneye dokunmaz. Değişebilir bir nesnede, değişmez nesnede modify()'ın zaten sunduğu şeyi sağlar:

$original = DateTime::from('2017-02-03');
$clone = $original->modifyClone('+1 day');
$original->format('Y-m-d'); // '2017-02-03'  (değişmedi)
$clone->format('Y-m-d');    // '2017-02-04'

DateTime::relativeToSeconds(string $relativeTime): int, göreli zaman dizesini saniyeye dönüştürür:

DateTime::relativeToSeconds('1 minute'); // 60
DateTime::relativeToSeconds('-1 hour'); // -3600

Son olarak DateTime, saniye cinsinden uzunluk belirten MINUTE, HOUR, DAY, WEEK, MONTH ve YEAR sabitlerini tanımlar; MONTH ve YEAR ortalama değerlerdir, bu yüzden yalnızca kaba tahminlerde kullanın.