README

Convert seconds into human-readable duration strings.

Requirements

• 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'),
);

Parsing Durations

use PhilipRehberger\HumanDuration\Duration;

// Shorthand
$duration = Duration::parse('1h 30m 15s'); // 5415 seconds

// Verbose
$duration = Duration::parse('2 hours, 45 minutes'); // 9900 seconds

// Decimal
$duration = Duration::parse('1.5h'); // 5400 seconds

// With days
$duration = Duration::parse('1d 2h'); // 93600 seconds

// ISO 8601
$duration = Duration::fromIso('PT1H30M15S'); // 5415 seconds
$duration = Duration::fromIso('P1DT2H');     // 93600 seconds

// Convert to ISO 8601
$duration->toIso(); // "PT1H30M15S"

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

Comparing and Combining Durations

$a = Duration::fromMinutes(90);
$b = Duration::fromHours(1);

$a->isGreaterThan($b); // true
$a->isLessThan($b);    // false
$a->equals($b);        // false

$a->add($b)->toHuman();      // "2h 30m"
$a->subtract($b)->toHuman(); // "30m"

Proportional Calculations

$duration = Duration::fromMinutes(90);

// Get 25% of a duration
$quarter = $duration->percentage(25);
$quarter->totalSeconds(); // 1350 (22.5 minutes)

// Get a fraction of a duration
$third = $duration->fraction(1, 3);
$third->totalSeconds(); // 1800 (30 minutes)

Negative Durations

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

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

API

Development

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

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT