dev

.github/workflows/phpunit.yml

@@ -2,9 +2,9 @@ name: PHP Tests
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, dev ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, dev ]
 
 jobs:
   tests:
@@ -27,4 +27,6 @@ jobs:
         run: composer install --prefer-dist --no-progress --no-interaction
 
       - name: Run Tests
-        run: vendor/bin/phpunit --coverage-text --colors=never
+        env:
+          XDEBUG_MODE: coverage
+        run: vendor/bin/phpunit --colors=never --coverage-text

.gitignore

@@ -2,3 +2,4 @@ vendor
 .idea
 composer.lock
 *.cache
+coverage

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayup Creative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

composer.json

@@ -20,5 +20,9 @@
         "phpunit/phpunit": "^10.0",
         "nesbot/carbon": "^3.0",
         "illuminate/database": "^10.0|^11.0"
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit",
+        "test-coverage": "vendor/bin/phpunit --coverage-html coverage"
     }
 }

phpunit.xml

@@ -1,17 +1,31 @@
-<?xml version="1.0"?>
-<phpunit bootstrap="vendor/autoload.php" colors="true">
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="depends,defects"
+         beStrictAboutCoverageMetadata="true"
+         beStrictAboutOutputDuringTests="true"
+         colors="true"
+
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerErrors="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         displayDetailsOnPhpunitDeprecations="true"
+>
     <testsuites>
-        <testsuite name="Duration">
+        <testsuite name="default">
             <directory>tests</directory>
         </testsuite>
     </testsuites>
 
-    <coverage processUncoveredFiles="true">
+    <source>
         <include>
-            <directory>./src</directory>
+            <directory>src</directory>
         </include>
         <exclude>
-            <directory>./tests</directory>
+            <directory>vendor</directory>
         </exclude>
-    </coverage>
+    </source>
 </phpunit>

readme.md

@@ -0,0 +1,161 @@
+# 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://img.shields.io/packagist/v/ayup-creative/duration.svg?style=flat-square)](https://packagist.org/packages/ayup-creative/duration)
+[![Total Downloads](https://img.shields.io/packagist/dt/ayup-creative/duration.svg?style=flat-square)](https://packagist.org/packages/ayup-creative/duration)
+[![License](https://img.shields.io/packagist/l/ayup-creative/duration.svg?style=flat-square)](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
+
+You can install the package via composer:
+
+```bash
+composer require ayup-creative/duration
+```
+
+## Usage
+
+The package provides two main classes: `Duration` (mutable) and `DurationImmutable` (immutable).
+
+### Creation
+
+```php
+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
+
+You can access the total time in various units:
+
+```php
+$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:
+
+```php
+$duration = DurationImmutable::make(hours: 1, minutes: 30, seconds: 15);
+
+$duration->getHours();   // 1
+$duration->getMinutes(); // 30
+$duration->getSeconds(); // 15
+```
+
+### Arithmetic
+
+```php
+$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
+
+```php
+$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
+
+```php
+$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)
+
+While `Duration` and `DurationImmutable` are always positive (clamped to 0), `TimeDelta` allows for negative durations, perfect for representing differences.
+
+```php
+use AyupCreative\Duration\TimeDelta;
+
+$delta = new TimeDelta(-3600); // -1 hour
+
+$delta->isNegative(); // true
+$delta->absolute();   // Returns DurationImmutable of 1 hour
+```
+
+### Laravel Support
+
+The package includes Eloquent casts for easy integration with your models.
+
+```php
+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
+
+```bash
+vendor/bin/phpunit
+```
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE) for more information.