Oihana Php System

oihana
date

TimeInterval

Helper class to manipulate and format time intervals (durations).

Supports various input formats:

Numeric values (int|float) as seconds
Colon-separated strings: "MM:SS" or "HH:MM:SS"
Human-readable units: "1.5d 3h 15m 12.5s"

Useful for displaying or converting durations to readable forms, such as "2h 5m" or "2:05:00", or for computing the total seconds or minutes.

Basic usage:

$duration = new TimeInterval('7:31');
echo $duration->humanize();         // 7m 31s
echo $duration->formatted();        // 7:31
echo $duration->toSeconds();        // 451
echo $duration->toMinutes();        // 7.5166
echo $duration->toMinutes(null, 0); // 8

With hour/minute/second string:

$duration = new TimeInterval('1h 2m 5s');
echo $duration->humanize();  // 1h 2m 5s
echo $duration->formatted(); // 1:02:05
echo $duration->toSeconds(); // 3725

With days and custom hours/day:

$duration = new TimeInterval('1.5d 1.5h 2m 5s', 6);
echo $duration->humanize();  // 1d 4h 32m 5s
echo $duration->formatted(); // 10:32:05
echo $duration->toMinutes(); // 632.083

Raw seconds:

$duration = new TimeInterval(4293);
echo $duration->humanize() ;  // 1h 11m 33s
echo $duration->formatted() ; // 1:11:33

Tags

Table of Contents

Properties

$days : int|float|null: The whole-day component of the parsed duration.
$hours : int|float|null: The whole-hour component of the parsed duration (after days).
$hoursPerDay : int|null: The number of hours in a single day, used for day↔hour conversions.
$minutes : int|float|null: The whole-minute component of the parsed duration (after hours).
$seconds : int|float|null: The seconds component of the parsed duration (may carry a fractional part).
$daysRegex : string: Regex matching the days component (e.g. `"1.5d"`).
$hoursRegex : string: Regex matching the hours component (e.g. `"3h"`, `"3.5h"`).
$minutesRegex : string: Regex matching the minutes component (e.g. `"15m"`).
$secondsRegex : string: Regex matching the seconds component (e.g. `"12s"`, `"12.5s"`).

Methods

__construct() : mixed: Creates a new TimeInterval instance.
formatted() : string: Returns the duration as a colon-formatted string.
humanize() : string: Returns the duration as a human-readable string.
parse() : self|bool: Parses one of the supported duration forms and updates the instance.
reset() : void: Resets the duration components to zero.
toMinutes() : int|float: Returns the duration as a total number of minutes.
toSeconds() : int|float: Returns the duration as a total number of seconds.

$days

The whole-day component of the parsed duration.


            public private(set)
            int|float|null
    $days
     = 0

Readable from outside, but only mutable from within the class.

$hours

The whole-hour component of the parsed duration (after days).


            public private(set)
            int|float|null
    $hours
     = 0

Readable from outside, but only mutable from within the class.

$hoursPerDay

The number of hours in a single day, used for day↔hour conversions.


            public private(set)
            int|null
    $hoursPerDay
     = 24

Readable from outside, but only mutable from within the class.

$minutes

The whole-minute component of the parsed duration (after hours).


            public private(set)
            int|float|null
    $minutes
     = 0

Readable from outside, but only mutable from within the class.

$seconds

The seconds component of the parsed duration (may carry a fractional part).


            public private(set)
            int|float|null
    $seconds
     = 0.0

Readable from outside, but only mutable from within the class.

$daysRegex

Regex matching the days component (e.g. `"1.5d"`).


        private
            string
    $daysRegex
     = '/(\d+(?:\.\d+)?)\s*d/i'

$hoursRegex

Regex matching the hours component (e.g. `"3h"`, `"3.5h"`).


        private
            string
    $hoursRegex
     = '/(\d+(?:\.\d+)?)\s*h/i'

$minutesRegex

