PHPackages                             vdhicts/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. vdhicts/time

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

vdhicts/time
============

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

v6.0.0(1y ago)14.6kMITPHPPHP ^8.1CI passing

Since Jan 6Pushed 2mo agoCompare

[ Source](https://github.com/vdhicts/time)[ Packagist](https://packagist.org/packages/vdhicts/time)[ Docs](https://github.com/vdhicts/time)[ RSS](/packages/vdhicts-time/feed)WikiDiscussions main Synced 2mo ago

READMEChangelog (8)Dependencies (4)Versions (8)Used By (0)

Time
====

[](#time)

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

[](#requirements)

This package requires PHP 8.1 or higher.

Installation
------------

[](#installation)

You can install the package via composer:

`composer require vdhicts/time`

Usage
-----

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

[](#time-1)

The `Time` object can be initiated with:

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

#### Building from input

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

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

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

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

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

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

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

[](#comparison-1)

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

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

[](#contribution)

Any contribution is welcome, but it should meet the [PER 2.0 code style](https://www.php-fig.org/per/coding-style/) and please create one pull request per feature/bug. In exchange, you will be credited as contributor.

Security
--------

[](#security)

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

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)

###  Health Score

45

—

FairBetter than 93% of packages

Maintenance64

Regular maintenance activity

Popularity21

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity74

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 ~340 days

Recently: every ~265 days

Total

7

Last Release

643d ago

Major Versions

1.1.0 → 2.0.02021-09-14

2.0.0 → 3.0.02022-02-06

3.0.0 → v4.0.02022-03-23

v4.0.0 → v5.0.02022-05-20

v5.0.0 → v6.0.02024-08-13

PHP version history (5 changes)1.0.0PHP ^7.1

2.0.0PHP ^7.4

3.0.0PHP ^7.4 || ^8.0

v4.0.0PHP ^8.0

v6.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/88d23e7b707d1cfe0eea91c00590613f45e0c75cb0a3ce89354328332e5c0c02?d=identicon)[vdhicts](/maintainers/vdhicts)

---

Top Contributors

[![dvdheiden](https://avatars.githubusercontent.com/u/90568118?v=4)](https://github.com/dvdheiden "dvdheiden (36 commits)")

---

Tags

phptime

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StyleECS

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[obliviousharmony/vscode-phpcs-integration

The custom PHPCS integration for the obliviousharmony.vscode-php-codesniffer VS Code extension.

426.4k](/packages/obliviousharmony-vscode-phpcs-integration)

PHPackages © 2026

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