An advanced library offering type safety and identity with Durations

Identity

This library uses some tricks to intern values so that two times are always equal to one another, no matter the distance in time or space.

useWithinboredom\Time;
useWithinboredom\Time\Unit;
$hour = Time::from(Unit::Hours, 1);
$minutes = Time::from(Unit::Minutes, 60);
echo$hour === $minutes ? 'true' : 'false'// outputs: true

Type Safety

You can ensure nobody will accidentally confuse seconds with milliseconds or minutes with seconds:

functionsleep(Time$time): void {
\sleep($time->as(Unit::Seconds));
}
// Helper functions are included so you can type less code:sleep(Minutes(5));

Conversions and Math

You can easily convert between units and even perform operations, like sorting and arithmetic:

// use the hour constant to get one hour$hour = Hour;
$hour = $hour->multiply(10)->add(Minutes(10)); // get 10:10 hours$interval = $hour->toDateInterval();
echoHours(10) < $hour ? 'true' : 'false';
// output: true

Support for Crell\Serde

You cannot serialize/deserialize/clone Time objects. However, if you use something like Serde, you can still serialize your value objects:

class CacheItem {
publicfunction__construct(
#[Field('expiration_in_seconds')]
#[TimeAs(Unit::Seconds)]
publicTime$expiration,
) {}
}
$serde = newSerdeCommon(handlers: new \Withinboredom\Time\SerdeExporter());
$serde->serialize(newCacheItem(Minutes(5)), 'json');

The above will be serialized (and deserialized) from:

{
"expiration_in_seconds": 300
}

Units

• Nanoseconds
• Microseconds
• Milliseconds
• Minutes
• Hours
• Days
• Weeks

FAQ

Why not months/years?

There are no set days in a month/year, so it’s better to use DateInterval for those types of measures.

Why does this exist?

I don’t like magic numbers.

How performant is this?

The main overhead is in autoloading and function-call overhead. Thus, if realtime performance is a concern, you might want to stick to magic numbers.

Developing

If you wish to create a PR or update the code here:

1. Clone the repo
2. composer install to install test dependencies
3. yarn to install git hooks for formatting
4. Open in favorite IDE.

Code Standards

Per coding styles are followed.