vdhicts/time

Time value-object with parser and collection and helpers for duration, rounding and ranges. Makes working with times easy.

v6.0.0 2024-08-13 17:36 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^10.5
• rector/rector: ^1.2
• symplify/easy-coding-standard: ^12.0

MIT

• D. van der Heiden

README

This package aims to make working with times (as in date, ranges and/or duration) easier. It contains a time value-object, parser, ranges, duration, rounding, etc.

Requirements

This package requires PHP 8.1 or higher.

Installation

You can install the package via composer:

composer require vdhicts/time

Usage

This package aims to provide an easy usage, with some similarities with PHP's DateTime and Carbon. An example of that are the interfaces.

Time

The Time object can be initiated with:

$time = new Time(14, 30, 15);

Building from input

To build the Time object from several different inputs, you can use the following methods:

TimeFactory::createFromString('14:30:15'); // Time object with 14 hours, 30 minutes and 15 seconds
TimeFactory::createFromDateTime(new \DateTime('2023-01-01 14:30:15')); // Time object with 14 hours, 30 minutes and 15 seconds
TimeFactory::createFromTimestamp(1640000000); // Time object with 11 hours, 33 minutes and 20 seconds
TimeFactory::createFromDurationInSeconds(9000); // Time object with 2 hours and 30 minutes
TimeFactory::createFromDurationInMinutes(150); // Time object with 2 hours and 30 minutes

Comparison

The Time object makes it easy to compare to other Time objects. It offers the following methods:

$time->isEqualTo(Time $anotherTime);
$time->isBefore(Time $anotherTime);
$time->isBeforeOrEqualTo(Time $anotherTime);
$time->isAfter(Time $anotherTime);
$time->isAfterOrEqualTo(Time $anotherTime);

Difference

The time object can also be used to calculate the difference between time objects:

$timeStart = new Time(10, 30);
$timeEnd = new Time(14);

$timeStart->diffInHours($timeEnd); // 3.5
$timeEnd->diffInHours($timeStart); // -3.5

The difference can be calculated in hours (diffInHours), minutes (diffInMinutes) and seconds (diffInSeconds).

Duration

A time can be part of a date, i.e. 2022-03-01 10:00:00 but can also be used for a duration, i.e. "It took me 1 hour and 46 minutes to get there.".

$time = new Time(1, 46);

sprintf('It took me %s hours', $time->durationInHours());
sprintf('It took me %s minutes', $time->durationInMinutes());
sprintf('It took me %s seconds', $time->durationInSeconds());

Results in:

string(32) "It took me 1.7666666666667 hours"
string(22) "It took me 106 minutes"
string(23) "It took me 6360 seconds"

Rounding

Working with very specific times might not always be the result you want, for example for time tracking. This package allows you to round the time to your likings. By default, it rounds to 5 minutes:

$time = new Time(2, 46, 23);

$time->roundNatural(); // 02:45:00
$time->roundUp(); // 02:50:00
$time->roundDown(); // 02:45:00

It's also possible to round the seconds and/or change the precision. For example, round to 15 seconds:

$time = new Time(2, 21, 33);

$time->roundNatural(15, true); // 02:21:30
$time->roundUp(15, true); // 02:21:45
$time->roundDown(15, true); // 02:21:30

Presentation

The Time object can be presented as a string with the toString method or just casting the object to a string (string)$time. This will output: 14:30:15.

There are also two other presentations available, the toNumericalTime and toReadableTime:

$time = new Time(12, 30, 45);
$time->toNumericalTime(); // 12:50
$time->toNumericalTime(true); // 12:50:75

$time->toReadableTime(); // 12:30
$time->toReadableTime(true); // 12:30:45

Time collection

Time objects can be collected in a TimeCollection. The TimeCollection ca be initiated with:

$timeCollection = new TimeCollection();

It's possible to provide an array of Time objects or to use the add and set methods on the collection. The contains method provides the ability to check if the collection contains a Time object.

Time range

A TimeRange object contains two Time objects, a start and end time. The TimeRange object can be initiated with:

$timeRange = new TimeRange($time, $anotherTime);

To get the duration of the range, you can get the Time object as duration with:

$timeRange->getRangeDuration();

Comparison

The TimeRange object makes it easy to compare to a single Time or another TimeRange.

To determine if a Time is in a range:

$time = new Time(14, 30, 15);
$timeRange->inRange($time);

To determine if another range overlaps the range:

$anotherTimeRange = new TimeRange($time, $anotherTime);
$timeRange->isOverlapping($anotherTimeRange);

Tests

Unit tests are available in the tests folder. Run with:

composer test

When you want a code coverage report which will be generated in the build/report folder. Run with:

composer test-coverage

Contribution

Any contribution is welcome, but it should meet the PER 2.0 code style and please create one pull request per feature/bug. In exchange, you will be credited as contributor.

Security

If you discover any security related issues in this or other packages of Vdhicts, please email [e-mail] instead of using the issue tracker.

License

This package is open-sourced software licensed under the MIT license