Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A date & time library that is decoupled from the system clock.
branch: develop

Merge tag '1.0.3' into develop

Version 1.0.3

* **[IMPROVED]** `DateTime` and `TimeOfDay` ISO string parsing now allows (but discards) partial-second information
latest commit e9638904e7
James Harris jmalloc authored
Failed to load latest commit information.
src
test/suite CS
.gitattributes Integrated Archer.
.gitignore Integrated Archer.
.php_cs CS
.travis.env Updating travis config.
.travis.install
.travis.key Integrated Archer.
.travis.yml Updated Travis configuration & code-style fixes.
CHANGELOG.md Bumped version and updated changelog.
CONTRIBUTING.md General maintenance of documentation, etc [ci skip]
LICENSE.md Removed typhoon, fixed some dependencies, housekeeping.
README.md Bumped version and updated changelog.
composer.json Allow either isolator 2.x or 3.x
composer.lock Updated dependencies.

README.md

Chrono

Build Status Test Coverage SemVer

Chrono is a PHP date & time library that is decoupled from the system clock.

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.

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.

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.

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();

String formatting

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

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 string representation.

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().

$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().

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

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

Contact us

Something went wrong with that request. Please try again.