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

v1.0.0(2mo ago)0207MITPHPPHP >=8.3CI passing

Since Apr 15Pushed 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 3w ago

READMEChangelog (1)Dependencies (3)Versions (3)Used By (0)

Duration
========

[](#duration)

[![PHP Tests](https://github.com/Ayup-Creative/php-duration/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/Ayup-Creative/php-duration/actions/workflows/ci-cd.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));

// From a string (similar to Carbon::parse)
$duration = DurationImmutable::parse('1h 30m');
$duration = DurationImmutable::parse('2 days');
$duration = DurationImmutable::parse('PT1H30M');
```

### 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)

// JSON Serialization
$json = json_encode($duration);
/*
{
    "seconds": 5400,
    "human": "1 hour 30 minutes",
    "short_human": "1h 30m",
    "formatted": "01:30",
    "iso8601": "PT1H30M"
}
*/
```

### 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
```

Development
-----------

[](#development)

This package uses [pre-commit](https://pre-commit.com/) to maintain code quality. To set up your local development environment:

1. Install pre-commit: `pip install pre-commit` (or your preferred method)
2. Install the git hooks: `pre-commit install --hook-type pre-commit --hook-type commit-msg`

The hooks will automatically run PHPUnit and validate your commit messages against [Conventional Commits](https://www.conventionalcommits.org/).

Testing
-------

[](#testing)

```
vendor/bin/phpunit
```

License
-------

[](#license)

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

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance86

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 94.7% 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

69d ago

### 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 (36 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

duration-parserduration-parsingphp

###  Code Quality

TestsPHPUnit

### 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)
```

###  Alternatives

[axllent/silverstripe-analytics-js

Google Universal Analytics tracking code for Silverstripe

1621.3k](/packages/axllent-silverstripe-analytics-js)[magepow/cancelorder

Customer Cancel Order magento2

122.0k](/packages/magepow-cancelorder)

PHPackages © 2026

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