DateTime

This package extends the features of PHP DateTime and DateTimeZone classes to ease the handling of times, time zones, and time zone locations. Getting the UTC or local representation of a time, formatting the time to a predefined format, accessing common properties such as day, month, year, quarter, and more has been made especially easy. Also, all instances can be used as strings.

Installation

composer require icanboogie/datetime

Usage

Let's say that now is "2013-02-03 21:03:45" in Paris:

<?phpuseICanBoogie\DateTime;
date_default_timezone_set('EST'); // set local time zone to Eastern Standard Time$time = newDateTime('now', 'Europe/Paris');
echo$time; // 2013-02-03T21:03:45+0100echo$time->utc; // 2013-02-03T20:03:45Zecho$time->local; // 2013-02-03T15:03:45-0500echo$time->utc->local; // 2013-02-03T15:03:45-0500echo$time->utc->is_utc; // trueecho$time->utc->is_local; // falseecho$time->local->is_utc; // falseecho$time->local->is_local; // trueecho$time->is_dst; // falseecho$time->as_rss; // Sun, 03 Feb 2013 21:03:45 +0100echo$time->as_db; // 2013-02-03 21:03:45echo$time->as_time; // 21:03:45echo$time->utc->as_time; // 20:03:45echo$time->local->as_time; // 15:03:45echo$time->utc->local->as_time; // 15:03:45echo$time->quarter; // 1echo$time->week; // 5echo$time->day; // 3echo$time->minute; // 3echo$time->is_monday; // falseecho$time->is_saturday; // trueecho$time->is_today; // trueecho$time->tomorrow; // 2013-02-04T00:00:00+0100echo$time->tomorrow->is_future; // trueecho$time->yesterday; // 2013-02-02T00:00:00+0100echo$time->yesterday->is_past; // trueecho$time->monday; // 2013-01-28T00:00:00+0100echo$time->sunday; // 2013-02-03T00:00:00+0100echo$time->timestamp; // 1359921825echo$time; // 2013-02-03T21:03:45+0100$time->timestamp += 3600 * 4;
echo$time; // 2013-02-04T01:03:45+0100echo$time->zone; // Europe/Parisecho$time->zone->offset; // 3600echo$time->zone->location; // FR,48.86667,2.33333echo$time->zone->location->latitude; // 48.86667$time->zone = 'Asia/Tokyo';
echo$time; // 2013-02-04T09:03:45+0900$time->hour += 72;
echo"Rendez-vous in 72 hours: $time"; // Rendez-vous in 72 hours: 2013-02-07T05:03:45+0900

Empty dates are also supported:

<?phpuseICanBoogie\DateTime;
$time = newDateTime('0000-00-00', 'utc');
// or$time = DateTime::none();
echo$time->is_empty; // trueecho$time->as_date; // 0000-00-00echo$time->as_db; // 0000-00-00 00:00:00echo$time; // ""

Acknowledgements

Ruby's Time class greatly inspired the implementation of the DateTime class.

Day of the week

<?phpuseICanBoogie\DateTime;
$time = newDateTime('2014-01-06 11:11:11', 'utc'); // a monday at 11:11:11 UTCecho$time->monday; // 2014-01-06T00:00:00Zecho$time->tuesday; // 2014-01-07T00:00:00Zecho$time->wednesday; // 2014-01-08T00:00:00Zecho$time->thursday; // 2014-01-09T00:00:00Zecho$time->friday; // 2014-01-10T00:00:00Zecho$time->saturday; // 2014-01-11T00:00:00Zecho$time->sunday; // 2014-01-12T00:00:00Z$time->monday->is_monday; // true$time->tuesday->is_tuesday; // true$time->wednesday->is_wednesday; // true$time->thursday->is_thursday; // true$time->friday->is_friday; // true$time->saturday->is_saturday; // true$time->sunday->is_sunday; // true$time->monday->is_tuesday; // false$time->tuesday->is_wednesday; // false$time->wednesday->is_thursday; // false$time->thursday->is_friday; // false$time->friday->is_saturday; // false$time->saturday->is_sunday; // false$time->sunday->is_monday; // false$time->monday->weekday; // 1$time->tuesday->weekday; // 2$time->wednesday->weekday; // 3$time->thursday->weekday; // 4$time->friday->weekday; // 5$time->saturday->weekday; // 6$time->sunday->weekday; // 7

now() and right_now()

DateTime::now() returns a new instance with the current local time and the local time zone. Further calls return equal times, event if they're minutes apart. now actually refers to the REQUEST_TIME or, if it is not available, to the first time the method was invoked.

On the other hand, DateTime::right_now() returns a new instance with the real current local time and the local time zone.

The following example demonstrates the difference:

<?phpuseICanBoogie\DateTime;
$now = DateTime::now();
sleep(2);
$now == DateTime::now(); // true$now == DateTime::right_now(); // false

Comparing DateTime instances

DateTime Instances are compared using standard comparison operations:

<?phpuseICanBoogie\DateTime;
$d1 = DateTime::now();
$d2 = DateTime::now();
$d1 == $d2; // true$d1 >= $d2; // true$d1 <= $d2; // true$d1 != $d2; // false$d1 > $d2; // false$d1 < $d2; // false$d2->second++;
$d1 != $d2; // true$d1 < $d2; // true$d2 > $d1; // true$d1 == $d2; // false$d1 >= $d2; // false$d2 <= $d1; // false

To determine if an instance is between two other instances, you need two comparisons:

<?phpuseICanBoogie\DateTime;
$now = DateTime::now();
$now > $now->yesterday && $now < $now->tomorrow; // true

To determine which instance is the most recent, or the latest, use PHP's min() and max() functions:

<?phpuseICanBoogie\DateTime;
$now = DateTime::now();
$yesterday = $now->yesterday;
$tomorrow = $now->tomorrow;
$yesterday === min($now, $yesterday, $tomorrow); // true$tomorrow === max($now, $yesterday, $tomorrow); // true

DateTime and JSON

Starting with v1.1.0, DateTime implements the JsonSerializable interface and serializes into ISO-8601 strings.

<?phpuseICanBoogie\DateTime;
$date = newDateTime("2014-10-23 13:50:10", "Europe/Paris");
echojson_encode([ 'date' => $date ]);
// {"date":"2014-10-23T13:50:10+0200"}

Changing multiple properties

The change() method is used to change multiple properties at once.

Note: Values exceeding ranges are added to their parent values.

<?phpuseICanBoogie\DateTime;
$date = DateTime::now()->change([ 'year' => 2015, 'month' => 5, 'hour' => 12 ]);

Using the $cascade parameter, setting the hour resets the minute and second to 0, and setting the minute resets the second to 0.

<?phpuseICanBoogie\DateTime;
echo DateTime::from("2015-05-05 12:13:14")->change([ 'hour' => 13 ], true); // 2015-05-05 13:00:00

Creating a new instance with changed properties

The with() method is similar to the change() method as it is used to define multiple properties at once, the difference is that the method creates a new instance, leaving the original instance intact.

<?phpuseICanBoogie\DateTime;
$now = DateTime::now();
$next_year = $now->with([ 'year' => $now->year + 1 ]);
spl_object_hash($now) == spl_object_hash($next_year); // false

Localized formatting

Localized formatting is outside of this package scope, still a localizer can be provided to the DateTime class to localize its instances, but of course the result depends on the implementation.

The following example demonstrates how to localize instances using ICanBoogie/CLDR which uses Unicode's Common Locale Data Repository to format DateTime instances.

<?phpuseICanBoogie\CLDR\Repository;
useICanBoogie\DateTime;
// …/* @var Repository $repository */
DateTime::$localizer = function(DateTime$instance, $locale) use ($repository) {
return$repository->locales[$locale]->localize($instance);
};
$date = DateTime::from('2015-05-05 23:21:05', 'UTC');
echo$date->localize('fr')->format('long'); // mardi 5 mai 2015 23:13:05 UTCecho$date->localize('fr')->as_medium; // 5 mai 2015 23:13:05

---

Continuous Integration

The project is continuously tested by GitHub actions.

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you're expected to uphold this code.

Contributing

See CONTRIBUTING for details.

License

ICanBoogie/DateTime is released under the BSD-3-Clause.