icanboogie / datetime
Extends the features of PHP DateTime and DateTimeZone
Installs: 328 896
Dependents: 5
Suggesters: 0
Security: 0
Stars: 50
Watchers: 5
Forks: 6
Open Issues: 0
Requires
- php: >=7.3
Requires (Dev)
- icanboogie/common: ^2.0
- phpunit/phpunit: ^9.5
Suggests
- icanboogie/common: Allows finer exceptions to be thrown
README
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:
<?php use ICanBoogie\DateTime; date_default_timezone_set('EST'); // set local time zone to Eastern Standard Time $time = new DateTime('now', 'Europe/Paris'); echo $time; // 2013-02-03T21:03:45+0100 echo $time->utc; // 2013-02-03T20:03:45Z echo $time->local; // 2013-02-03T15:03:45-0500 echo $time->utc->local; // 2013-02-03T15:03:45-0500 echo $time->utc->is_utc; // true echo $time->utc->is_local; // false echo $time->local->is_utc; // false echo $time->local->is_local; // true echo $time->is_dst; // false echo $time->as_rss; // Sun, 03 Feb 2013 21:03:45 +0100 echo $time->as_db; // 2013-02-03 21:03:45 echo $time->as_time; // 21:03:45 echo $time->utc->as_time; // 20:03:45 echo $time->local->as_time; // 15:03:45 echo $time->utc->local->as_time; // 15:03:45 echo $time->quarter; // 1 echo $time->week; // 5 echo $time->day; // 3 echo $time->minute; // 3 echo $time->is_monday; // false echo $time->is_saturday; // true echo $time->is_today; // true echo $time->tomorrow; // 2013-02-04T00:00:00+0100 echo $time->tomorrow->is_future; // true echo $time->yesterday; // 2013-02-02T00:00:00+0100 echo $time->yesterday->is_past; // true echo $time->monday; // 2013-01-28T00:00:00+0100 echo $time->sunday; // 2013-02-03T00:00:00+0100 echo $time->timestamp; // 1359921825 echo $time; // 2013-02-03T21:03:45+0100 $time->timestamp += 3600 * 4; echo $time; // 2013-02-04T01:03:45+0100 echo $time->zone; // Europe/Paris echo $time->zone->offset; // 3600 echo $time->zone->location; // FR,48.86667,2.33333 echo $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:
<?php use ICanBoogie\DateTime; $time = new DateTime('0000-00-00', 'utc'); // or $time = DateTime::none(); echo $time->is_empty; // true echo $time->as_date; // 0000-00-00 echo $time->as_db; // 0000-00-00 00:00:00 echo $time; // ""
Acknowledgements
The implementation of the DateTime class is vastly inspired by Ruby's Time class.
Day of week
<?php use ICanBoogie\DateTime; $time = new DateTime('2014-01-06 11:11:11', 'utc'); // a monday at 11:11:11 UTC echo $time->monday; // 2014-01-06T00:00:00Z echo $time->tuesday; // 2014-01-07T00:00:00Z echo $time->wednesday; // 2014-01-08T00:00:00Z echo $time->thursday; // 2014-01-09T00:00:00Z echo $time->friday; // 2014-01-10T00:00:00Z echo $time->saturday; // 2014-01-11T00:00:00Z echo $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. Subsequent calls return equal times, event if they are 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:
<?php use ICanBoogie\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:
<?php use ICanBoogie\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 just need two comparisons:
<?php use ICanBoogie\DateTime; $now = DateTime::now(); $now > $now->yesterday && $now < $now->tomorrow; // true
To determine which instance is the most recent, or the most late, simply use PHP's min()
and max()
functions:
<?php use ICanBoogie\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 instances implements the JsonSerializable interface and are serialized into ISO-8601 strings.
<?php use ICanBoogie\DateTime; $date = new DateTime("2014-10-23 13:50:10", "Europe/Paris"); echo json_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.
<?php use ICanBoogie\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.
<?php use ICanBoogie\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.
<?php use ICanBoogie\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.
<?php use ICanBoogie\CLDR\Repository; use ICanBoogie\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 UTC echo $date->localize('fr')->as_medium; // 5 mai 2015 23:13:05
Continuous Integration
The project is continuously tested by GitHub actions.
Contributing
Please see CONTRIBUTING for details.
License
ICanBoogie/DateTime is released under the BSD-3-Clause.