icecave / chrono
A date & time library that is decoupled from the system clock.
Installs: 154 537
Dependents: 7
Suggesters: 0
Security: 0
Stars: 53
Watchers: 4
Forks: 1
Open Issues: 29
Requires
- php: >=7.2
- icecave/isolator: ^3
- icecave/parity: ^3
Requires (Dev)
README
Chrono is a PHP date & time library that is decoupled from the system clock.
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.
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();