Regex matching the minutes component (e.g. `"15m"`).


        private
            string
    $minutesRegex
     = '/(\d+)\s*m/i'

$secondsRegex

Regex matching the seconds component (e.g. `"12s"`, `"12.5s"`).


        private
            string
    $secondsRegex
     = '/(\d+(?:\.\d+)?)\s*s/i'

__construct()

Creates a new TimeInterval instance.


    public
                    __construct([int|float|string|null $duration = null ][, int $hoursPerDay = 24 ]) : mixed

The $duration parameter can be:

an integer or float representing the duration in seconds,
a string formatted as "HH:MM", "HH:MM:SS", or a string containing time units (e.g. "1h 30m 15s", "2.5d 4h"),
or null for an initial zero duration.

The $hoursPerDay parameter sets the number of hours in a day for calculations involving days (default is 24).

Parameters

$duration : int|float|string|null = null: Initial duration to parse or null for zero.
$hoursPerDay : int = 24: Number of hours per day (used for day-to-hour conversions).

formatted()

Returns the duration as a colon-formatted string.


    public
                    formatted([int|float|string|null $duration = null ][, bool $zeroFill = false ]) : string

For example, one hour and 42 minutes returns "1:42". With $zeroFill set to true:

42 minutes returns "0:42:00"
28 seconds returns "0:00:28"

Note: when $duration is not null, the instance is re-parsed via self::parse() — its internal state is mutated as a side-effect.

Parameters

$duration : int|float|string|null = null: Optional duration to parse before formatting.
$zeroFill : bool = false: Force zero-fill of the hour and minute components.

Return values

string —

The colon-formatted duration string.

humanize()

Returns the duration as a human-readable string.


    public
                    humanize([int|float|string|null $duration = null ]) : string

For example, one hour and 42 minutes returns "1h 42m".

Note: when $duration is not null, the instance is re-parsed via self::parse() — its internal state is mutated as a side-effect.

Parameters

$duration : int|float|string|null = null: Optional duration to parse before formatting.

Return values

string —

The human-readable duration string (e.g. "1d 2h 3m 4s").

parse()

Parses one of the supported duration forms and updates the instance.


    public
                    parse(int|float|string|null $duration) : self|bool

Supported forms:

null → returns false (no-op other than self::reset()).
Numeric (int|float) → interpreted as a total number of seconds.
Colon-separated string "MM:SS" or "HH:MM:SS".
Unit-suffixed string "1.5d 3h 15m 12.5s" (any subset, any order).

The instance is self::reset() before being populated. On success the instance itself is returned (fluent style); on failure false is returned and the instance is left in its reset state.

Parameters

$duration : int|float|string|null: The duration to parse.

Return values

self|bool —

The instance on success, or false if the input cannot be parsed.

reset()

Resets the duration components to zero.


    public
                    reset() : void

The self::$hoursPerDay setting is preserved.

toMinutes()

Returns the duration as a total number of minutes.


    public
                    toMinutes([int|float|string|null $duration = null ][, int|bool $precision = false ]) : int|float

For example, one hour and 42 minutes returns 102.

Note: when $duration is not null, the instance is re-parsed via self::parse() — its internal state is mutated as a side-effect.

Parameters

$duration : int|float|string|null = null: Optional duration to parse before computing.
$precision : int|bool = false: Number of decimal digits to round to; false to skip rounding, true is equivalent to 0.

Return values

int|float —

The total number of minutes (rounded according to $precision).

toSeconds()

Returns the duration as a total number of seconds.


    public
                    toSeconds([int|float|string|null $duration = null ][, int|bool $precision = false ]) : int|float

For example, one hour and 42 minutes returns 6120.

Note: when $duration is not null, the instance is re-parsed via self::parse() — its internal state is mutated as a side-effect.

Parameters

$duration : int|float|string|null = null: Optional duration to parse before computing.
$precision : int|bool = false: Number of decimal digits to round to; false to skip rounding.

Return values

int|float —

The total number of seconds (rounded according to $precision).