PHPackages                             dakujem/time - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dakujem/time

ActiveLibrary[Utility & Helpers](/categories/utility)

dakujem/time
============

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

1.1.2(6mo ago)41.5k[1 issues](https://github.com/dakujem/time/issues)BSD-2-ClausePHPPHP ^7.2 || ^8CI passing

Since May 15Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/dakujem/time)[ Packagist](https://packagist.org/packages/dakujem/time)[ RSS](/packages/dakujem-time/feed)WikiDiscussions trunk Synced today

READMEChangelog (7)Dependencies (3)Versions (10)Used By (0)

Time
====

[](#time)

> 💿 `composer require dakujem/time`
>
> 📒 [Changelog](changelog.md)

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`:

```
// negative time values
(string) Time::create('-10:30'); // -10:30:00
(string) Time::create('10:30')->subHours(100); // -89:30:00

// time values exceeding 24 hours
Time::create('50:00:00'); // 50 hours
Time::fromDays(10); // 10 days
```

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
-------

[](#methods)

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

Options to create a time object:

```
// constructor, create, fromSeconds, fromMinutes, fromHours, fromDays, fromWeeks
new Time('12:20') == Time::create('12:20')
Time::fromDays(4)
Time::fromHours(12, 20) == Time::create('12:20') == Time::create(44400) == Time::fromSeconds(44400)
```

Arithmetic methods:

```
// arithmetic methods: add, sub, mult, div, mod
(new Time('12:00'))->add(Time::fromSeconds(17000))->sub(new Time(45))
Time::fromHours(10)->div(2) // 5 hours
```

Comparisons:

```
// comparison methods: lt, lte, gt, gte, eq, neq, between
(new Time('12:00'))->between('12:30', '11:30') // TRUE
```

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

```
// adding values: addSeconds, addMinutes, addHours, addDays, addWeeks
// subtracting values: subSeconds, subMinutes, subHours, subDays, subWeeks
(string) Time::create(123) //  00:02:03
        ->addSeconds(10)   //  00:02:13
        ->addSeconds(-10)  //  00:02:03
        ->subMinutes(-10)  // -00:08:03
```

Conversion options:

```
// conversion options: toSeconds, toMinutes, toHours, toDays, toWeeks
Time::fromWeeks(4)->toSeconds() // 2419200
Time::fromDays(3.5)->toWeeks()  // 0.5
```

Input parsing (reading) and output formatting:

```
// string time parsing (reading)
Time::create('23:59:59')->toSeconds() == TimeHelper::parse('23:59:59')
TimeHelper::parse('-10:30')
Time::create(TimeHelper::parse('10:30 PM', TimeHelper::FORMAT_HMA)) // custom format

// output formatting
(string) Time::create(123)->format(Time::FORMAT_HM); // 00:02 - custom format (HH:mm)
(string) Time::fromHours(2, 3, 4); // 02:03:04 - the default format (HH:mm:ss)
```

Output to other time objects (conversion):

```
// converting to DateTime or Carbon: toDateTime, toCarbon
$carbon = Time::create(123)->toCarbon();
$datetm = Time::create('07:50 AM')->toDateTime();
```

Validating valid day time and clipping to valid day time:

```
// clipping to valid day time
Time::create(-1)->isValidDayTime(); // FALSE
(string) Time::create(-1); // -00:00:01
(string) Time::create(-1)->clipToDayTime(); // 23:59:59
(Time::create('23:59:59'))          // 23:59:59
        ->addSeconds(1)             // 24:00:00
        ->clipToDayTime();          // 00:00:00
```

And there is more!

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

Mutable and Immutable Time objects
----------------------------------

[](#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.

```
$immutable = Time::fromSeconds(0);
// all the operations work as expected:
(string) $immutable->addSeconds(30)->mult(2); // "00:01:00"
// but the instance itself does not change - this is in contrast to the mutable TimeMutable object:
$immutable->getMinutes(); // 0
```

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

```
$mutable = TimeMutable::fromSeconds(0);
(string) $mutable->addSeconds(30)->mult(2); // "00:01:00"
// the modifications are accumulated inside the TimeMutable instance:
$mutable->getMinutes(); // 1
```

`TimeMutable` may be useful for aggregations:

```
$acc = new TimeMutable();
foreach(... as $foo){
    $acc->add($foo->getDuration());
}
print $acc;
```

Parsing time strings and formatting
-----------------------------------

[](#parsing-time-strings-and-formatting)

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

```
Time::create('23:59:59')->sub('12:30')
```

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:

```
$timeFactory = new TimeFactory();
$timeFactory->create('23:59:59')->sub($timeFactory->create('12:30'))
```

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:

```
Time::create(TimeHelper::parse('23:59:59'))->sub(TimeHelper::parse('10:30 PM', TimeHelper::FORMAT_HMA))
```

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...
-----------------------------

[](#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):

```
Time::create(5.500) // 5.5 seconds
```

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
------------

[](#installation)

Use [Composer](https://getcomposer.org/):

`$` `composer require dakujem/time`

Testing
-------

[](#testing)

Run CLI command:

`$` `composer test`

Or open `tests/index.php` in a browser.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance62

Regular maintenance activity

Popularity22

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~584 days

Recently: every ~780 days

Total

7

Last Release

194d ago

Major Versions

0.3 → 1.02018-01-30

PHP version history (2 changes)0.1.0PHP ^5.4 || ^7.0

1.1PHP ^7.2 || ^8

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/443067?v=4)[Andrej Rypo](/maintainers/dakujem)[@dakujem](https://github.com/dakujem)

---

Top Contributors

[![dakujem](https://avatars.githubusercontent.com/u/443067?v=4)](https://github.com/dakujem "dakujem (63 commits)")

---

Tags

utilitytimeutilities

### Embed Badge

![Health badge](/badges/dakujem-time/health.svg)

```
[![Health](https://phpackages.com/badges/dakujem-time/health.svg)](https://phpackages.com/packages/dakujem-time)
```

###  Alternatives

[vaimo/composer-patches

Applies a patch from a local or remote file to any package that is part of a given composer project. Patches can be defined both on project and on package level. Optional support for patch versioning, sequencing, custom patch applier configuration and patch command for testing/troubleshooting added patches.

3014.6M26](/packages/vaimo-composer-patches)[lodash-php/lodash-php

A port of Lodash to PHP

528756.6k5](/packages/lodash-php-lodash-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)