Download the PHP package bakame/tokei without Composer

Tokei

Tokei (pronounced: [to̞ke̞ː] or [tokeː]) is a lightweight domain-focused set of immutable value objects for representing and operating on time, durations, including, circular 24-hour intervals, and interval sets, offering expressive temporal modeling without timezone handling.

The framework-agnostic package offers a consistent and expressive way to work with temporal values in a safe and predictable manner.

Installation

composer require bakame/tokei

You need:

• PHP >= 8.3 but the latest stable version of PHP is recommended
• to be able to get the locale string version of the time you need the ext-intl extension or use its polyfill.

Documentation

Time

The Bakame\Tokei\Time object is designed to be, cyclic (24h wrap-around) and precision-aware (microseconds supported)

Instantiation

You can create a Time instance:

• using its time components via the Time::at method;
• by parsing a time string using the Time::parse method;
• using Time::atMicroOfDay, Time::atMilliOfDay, Time::atSecondOfDay or Time::atMinuteOfDay; The value will represent respectively the microseconds, milliseconds, seconds or minutes from midnight.

Here's some usage example.

[!WARNING] On failure, with Time::parse, null is returned instead of an exception being thrown.

To ease instantiation, predefined instances can be obtained with the following methods:

Accessors

Once instantiated you can access each time component using the following methods

Formatting

To work as expected the Time::toLocaleString requires the presence of the Intl extension or of its polyfill otherwise a TimeException will be thrown.

Example:

Modifying time

Because Time is an immutable VO, any change to its value will return a new instance with the updated value and leave the original object unchanged. You can modify the time with the following methods:

• Time::add will add a duration to change the time;
• Time::with will adjust a specific time component;
• Time::roundTo will adjust a specific time component;
• Time::clamp will adjust the time against two other time references;

The add and with methods act differently in regard to wrapping around 24hours automatically. The Time::add supports wrapping whereas Time::with does not and instead throws an InvalidTime exception instead

To simplify reasoning around time you can also truncate or round its value to one of the unit declare on the Bakame\Tokei\Unit enum

Comparing times

It is possible to compare two Time instances using the Time::compareTo method.

the method returns:

• -1 if earlier
• 0 if equal
• 1 if later

Convenient methods derived from Time::compareTo are also available to ease usage:

Differences

The class provides two methods to account for differences between two Time instances:

• the Time::diff returns the signed difference between both instances;
• the Time::distance returns the forward cyclic difference (24 wrap) between both instances;

Here's an example usage to highlight the distinction in returned values between both differences methods:

Interacting with PHP's native Date API

In one hand, it is possible to extract the time part of any DateTimeInterface implementing class using the fromDate method. On the other hand, you can apply the time to an DateTimeInterface object using the applyTo method

[!NOTE] If the DateTimeInterface instance submitted extends the DateTimeImmutable class then the return type will be of that same type otherwise PHP's DateTimeImmutable is returned.

Duration

The Bakame\Tokei\Duration Value Object provides utilities for working with durations

Instantiation

The Duration class can be instantiated either by providing:

• each duration parts using the complementaryDuration::of method.
• a ISO8601 duration expression.

[!IMPORTANT] Duration::fromNotation only parse ISO8601 notations with deterministic part (ie: years and months are excluded)

Accessors

Once instantiated you can access the duration properties directly. The object exposes a sign property which indicates if the original value was negative, 0 or positive. And provides a toMicro method to get the microseconds based representation of the duration.

Formatting

Formatting the duration string representation is returned by the Duration::format with the help of the DurationNotation Enum

When using the DurationNotation::Chrono the following human-readable format is used:

• microseconds are optional
• negative values are prefixed with -

When using the DurationNotation::Iso8601 formats the instance value is converted into a ISO8601 compatible string. The returned string may not be compatible with PHP's DateInterval constructor but is valid withing the ISO8601 extended specification.

[!IMPORTANT]

• Only deterministic duration interval are used Y, M for month are not used
• to have a predictive representation W is not used; 7D multiple are used instead.

Last but not least a compact format more suited for debugging is returns using the DurationNotation::Compact case.

The Duration class also allows conversion in time units and in DateInterval instances. The method Duration::toDateInterval converts the instance into a PHP DateInterval instance while preserving its sign (inverted intervals are supported).

Modifying duration

You can:

• make it unsigned using the Duration::abs method
• invert its signing using the Duration::negate method
• update the duration using fixed duration parts Duration::increment method
• round its value to one of the unit declare on the Bakame\Tokei\Unit enum
• clamp its value against two other Duration instances
• sum multiple Duration instance using the Duration::sum method
• multiply or divide a Duration instance using the Duration::multipliedBy and Duration::dividevBy methods

Comparing duration

It is possible to compare duration using common methods terminology

Returns:

• -1 if shorter
• 0 if equal
• 1 if longer

Convenient methods based on Duration::compareTo are also available:

Interval

Bakame\Tokei\Interval represents a start-inclusive, end-exclusive interval between two times on a 24-hour circular clock.

Intervals are immutable and support:

• circular ranges crossing midnight,
• interval algebra,
• time iteration,
• normalization,
• duration arithmetic.

The library uses half-open interval semantic where start is inclusive and end is exclusive. If end < start, the interval is considered to wrap around midnight.

The library also support both collapsed and circular intervals for which start == end.

The distinction between them lies in their duration:

• a collapsed interval has a duration of PT0S, representing an empty interval;
• a circular interval has a duration of P1D, representing a full-day interval.

for instance:

An interval can, thus, be defined as either:

• a continuous span of time between two points in time, or
• a continuous span of time starting at a specific point in time with a given duration.

Instantiation

Accessors

Interval Type

Formatting

using the following Enum:

Out of the box, to following formatting algorithm are possible:

• ISO8601 returns a string representation based on the starting time and the interval duration;
• IS08000 returns a string representation based on the interval endpoints;
• Bourbaki returns a string representation based on the interval endpoints with different boundary markers;

Iterations

Modifying by duration and/or time

Strict Comparison

The method compares the instance endpoint as well as its duration.

Duration based comparison

Time based comparison

Interacting with PHP's native Date API

The reference DateTimeInterface object is used to compute the starting date using Time::applyTo method.

IntervalSet

Bakame\Tokei\IntervalSet is an immutable collection of Bakame\Tokei\Interval instances implementing PHP's Countable and IteratorAggregate interfaces. it represents a collection of intervals treated as a single temporal domain.

it supports:

• interval normalization,
• union, intersection, and difference operations,
• containment checks,
• interval splitting and merging,
• iteration over intervals.

Overlapping or adjacent intervals may be merged during normalization to produce a minimal and consistent representation.

An IntervalSet may contain zero, one, or multiple non-overlapping intervals, including collapsed and circular intervals.

Instantiation

Accessors

nth and get supports negative index but differ on failure:

• nth returns null on invalid offset;
• get throws a TimeException exception on invalid offset;

Formatting

Supports the same formatting arguments as the Interval::format method.

Interacting with PHP's native Date API

Returns the list of Interval instances converted using their Interval::toNative method.

Interval methods

Collection methods

Testing

The library has:

• a PHPUnit test suite.
• a coding style compliance test suite using PHP CS Fixer.
• a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder.

Contributing

Contributions are welcome and will be fully credited. Please see CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• ignace nyamagana butera
• All Contributors