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

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

ayup-creative/duration
======================

Carbon-style mutable and immutable Duration value objects with Laravel support

018↓100%PHPCI passing

Since Mar 4Pushed 2mo agoCompare

[ Source](https://github.com/Ayup-Creative/php-duration)[ Packagist](https://packagist.org/packages/ayup-creative/duration)[ RSS](/packages/ayup-creative-duration/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

Duration
========

[](#duration)

[![PHP Tests](https://github.com/Ayup-Creative/php-duration/actions/workflows/phpunit.yml/badge.svg)](https://github.com/Ayup-Creative/php-duration/actions/workflows/phpunit.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/ca068b9082d2e6220a92d942b21c9d9330d5ed47fd151adbcf3efb8ee89c6fb1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f617975702d63726561746976652f6475726174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ayup-creative/duration)[![Total Downloads](https://camo.githubusercontent.com/ad3e2d52a8d7f540ba8e78d1abfd3b9e560c55662cd356275203b945a7e0ea19/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f617975702d63726561746976652f6475726174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ayup-creative/duration)[![License](https://camo.githubusercontent.com/3d09a1f9c9505d9e4800f5eaee4ccf8b585da2a67f044637e8367da882f17d20/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f617975702d63726561746976652f6475726174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ayup-creative/duration)

Carbon-style mutable and immutable Duration value objects with Laravel support. This package provides a simple way to handle durations of time (hours, minutes, seconds) without the complexity of dates.

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

[](#installation)

You can install the package via composer:

```
composer require ayup-creative/duration
```

Usage
-----

[](#usage)

The package provides two main classes: `Duration` (mutable) and `DurationImmutable` (immutable).

### Creation

[](#creation)

```
use AyupCreative\Duration\DurationImmutable;

// From various units
$duration = DurationImmutable::seconds(100);
$duration = DurationImmutable::minutes(5);
$duration = DurationImmutable::hours(2);
$duration = DurationImmutable::days(1);
$duration = DurationImmutable::weeks(1);
$duration = DurationImmutable::months(1); // 30.44 days
$duration = DurationImmutable::years(1);  // 365.25 days

// Combined
$duration = DurationImmutable::make(days: 1, hours: 2, minutes: 3, seconds: 4);
$duration = DurationImmutable::hoursAndMinutes(1, 30);

// From Carbon
$duration = DurationImmutable::fromCarbon(\Carbon\CarbonInterval::hours(2));
```

### Accessing Units

[](#accessing-units)

You can access the total time in various units:

```
$duration = DurationImmutable::hours(2);

$duration->totalSeconds(); // 7200
$duration->totalMinutes(); // 120 (int)
$duration->toMinutes();    // 120.0 (float)
$duration->totalHours();   // 2

// Or via magic properties
$duration->totalSeconds; // 7200
$duration->totalMinutes; // 120
```

You can also get the individual parts of a decomposed duration:

```
$duration = DurationImmutable::make(hours: 1, minutes: 30, seconds: 15);

$duration->getHours();   // 1
$duration->getMinutes(); // 30
$duration->getSeconds(); // 15
```

### Arithmetic

[](#arithmetic)

```
$d1 = DurationImmutable::minutes(30);
$d2 = DurationImmutable::minutes(15);

$result = $d1->add($d2);      // 45 minutes
$result = $d1->sub($d2);      // 15 minutes
$result = $d1->multiply(2);   // 60 minutes

// Ceiling operations
$duration = DurationImmutable::seconds(65);
$duration->ceilToMinutes(1); // 120 seconds
$duration->ceilTo(30);       // 90 seconds
```

### Comparisons

[](#comparisons)

```
$d1 = DurationImmutable::minutes(30);
$d2 = DurationImmutable::minutes(60);

$d1->isLessThan($d2);          // true
$d1->isGreaterThan($d2);       // false
$d1->equals($d2);              // false
$d1->isZero();                 // false
$d1->max($d2);                 // returns $d2
```

### Formatting & Humanization

[](#formatting--humanization)

```
$duration = DurationImmutable::make(days: 1, hours: 2, minutes: 3, seconds: 4);

// Custom format
$duration->format('dd:hh:mm:ss'); // "01:02:03:04"
$duration->format('d:h:m:s');    // "1:2:3:4"

// Human readable
$duration->toHuman();      // "1 day 2 hours"
$duration->toShortHuman(); // "1d 2h 3m"

// String conversion
(string) $duration; // "02:03" (hh:mm)
```

### TimeDelta (Negative Durations)

[](#timedelta-negative-durations)

While `Duration` and `DurationImmutable` are always positive (clamped to 0), `TimeDelta` allows for negative durations, perfect for representing differences.

```
use AyupCreative\Duration\TimeDelta;

$delta = new TimeDelta(-3600); // -1 hour

$delta->isNegative(); // true
$delta->absolute();   // Returns DurationImmutable of 1 hour
```

### Laravel Support

[](#laravel-support)

The package includes Eloquent casts for easy integration with your models.

```
use AyupCreative\Duration\Casts\Seconds;
use AyupCreative\Duration\Casts\Minutes;
use AyupCreative\Duration\Casts\Hours;
use AyupCreative\Duration\Casts\Days;
use Illuminate\Database\Eloquent\Model;

class Task extends Model
{
    protected $casts = [
        'duration_in_seconds' => Seconds::class,
        'estimate_in_hours'   => Hours::class,
    ];
}

$task = Task::find(1);
$task->duration_in_seconds; // Returns DurationImmutable instance
```

Testing
-------

[](#testing)

```
vendor/bin/phpunit
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

22

—

LowBetter than 23% of packages

Maintenance61

Regular maintenance activity

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/494de8188ad97403b72e40e385235a74ef6331aa2710b3727193f646189af9fc?d=identicon)[mykemeynell](/maintainers/mykemeynell)

---

Top Contributors

[![mykemeynell](https://avatars.githubusercontent.com/u/1590190?v=4)](https://github.com/mykemeynell "mykemeynell (21 commits)")

### Embed Badge

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

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

PHPackages © 2026

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