icecave/chrono

A date & time library that is decoupled from the system clock.

Chrono

, _(*1)

Chrono is a PHP date & time library that is decoupled from the system clock., _(*2)

composer require icecave/chrono

Rationale

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., _(*3)

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)., _(*4)

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., _(*5)

Concepts

• 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.

Implementations

• 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.

Examples

Getting the current time

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., _(*6)

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:, _(*7)

$nowUtc = $clock->utcDateTime();

String formatting

To produce a formatted string representing a Date, DateTime, TimeOfDay or TimeZone instance use the format() method., _(*8)

The output is specified using the same format as PHP's built-in date() function., _(*9)

$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 string representation., _(*10)

Unix timestamps

Date and DateTime instances can be produced from unix timestamps using the fromUnixTime() static method. The unix timestamp can be retrieved using unixTime()., _(*11)

$dateTime = DateTime::fromUnixTime(1367823963);
$timestamp = $dateTime->unixTime();

PHP native "DateTime" objects

Date and DateTime instances can be produced from native PHP DateTime instances using the fromNativeDateTime() static method, and can be converted to a native DateTime using nativeDateTime()., _(*12)

use DateTime as NativeDateTime;
use Icecave\Chrono\DateTime;

$dateTime = DateTime::fromNativeDateTime(new NativeDateTime);
$nativeDateTime = $dateTime->nativeDateTime();