Date and Time
*************

.[perex]
[api:Nette\Utils\DateTime] is a class that extends the native [php:DateTime] with additional useful features.

Compared to the native class, it is strict. While PHP **silently accepts** invalid dates like `0000-00-00` (converts to `-0001-11-30`) or `2024-02-31` (converts to `2024-03-02`), `Nette\Utils\DateTime` throws an exception in such cases.

It also **fixes the behavior** during Daylight Saving Time (DST) transitions, where in native PHP adding a relative time (e.g., `+100 minutes`) can "result in an earlier time":https://phpfashion.com/en/100-minutes-is-less-than-50-php-paradoxes-during-time-changes than adding a shorter period (e.g., `+50 minutes`). Nette ensures that arithmetic works intuitively and `+100 minutes` is always more than `+50 minutes`.

Installation:

```shell
composer require nette/utils
```

All examples assume the following class alias is defined:

```php
use Nette\Utils\DateTime;
```


static from(string|int|\DateTimeInterface $time): static .[method]
------------------------------------------------------------------
Creates a `DateTime` object from a string, UNIX timestamp, or another [php:DateTimeInterface] object. Throws an `\Exception` if the date and time are not valid.

```php
DateTime::from(1138013640); // creates a DateTime from the UNIX timestamp with the default timezone
DateTime::from(42); // creates a DateTime from the current time plus 42 seconds
DateTime::from('1994-02-26 04:15:32'); // creates a DateTime based on a string
DateTime::from('1994-02-26'); // creates DateTime from date, time will be 00:00:00
```


static fromParts(int $year, int $month, int $day, int $hour=0, int $minute=0, float $second=0.0): static .[method]
------------------------------------------------------------------------------------------------------------------
Creates a `DateTime` object or throws an `Nette\InvalidArgumentException` if the date and time are not valid.
```php
DateTime::fromParts(1994, 2, 26, 4, 15, 32);
```


static createFromFormat(string $format, string $time, string|\DateTimeZone|null $timezone=null): static|false .[method]
-----------------------------------------------------------------------------------------------------------------------
Extends [php:DateTime::createFromFormat] with the ability to specify a timezone as a string.
```php
DateTime::createFromFormat('d.m.Y', '26.02.1994', 'Europe/London'); // create with custom timezone
```


static relativeToSeconds(string $str): int .[method]{data-version:4.0.7}
------------------------------------------------------------------------
Converts a relative time string to seconds. It is useful for converting times like `5 minutes` or `2 hours` to a numeric value.

```php
DateTime::relativeToSeconds('1 minute'); // 60
DateTime::relativeToSeconds('10 minutes'); // 600
DateTime::relativeToSeconds('-1 hour'); // -3600
```


modifyClone(string $modify=''): static .[method]
------------------------------------------------
Creates a copy with a modified time.
```php
$original = DateTime::from('2017-02-03');
$clone = $original->modifyClone('+1 day');
$original->format('Y-m-d'); // '2017-02-03'
$clone->format('Y-m-d');    // '2017-02-04'
```


__toString(): string .[method]
------------------------------
Returns the date and time in the format `Y-m-d H:i:s`.
```php
echo $dateTime; // '2017-02-03 04:15:32'
```


implements JsonSerializable .[method]
-------------------------------------
Returns the date and time in ISO 8601 format (e.g., `2017-02-03T04:15:32.123+01:00`), which is commonly used in JavaScript.
```php
$date = DateTime::from('2017-02-03');
echo json_encode($date);
```