datetime
, (*1)
, (*2)
PHP7 date/time library., (*3)
Prerequisites
Installation
Install via composer
To install datetime with Composer, run the following command:, (*4)
$ composer require krixon/datetime
You can see this library on Packagist., (*5)
Install from source
# HTTP
$ git clone https://github.com/krixon/datetime.git
# SSH
$ git clone git@github.com:krixon/datetime.git
Introduction
This library is a layer on top of PHP's built-in date and time classes which provides additional functionality
and improvements such as microsecond precision and immutability (without the inconsistencies between \DateTime,
\DateTimeImmutable and DateTimeInterface)., (*6)
Creating Dates
There are various ways to create a new DateTime instance., (*7)
Using the current time and default timezone:, (*8)
// These objects all represent the current time.
$date = DateTime::now();
$date = DateTime::create();
$date = new DateTime();
Using a UNIX timestamp:, (*9)
// Standard (second) precision.
DateTime::fromTimestamp(1499789008)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.000000
// Millisecond precision.
DateTime::fromTimestampWithMilliseconds(1499789008123)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.123000
// Microsecond precision.
DateTime::fromTimestampWithMicroseconds(1499789008123456)->format('Y-m-d H:i:s.u');
// 2017-07-11 16:03:28.123456
Parsing a string using a specified format:, (*10)
$date = DateTime::fromFormat('Y-m-d H:i:s.u', '2017-07-11 16:03:28.123456');
Parsing a string containing any supported date and time format:, (*11)
$date = DateTime::create('yesterday');
$date = DateTime::create('1 month ago');
$date = DateTime::create('first day of January 2008');
$date = DateTime::create('+5 weeks');
$date = DateTime::create('Monday next week');
// etc
Using an existing built-in \DateTime instance:, (*12)
$date = DateTime::fromInternalDateTime(new \DateTime());
Using an existing \IntlCalendar instance:, (*13)
$calendar = \IntlCalendar::createInstance();
$calendar->setTime(1499789008123);
$date = DateTime::fromIntlCalendar($calendar);
Modifying Dates
All DateTime instances are immutable. However methods are provided for creating new instances with modifications
applied., (*14)
Adjusting the date:, (*15)
$date = DateTime::create('21st March 2017 09:45:00');
$date->withDateAt(2016, 09, 15); // 2016-09-15 09:45:00
// Any components not specified will not be changed.
$date->withDateAt(null, null, 15); // 2017-01-15 09:45:00
// There are also methods for setting the components individually.
$date->withYear(1981); // 1981-03-21 09:45:00
$date->withMonth(DateTime::JAN); // 2017-01-21 09:45:00
$date->withDay(15); // 2017-03-15 09:45:00
// Convenience methods for common date adjustments.
$date->withDateAtStartOfYear(); // 2017-01-01 00:00:00
$date->withDateAtStartOfMonth(); // 2017-03-01 00:00:00
$date->withDateAtEndOfMonth(); // 2017-03-31 00:00:00
$date->withDateAtDayOfWeekInMonth(DateTime::TUE, 4); // 2017-03-28 00:00:00 (4th Tuesday in March 2017)
$date->withDateAtDayOfWeekInMonth(DateTime::MON, -2); // 2017-03-20 00:00:00 (Penultimate Tuesday in March 2017)
$date->withDateAtStartOfWeek('en_GB'); // 2017-03-20 00:00:00 (Monday, start of the week of 21st Match 2017 in Great Britain).
$date->withDateAtStartOfWeek('en_US'); // 2017-03-19 00:00:00 (Sunday, start of the week of 21st Match 2017 in USA).
If you are making many changes to a DateTime without needing the intermediate objects, you can use the
DateTimeCalculator class. This supports all of the operations you can do on a DateTime object itself but without
the overhead of creating new objects which are then thrown away., (*16)
For example, imagine you want to add an interval to a base date a number of times, but you are only interested in
the final result. While you could call $date = $date->add('PT1D') repeatedly, a more efficient method would be:, (*17)
$calculator = DateTime::create('2017-01-01')->calculator();
for ($i = 0; $i < 50; $i++) {
$calculator->addInterval('PT1D');
}
$date = $calculator->result(); // 2017-02-19
Of course this is a contrived example and in reality you would just call $date = $date->add('PT50D'), but there
are many arithmetic operations you can perform with the calculator which cannot necessarily be achieved as efficiently
using just the DateTime API., (*18)
Wallogit.com
