🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

TimeSpan — nanosecond-precision duration

Purpose

Immutable duration value object: 64-bit nanoseconds, exact arithmetic with overflow control, parsing of ISO 8601, 1h 30m and PHP relative strings.

What for and how to use

Timeouts, intervals, delay configuration: TimeSpan::fromString('1h 30m'), ->plus(), ->compareTo(), ->toIso8601(), ->toDateInterval(), human-readable — ->forHumans('en', 2) (“1 hour 30 minutes”).

Example

$span = TimeSpan::fromString('1h 30m')->plus(TimeSpan::ofSeconds(15.5));
$span->seconds();        // 5415.5
$span->toIso8601();      // PT1H30M15.5S
TimeSpan::between($start, $end);   // from a pair of moments
TimeSpan::fromIso8601('P2DT3H');

Anti-patterns

Calendar years/months are deliberately rejected (their duration is ambiguous): TimeSpan is an exact nanosecond duration. For calendar month/year arithmetic use CalendarDate (addMonthsNoOverflow(), addYears()).

Lifecycle

flowchart TD
    A[ofSeconds/ofHours/...] --> S((TimeSpan ns))
    B[fromIso8601 / fromString / fromDateString] --> S
    C[between / fromDateInterval] --> S
    S --> D[plus/minus/multipliedBy/dividedBy]
    D --> S
    S --> E[seconds()/toIso8601()/toDateInterval()]

Feature comparison with competitors

Aspect	🏆 CloudCastle	symfony	carbon	lcobucci	beste	ergebnis
Nanosecond storage precision	✅	❌	❌	❌	❌	❌
Integer overflow control	✅	❌	❌	❌	❌	❌
Parsing ISO 8601 and human strings	✅	❌	✅	❌	❌	❌
Immutable arithmetic	✅	❌	✅	❌	❌	❌
Rejecting ambiguous months/years	✅	❌	❌	❌	❌	❌
Human-readable `forHumans()` in 6 languages	✅	❌	✅	❌	❌	❌
Total	🏆 6	0	3	0	0	0

← Back to the feature list

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano