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

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

vascowhite/time
===============

A class to deal with operations on times independent of date.

v1.1.0(9y ago)1261GPL-3.0PHPPHP >=5.5.0

Since Dec 13Pushed 7y ago1 watchersCompare

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

READMEChangelogDependencies (1)Versions (5)Used By (0)

Moved to

Time
====

[](#time)

[![Build Status](https://camo.githubusercontent.com/3873b3c224418d1be7982b52d57438a46731bf99500a355e3920360d66f7d0eb/68747470733a2f2f7472617669732d63692e6f72672f766173636f77686974652f54696d652e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/vascowhite/Time)

Introduction
------------

[](#introduction)

This is a class for dealing with times.

This [time data type](http://www.hackcraft.net/web/datetime/#time) represents a period of time. It is expressed in the format 'H:i:s' (a left truncation of the representation of datetime). It is the elapsed time that would be measured on a stop watch that is unaware of date, time zones or DST.

PHP's native `\DatePeriod` is excellent for representing a time period of any length, however it does not lend itself to manipulating time periods or performing calculations with them. Hence, this class was born. Its scope has been limited to hours, minutes and seconds for now as this allows for accurate manipulation without worrying about DST, etc., the `DateTime` classes already have that well covered.

This class can add, subtract, average, sum and compare times. It will also convert a `\DateInterval` object to a `TimeValue` and a `TimeValue` object into a `\DateInterval` object.

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

[](#installation)

Install using composer, add the following to composer.json:-

```
"require": {
    "vascowhite/time": "1.1.0"
}
```

Other methods of installation are possible, but not supported.

Requirements
------------

[](#requirements)

Requires PHP >= 5.5.0

---

### TimeValue

[](#timevalue)

This is an **immutable** class that represents a time data type. It knows nothing about dates, if you need times associated with dates, then PHP's [`\DateTime`](http://php.net/datetime) Classes are what you are looking for.

There are various methods available for manipulating and comparing `TimeValue` objects.

`TimeValue` objects implement the `__toString()` magic method, so can be echoed etc..

---

#### TimeValue::\_\_construct()

[](#timevalue__construct)

**Signature:-**

```
TimeValue __construct(String $time, String $format = 'H:i:s')
```

**Arguments**

`$time` is a string representing a period of time. For example one hour, sixteen minutes and thirty seconds would be represented thus: '01:16:30'.

`$format` Optional format string, defaults to 'H:i:s'. Available formats are 'H:i:s', 'H', 'i', or 's'.

The following are examples of valid formats:-

```
new TimeValue('12:15:20'); // 12 hours 15 minutes 20 seconds
new TimeValue('12', 'H'); // 12 hours 0 minutes 0 seconds
new TimeValue('12:15', 'H:i'); // 12 hours 15 minutes
new TimeValue('12:15', 'i:s'); // 12 minutes 15 seconds
new TimeValue('20', 's'); // 20 seconds.
```

Although the formats are specified none of the fields are limited to 2 digits. The following are also valid:-

```
new TimeValue('120:150:200'); // 120 hours 150 minutes 200 seconds Will output '122:33:20'
new TimeValue('00:00:36000'); // 36000 seconds. Will output '10:00:00'
```

**Return**Returns a `TimeValue` object.

---

#### TimeValue::getSeconds()

[](#timevaluegetseconds)

**Signature**

```
Int getSeconds();
```

**Arguments**

None.

**Return**Returns an integer representing the number of seconds that the `TimeValue` spans.

**Example**

```
$time = new TimeValue('00:10:10');
echo $time->getSeconds; // Output 610
```

---

### TimeValue::getTime()

[](#timevaluegettime)

**Signature**

```
String getTime()
```

**Arguments**

None.

**Return**

Returns a string representing the time in the format 'H:i:s'. The 'H' portion will expand to the required number of digits to represent the hour.

**Example**

```
$time = new TimeValue('00:00:36000');
echo $time->getTime(); // Output "10:00:00"
```

---

### TimeValue::add()

[](#timevalueadd)

**Signature**

```
TimeValue add(TimeValue)
```

**Arguments**

The `TimeValue` to be added.

**Return**

Returns a `TimeValue` object set to the appropriate number of seconds.

**Example**

```
$time = new TimeValue('01:00:00');
echo $time->add(new TimeValue('30', 'i'); // Output "01:30:00"
```

---

### TimeValue::sub()

[](#timevaluesub)

**Signature**

```
TimeValue sub(TimeValue)
```

**Arguments**

The `TimeValue` to be subtracted.

**Return**

Returns a `TimeValue` object set to the appropriate number of seconds.

**Example**

```
$time = new TimeValue('01:00:00');
echo $time->sub(new TimeValue('00:30'); // Output "00:30:00"
```

---

### TimeValue::average()

[](#timevalueaverage)

**Signature**

```
TimeValue average(TimeValues[])
```

**Arguments**

An array of `TimeValue` objects.

**Return**

Returns a `TimeValue` object set to the average number of seconds of the `TimeValue` objects in the supplied array.

**Example**

```
$timeValue1 = new TimeValue('00:20:00'); //1200 seconds
$timeValue2 = new TimeValue('00:10:00'); //600 seconds
$timeValue3 = new TimeValue('00:30:00'); //1800 seconds
$average = TimeValue::average([$timeValue1, $timeValue2, $timeValue3]);
echo $average->getSeconds(); //Output = 1200
```

---

### TimeValue::sum()

[](#timevaluesum)

**Signature**

```
TimeValue sum(TimeValues[])
```

**Arguments**

An array of `TimeValue` objects.

**Return**

Returns a `TimeValue` object set to the sum the `TimeValue` objects in the supplied array.

**Example**

```
$timeValue1 = new TimeValue('00:20:00'); //1200 seconds
$timeValue2 = new TimeValue('00:10:00'); //600 seconds
$timeValue3 = new TimeValue('00:30:00'); //1800 seconds
$sum = TimeValue::sum([$timeValue1, $timeValue2, $timeValue3]);
echo $sum->getSeconds(); //Output = 3600
```

---

### TimeValue::createFromDateInterval()

[](#timevaluecreatefromdateinterval)

**Signature**

```
TimeValue createFromDateInterval(\DateInterval, bool)
```

**Arguments**

A `\DateInterval` object. A Boolean value. If true the returned `\DateInterval` object will represent a negative value. Defaults to false.

**Return**

Returns a `TimeValue` object set to the number of seconds represented by the `\DateInterval` object.

**Example**

```
$interval = new \DateInterval('P1Y1M6DT14H12M6S');
$timeValue = TimeValue::createFromDateInterval($interval); //34783926 seconds
```

---

### TimeValue::toDateInterval()

[](#timevaluetodateinterval)

**Signature**

```
TimeValue||Bool toDateInterval()
```

**Arguments**

None.

**Return**

Returns a `\DateInterval` object with all fields set as if created by `\DateTime::diff()`. Returns `false` if the conversion fails.

**Example**

```
$timeValue = new TimeValue('34783926', 's');
var_dump($timeValue);
/*
Output
object(DateInterval)[2]
   public 'y' => int 1
   public 'm' => int 1
   public 'd' => int 6
   public 'h' => int 14
   public 'i' => int 12
   public 's' => int 6
   public 'weekday' => int 0
   public 'weekday_behavior' => int 0
   public 'first_last_day_of' => int 0
   public 'invert' => int 0
   public 'days' => int 402
   public 'special_type' => int 0
   public 'special_amount' => int 0
   public 'have_weekday_relative' => int 0
   public 'have_special_relative' => int 0
*/
```

---

### TimeValue::format()

[](#timevalueformat)

**Signature**

```
string format(string)
```

**Arguments**

A string representing the desired format. Uses same formatting as [`\DateInterval::format()`](http://php.net/manual/en/dateinterval.format.php)

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 84.4% 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 ~521 days

Total

4

Last Release

2602d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/22130051017ac7053fbf5dd94d944ec0e73d7c065dd62ca657e6fc2dd7c5639e?d=identicon)[vascowhite](/maintainers/vascowhite)

---

Top Contributors

[![vascowhite](https://avatars.githubusercontent.com/u/874109?v=4)](https://github.com/vascowhite "vascowhite (81 commits)")[![ecoralic](https://avatars.githubusercontent.com/u/73831203?v=4)](https://github.com/ecoralic "ecoralic (11 commits)")[![Glavic](https://avatars.githubusercontent.com/u/2729571?v=4)](https://github.com/Glavic "Glavic (4 commits)")

---

Tags

timecalculationsperiods

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[symfony/clock

Decouples applications from the system clock

430168.9M205](/packages/symfony-clock)[knplabs/knp-time-bundle

Making your dates and durations look sensible and descriptive

6308.9M39](/packages/knplabs-knp-time-bundle)[league/period

Time range API for PHP

7335.4M21](/packages/league-period)[wapmorgan/morphos

A morphological solution for Russian and English language written completely in PHP. Provides classes to inflect personal names, geographical names, decline and pluralize nouns, generate cardinal and ordinal numerals, spell out money amounts and time.

8351.3M7](/packages/wapmorgan-morphos)[brick/date-time

Date and time library

3623.3M61](/packages/brick-date-time)[aeon-php/calendar

PHP type safe, immutable calendar library

2079.7M16](/packages/aeon-php-calendar)

PHPackages © 2026

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