Download the PHP package dakujem/time without Composer

Time

💿 composer require dakujem/time

📒 Changelog

A no-nonsense library for working with time and doing temporal calculations the easy way.

The aim of the Time toolkit is to help working with temporal data like work timer measurements, schedules, time-tables, subscription timers etc.

For example, Time supports working with negative times and times exceeding 24 hours, as opposed to DateTime or Carbon:

On the contrary to DateTime or Carbon (nesbot/carbon), Time is simply a container for time measured in seconds, it does not refer to any real point-in-time, there are no time zones no nothing.

With Time you can compare time values, perform atirhmetic operations or convert them. You can parse strings containing formatted time values and you can print the Time object according to a specified format.

Your data may be stored in seconds, minutes, hours or in formatted strings, working with Time will still be the same.

Methods

There are many methods for handling, converting, modifying, reading and printing the time value.

Options to create a time object:

Arithmetic methods:

Comparisons:

Adding / subtracting seconds, minutes, hours, days or weeks:

Conversion options:

Input parsing (reading) and output formatting:

Output to other time objects (conversion):

Validating valid day time and clipping to valid day time:

And there is more!

Note: For all the methods, please refer to the source code.

Mutable and Immutable Time objects

The default Time object is immutable. It means that once a Time instance is created, its value does not change. Upon any modification a new instance is returned.

Sometimes one needs to treat a time object as a mutable object, an accumulator, the solution is the TimeMutable class.

TimeMutable may be useful for aggregations:

Parsing time strings and formatting

By default, Time accepts time strings in HH:MM:SS format:

The default format is stored in TimeHelper::$defaultFormat static variable and can be changed. However, it is always more flexible to use a factory and pass Time instances into calculations:

This way the format of the input can be changed at runtime and can be set for all the factories independently. The factories can also be implemented in custom way and use custom parsers.

To use different formats without using a factory, TimeHelper can be used manually:

The same principle is true for formatting. Converting the time objects to string is done using the format stored in TimeHelper::$defaultFormat, that is HH:MM:SS by default.

Note

Parsing and printing of "funny" formats (like "i:H", "?i:s") is not advised with negative numbers. It is best to only parse standard time representations. If special time formats need to be parsed, own parser should be provided and Time library used for calculations afterwards.

Milliseconds, microseconds...

The Time object is built for calculations in seconds, which is the maximum integer resolution for which all the features work.

However, it is possible to use double time values to get heigher resolution (milliseconds or microseconds):

Features that do not work correctly (yet) when using double:

• parsing - custom parsing needed
• formatting - TimeHelper is currently unable to format double correctly
• there is no round or abs implementation yet

Note: When using double data type all the PHP implementation limitations apply.

Installation

Use Composer:

$ composer require dakujem/time

Testing

Run CLI command:

$ composer test

Or open tests/index.php in a browser.