krixon / datetime
Datetime value objects.
Installs: 6 982
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 1
Requires
- php-64bit: >=7
Requires (Dev)
- phpunit/phpunit: 5.4.*
- satooshi/php-coveralls: ^1.0
This package is auto-updated.
Last update: 2024-11-17 19:20:25 UTC
README
PHP7 date/time library.
Prerequisites
- PHP 7.0+
Installation
Install via composer
To install datetime with Composer, run the following command:
$ composer require krixon/datetime
You can see this library on Packagist.
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
).
Creating Dates
There are various ways to create a new DateTime
instance.
Using the current time and default timezone:
// These objects all represent the current time. $date = DateTime::now(); $date = DateTime::create(); $date = new DateTime();
Using a UNIX timestamp:
// 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:
$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:
$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:
$date = DateTime::fromInternalDateTime(new \DateTime());
Using an existing \IntlCalendar
instance:
$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.
Adjusting the date:
$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.
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:
$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.