Tarih ve Saat
*************

.[perex]
Nette, tarih ve saatle çalışmak için iki sınıf sunar: [api:Nette\Utils\DateTimeImmutable] (değişmez, önerilen) ve [api: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":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes. Bu sınıflar aritmetiğin sezgisel çalışmasını sağlar ve `+100 dakika` her zaman `+50 dakika`dan fazladır.

Kurulum:

```shell
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:

```php
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.

```php
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 .[method]
-----------------------------------------------------------------------
Bir dizeden, UNIX zaman damgasından veya başka bir [php:DateTimeInterface] nesnesinden nesne oluşturur. `null` geçerli zamanı belirtir. Tarih ve saat geçerli değilse istisna fırlatır.

```php
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 .[method]
------------------------------------------------------------------------------------------------------------------
Nesneyi tek tek parçalarından oluşturur; tarih ve saat geçerli değilse istisna fırlatır.

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


static createFromFormat(string $format, string $datetime, string|\DateTimeZone|null $timezone=null): static|false .[method]
---------------------------------------------------------------------------------------------------------------------------
Yerleşik [php:DateTime::createFromFormat] metodunu, saat dilimini dize olarak belirtme olanağıyla genişletir.

```php
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ı.

```php
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:

```php
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:

```php
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.

```php
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:

```php
$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: .{data-version:4.0.7}

```php
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.