PHPackages                             rasuvaeff/duration - 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. rasuvaeff/duration

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

rasuvaeff/duration
==================

Type-safe immutable duration value object for PHP

v1.0.0(today)00BSD-3-ClausePHPPHP 8.3 - 8.5CI passing

Since Jun 30Pushed todayCompare

[ Source](https://github.com/rasuvaeff/duration)[ Packagist](https://packagist.org/packages/rasuvaeff/duration)[ Docs](https://github.com/rasuvaeff/duration)[ RSS](/packages/rasuvaeff-duration/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (10)Versions (2)Used By (0)

rasuvaeff/duration
==================

[](#rasuvaeffduration)

[![Latest Stable Version](https://camo.githubusercontent.com/b92fae5101ddf74336ebc134166887fc70deebbb6cb214f81cb021325b2cd84d/68747470733a2f2f706f7365722e707567782e6f72672f7261737576616566662f6475726174696f6e2f76)](https://packagist.org/packages/rasuvaeff/duration)[![Total Downloads](https://camo.githubusercontent.com/cc28b68d7f8fdc154633e57792aa88c7cd4df33e7aa323b20447d168e657cb09/68747470733a2f2f706f7365722e707567782e6f72672f7261737576616566662f6475726174696f6e2f646f776e6c6f616473)](https://packagist.org/packages/rasuvaeff/duration)[![Build](https://github.com/rasuvaeff/duration/actions/workflows/build.yml/badge.svg)](https://github.com/rasuvaeff/duration/actions/workflows/build.yml)[![Static analysis](https://github.com/rasuvaeff/duration/actions/workflows/static-analysis.yml/badge.svg)](https://github.com/rasuvaeff/duration/actions/workflows/static-analysis.yml)[![Psalm level](https://camo.githubusercontent.com/68f7f31799f2b93c710b14ba3877072e7fe07ec9d7cee3fdf67e14beab3e1b6f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7073616c6d2d6c6576656c5f312d626c75652e737667)](https://github.com/rasuvaeff/duration/actions/workflows/static-analysis.yml)[![PHP](https://camo.githubusercontent.com/fd97cf7a5f62b1fbf95198535f8d2eb42eb3f57a0d9d570e0d971017ed894e30/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f7261737576616566662f6475726174696f6e2f706870)](https://packagist.org/packages/rasuvaeff/duration)[![License](https://camo.githubusercontent.com/6cb285b57819f8de0acfb34923298f4f569f962544e8fe35331da2d163f4e485/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4253442d2d332d2d436c617573652d626c75652e737667)](LICENSE.md)

Type-safe, immutable, non-negative duration value object for PHP. Replaces bare `int` parameters (seconds? milliseconds?) with an explicit unit, removing a whole class of "seconds vs milliseconds" bugs. Designed as the foundation for timeout, wait and lease parameters across the resilience packages.

> Using an AI coding assistant? [llms.txt](llms.txt) contains a compact API reference you can share with the model.

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

[](#requirements)

- PHP 8.3+
- No runtime dependencies

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

[](#installation)

```
composer require rasuvaeff/duration
```

Usage
-----

[](#usage)

```
use Rasuvaeff\Duration\Duration;

$timeout = Duration::seconds(2.5);

$timeout->toMillis();  // 2500
$timeout->toMicros();  // 2500000
$timeout->toSeconds(); // 2.5

$total = Duration::millis(500)->plus(Duration::seconds(1)); // 1500ms

Duration::seconds(1)->isGreaterThan(Duration::millis(500)); // true

echo Duration::minutes(1.5); // "1.5min"
```

### Factories

[](#factories)

MethodDescription`Duration::zero()`Zero-length duration`Duration::micros(int $micros)`From microseconds`Duration::millis(int $millis)`From milliseconds`Duration::seconds(int|float $seconds)`From seconds (fractional allowed)`Duration::minutes(int|float $minutes)`From minutes (fractional allowed)`Duration::hours(int|float $hours)`From hours (fractional allowed)`Duration::days(int|float $days)`From days (fractional allowed)### Conversions

[](#conversions)

MethodReturnsNotes`toMicros()``int`Exact — microseconds is the storage unit`toMillis()``int`Rounded **up** (`ceil`)`toSeconds()``float``toMinutes()``float``toMillis()` rounds up on purpose: a non-zero sub-millisecond duration must never collapse to `0`, because `0ms` means "no timeout / infinite" to cURL and most HTTP clients — the exact failure a timeout value is meant to prevent.

### Arithmetic & comparison

[](#arithmetic--comparison)

MethodReturnsDescription`plus(Duration $other)``Duration`Sum of two durations`minus(Duration $other)``Duration`Saturating difference — never negative (a passed deadline is `0`)`Duration::min($a, $b)``Duration`Static — the smaller of two durations`Duration::max($a, $b)``Duration`Static — the larger of two durations`isZero()``bool`True when zero-length`isPositive()``bool`True when non-zero`equals(Duration $other)``bool`Equal length`compareTo(Duration $other)``int``-1` / `0` / `1``isGreaterThan(Duration $other)``bool`Strictly longer`isLessThan(Duration $other)``bool`Strictly shorter### String representation

[](#string-representation)

`Duration` implements `Stringable`. Casting to string yields a human-readable form, choosing the largest unit with a value of at least 1:

```
"0"        zero
"1µs"      microseconds (integer)
"250ms"    milliseconds (integer, rounded up — matches toMillis())
"2.5s"     seconds (%g, trailing zeros trimmed)
"1.5min"   minutes
"2h"       hours
"1.5d"     days

```

The unit set, rounding and suffix spelling are an observable contract: changing them is a **major** version bump. For machine-readable values use `toMicros()` / `toMillis()` / `toSeconds()` / `toMinutes()` directly.

Security
--------

[](#security)

Not security-sensitive: a pure, side-effect-free value object. It performs no I/O and holds no secrets. The only enforced contract is the input domain:

- Negative durations throw `InvalidArgumentException` (`Duration cannot be negative`).
- Non-finite floats (`INF` / `NAN`) throw `InvalidArgumentException` (`Duration must be finite`).

Examples
--------

[](#examples)

See [examples/](examples/) for runnable scripts. Examples are expected to execute without fatal errors and stay aligned with the documented public API.

ScriptShowsNeeds server?`basic.php`Factories, conversions, arithmetic, comparisonnoDevelopment
-----------

[](#development)

No PHP/Composer on the host — run in Docker via the `composer:2` image:

```
docker run --rm -v "$PWD":/app -w /app composer:2 composer install
docker run --rm -v "$PWD":/app -w /app composer:2 composer build
docker run --rm -v "$PWD":/app -w /app composer:2 composer cs:fix
docker run --rm -v "$PWD":/app -w /app composer:2 composer test
docker run --rm -v "$PWD":/app -w /app composer:2 composer release-check
```

Or with Make:

```
make install
make build
make cs-fix
make test
make test-coverage
make mutation
make release-check
```

`make test-coverage` and `make mutation` bootstrap `pcov` inside the `composer:2` container because the base image has no coverage driver.

License
-------

[](#license)

[BSD-3-Clause](LICENSE.md)

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 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

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b0812d5572a7041dfe36e222d295b2e6dc55833a605350fcde58a51a5965ed30?d=identicon)[rasuvaeff](/maintainers/rasuvaeff)

---

Top Contributors

[![rasuvaeff](https://avatars.githubusercontent.com/u/1352718?v=4)](https://github.com/rasuvaeff "rasuvaeff (1 commits)")

---

Tags

durationimmutablephpphp-libraryresiliencetimetimeoutvalue-objectValue Objecttimetimeoutimmutableduration

###  Code Quality

Static AnalysisPsalm, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/rasuvaeff-duration/health.svg)

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

###  Alternatives

[knplabs/knp-time-bundle

Making your dates and durations look sensible and descriptive

6239.3M52](/packages/knplabs-knp-time-bundle)[brick/date-time

Date and time library

3623.6M94](/packages/brick-date-time)[aeon-php/calendar

PHP type safe, immutable calendar library

20410.2M16](/packages/aeon-php-calendar)[khill/php-duration

Converts between colon formatted time, human-readable time and seconds

1571.8M20](/packages/khill-php-duration)[sybio/gif-frame-extractor

PHP class that separates all the frames (and their duration) of an animated GIF

179431.1k9](/packages/sybio-gif-frame-extractor)

PHPackages © 2026

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