philiprehberger/php-human-duration

Convert seconds into human-readable duration strings

v1.0.2 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• time
• human
• format
• duration
• readable

README

Convert seconds into human-readable duration strings.

Requirements

Dependency	Version
PHP	^8.2

Installation

composer require philiprehberger/php-human-duration

Usage

Creating Durations

use PhilipRehberger\HumanDuration\Duration;

// From seconds
$duration = Duration::fromSeconds(3665);

// From minutes
$duration = Duration::fromMinutes(90);

// From hours
$duration = Duration::fromHours(2.5);

// From the difference between two dates
$duration = Duration::between(
    new DateTimeImmutable('2026-01-01 08:00:00'),
    new DateTimeImmutable('2026-01-01 09:30:00'),
);

Formatting Durations

$duration = Duration::fromSeconds(3665);

$duration->toHuman();   // "1h 1m 5s"
$duration->toVerbose(); // "1 hour, 1 minute, 5 seconds"
$duration->toCompact(); // "1:01:05"

// Stringable — casting to string uses toHuman()
echo $duration; // "1h 1m 5s"

Accessing Raw Values

$duration = Duration::fromSeconds(5400);

$duration->totalSeconds(); // 5400
$duration->totalMinutes(); // 90.0
$duration->totalHours();   // 1.5

Negative Durations

$duration = Duration::fromSeconds(-65);

$duration->toHuman();   // "-1m 5s"
$duration->toVerbose(); // "-1 minute, 5 seconds"
$duration->toCompact(); // "-1:05"

API

Method	Return	Description
Duration::fromSeconds(int $seconds)	Duration	Create from seconds
Duration::fromMinutes(int|float $minutes)	Duration	Create from minutes
Duration::fromHours(int|float $hours)	Duration	Create from hours
Duration::between(DateTimeInterface $start, DateTimeInterface $end)	Duration	Create from date difference
toHuman()	string	Compact format: 1h 5m 30s
toVerbose()	string	Verbose format: 1 hour, 5 minutes, 30 seconds
toCompact()	string	Clock format: 1:05:30
totalSeconds()	int	Total seconds
totalMinutes()	float	Total minutes
totalHours()	float	Total hours

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

License

MIT