A date & time library that is decoupled from the system clock.
Chrono is a PHP date & time library that is decoupled from the system clock.
composer require icecave/chrono
Many date & time operations in the core PHP libraries require access to system state such as the current wall time, or resources such as timezone databases. These hard-wired dependencies can make it very difficult to write well-abstracted and testable code when dealing with time-sensitive operations.
Chrono provides a set of date & time classes that are completely decoupled from the system and hence behave consistently, regardless of system state and configuration (such as the date.timezone INI directive).
A SystemClock instance must be explicitly constructed before any global date & time operations are used. Classes that require use of a clock may take a ClockInterface as a dependency, improving decoupling and testability.
- Clock: A factory for chronological measurements.
- Time: A chronological measurement with a time component.
- Date: A chronological measurement with a date component.
- Time Point: A discreet point on the time-continuum.
- Time Span: An un-anchored span of time.
- Interval: A span of time between two Time Points.
- System Clock: A factory for chronological measurements that uses the system clock.
- Test Clock: A clock that can be manually manipulated for testing purposes.
- Date: Represents a date. Models the Time Point and Date concepts.
- Time of Day: Represents a time of day. Models the Time concept.
- Date Time: Represents a time of day on specific date. Models the Time Point, Date and Time concepts.
- Interval: A span of time between two Time Points. Models the Interval concept.
- Month: A one month time span. Models the Interval concept.
- Year: A one year time span. Models the Interval concept.
- Duration: A time span measured in seconds with no beginning or end. Models the Time Span concept.
- Period: A time span specified in component form (eg: 3 months, 4 days), models the Time Span concept.
In order to get the current time you need to use a clock. Most of the time in production code you will use the SystemClock class, which uses the machine's current system time and time zone information.
use Icecave\Chrono\Clock\SystemClock; // Construct a new system clock ... $clock = new SystemClock; // Obtain a DateTime instance representing the current date and time ... $now = $clock->localDateTime(); // Obtain a Date instance representing the current date ... $today = $clock->localDate(); // Obtain the current time of day ... $timeOfDay = $clock->localTime();
Each of the clock methods shown above has a UTC counterpart. For example, to obtain the current time in UTC you can use the following code:
$nowUtc = $clock->utcDateTime();
The output is specified using the same format as PHP's built-in date() function.
$now = $clock->localDateTime(); $string = $now->format('Y-m-d H:i:s');
Casting the object as a string (or calling
isoString()) produces an ISO-8601
$dateTime = DateTime::fromUnixTime(1367823963); $timestamp = $dateTime->unixTime();
use DateTime as NativeDateTime; use Icecave\Chrono\DateTime; $dateTime = DateTime::fromNativeDateTime(new NativeDateTime); $nativeDateTime = $dateTime->nativeDateTime();