Initial commit

.editorconfig

@@ -0,0 +1,16 @@
+# editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.neon]
+indent_style = tab

.gitattributes

@@ -0,0 +1,11 @@
+*.php diff=php
+
+/.editorconfig export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.php_cs.dist export-ignore
+/.travis.yml export-ignore
+
+/phive.xml export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore

.gitignore

@@ -0,0 +1,8 @@
+/build
+/vendor
+
+/.php_cs
+/.php_cs.cache
+/composer.lock
+/phpstan.neon
+/phpunit.xml

.php_cs.dist

@@ -0,0 +1,16 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()
+    ->in(['src', 'tests']);
+
+return PhpCsFixer\Config::create()
+    ->setUsingCache(true)
+    ->setRules([
+        '@Symfony' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'header_comment' => ['header' => ''],
+        'ordered_imports' => true,
+        'phpdoc_align' => false,
+        'phpdoc_order' => true,
+    ])
+    ->setFinder($finder);

.travis.yml

@@ -0,0 +1,21 @@
+language: php
+sudo: false
+
+php:
+    - 7.1
+    - 7.2
+    - 7.3
+    - nightly
+
+matrix:
+    fast_finish: true
+    allow_failures:
+        - php: nightly
+
+cache:
+    directories:
+        - $HOME/.composer/cache
+
+install: composer update --no-interaction --no-suggest --no-progress
+
+script: composer test-ci

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+Initial release

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Jérôme Gamez, https://github.com/jeromegamez <jerome@gamez.name>
+
+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.

README.md

@@ -0,0 +1,144 @@
+# Duration for PHP
+
+Working with durations made easy.
+
+[![Current version](https://img.shields.io/packagist/v/gamez/duration.svg)](https://packagist.org/packages/gamez/duration)
+[![Supported PHP version](https://img.shields.io/packagist/php-v/gamez/duration.svg)]()
+[![Build Status](https://travis-ci.com/jeromegamez/duration-php.svg?branch=master)](https://travis-ci.com/jeromegamez/duration-php)
+
+Do you like to use `DateTimeInverval` to compute and work with durations? Me neither, so let's fix that!
+
+* [Installation](#installation)
+* [Reference](#reference)
+  * [Supported Input Values](#supported-input-values)
+  * [Transformations](#transformations)
+  * [Comparisons](#comparisons)
+  * [Operations](#operations)
+* [Extending `Gamez\Duration`](#extending-gamezduration)
+* [Roadmap](#roadmap)
+
+---
+
+## Installation
+
+You can install the package with [Composer](https://getcomposer.org):
+
+```bash
+composer install gamez/duration
+```
+
+You can then use Duration:
+
+```php
+<?php
+require 'vendor/autoload.php';
+
+use Gamez\Duration;
+
+$duration = Duration::make('13 minutes 37 seconds');
+```
+
+---
+
+## Reference
+
+### Supported input values
+
+#### DateIntervals
+
+```php
+Duration::make(P13M37S');
+Duration::make(new DateInterval('P13M37S'));
+```
+
+#### Colon notation
+
+```php
+Duration::make('13:37'); // minutes:seconds
+Duration::make('13:37:37'); // hours:minutes:seconds
+```
+
+#### Textual notation
+
+A textual notation is any value that can be processed by 
+[DateInterval::createFromDateString()](https://secure.php.net/manual/en/dateinterval.createfromdatestring.php)
+
+```php
+Duration::make('13 minutes 37 seconds');
+```
+
+### Transformations
+
+When transformed, a Duration will be
+
+* converted to a DateInterval representation
+* optimized in the sense that an input value of 60 seconds would result in an output value of "1 minute", 
+  for example "PT60S" would be converted to "PT1H"
+
+```php
+$duration = Duration::make('8 days 29 hours 77 minutes');
+
+echo (string) $duration; // P9DT6H17M
+echo json_encode($duration); // "P9DT6H17M"
+echo get_class($duration->toDateInterval()); // DateInterval
+```
+
+### Comparisons
+
+```php
+$oneSecond = Duration::make('1 second');
+$sixtySeconds = Duration::make('60 seconds');
+$oneMinute = Duration::make('1 minute');
+$oneHour = Duration::make('1 hour');
+
+$oneSecond->isSmallerThan($oneMinute); // true
+$oneHour->isLargerThan($oneMinute); // true
+$oneMinute->equals($sixtySeconds); // true
+
+$durations = [$oneMinute, $oneSecond, $oneHour, $sixtySeconds];
+```
+
+### Operations
+
+Results will always be rounded by the second.
+
+```php
+$thirty = Duration::make('30 seconds');
+
+echo $thirty->withAdded('31 seconds'); // PT1M1S
+echo $thirty->withSubtracted('29 seconds'); // PT1S
+echo $thirty->multipliedBy(3); // PT1M30S
+echo $thirty->dividedBy(2.5); // PT12S
+
+$thirty->multipliedBy(-1); // InvalidArgumentException
+$thirty->withSubtracted('31 seconds'); // InvalidArgumentException
+```
+
+---
+
+## Extending `Gamez\Duration`
+
+Are you missing a feature in the `Gamez\Duration` class? Please consider making a
+pull request if you think others would benefit from this feature as well.
+
+Otherwise, you can dynamically add methods to the class with the help of 
+[spatie/macroable](https://github.com/spatie/macroable):
+
+```php
+Duration::macro('shuffle', function () {
+    return str_shuffle((string) $this);
+});
+
+$duration = Duration::make('30 seconds');
+echo $duration->shuffle(); // This doesn't make sense
+```
+
+---
+
+## Roadmap
+
+* Support more input formats
+* Add "output for humans" (like colon notation)
+* Support flags to configure the handling of edge cases (e.g. negative operation results)
+* ...
+

composer.json

@@ -0,0 +1,46 @@
+{
+    "name": "gamez/duration",
+    "description": "Working with durations made easy",
+    "keywords": ["duration", "time"],
+    "license": "MIT",
+    "homepage": "https://github.com/jeromegamez/duration-php",
+    "authors": [
+        {
+            "name": "Jérôme Gamez",
+            "homepage": "https://github.com/jeromegamez"
+        }
+    ],
+    "require": {
+        "php": "^7.1",
+        "spatie/macroable": "^1.0"
+    },
+    "require-dev": {
+        "phpstan/phpstan": "^0.11.1",
+        "phpunit/phpunit": "^7.5"
+    },
+    "autoload": {
+        "psr-4": {
+            "Gamez\\": "src"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Gamez\\Duration\\Tests\\": "tests"
+        }
+    },
+    "scripts": {
+        "test": ["@phpunit", "@phpstan"],
+        "test-ci": ["@phpunit-ci", "@phpstan-ci"],
+
+        "coverage": "vendor/bin/phpunit --coverage-html=build/coverage",
+
+        "phpunit": "vendor/bin/phpunit --testdox",
+        "phpunit-ci": "vendor/bin/phpunit -c phpunit.xml.dist --testdox",
+
+        "phpstan": "vendor/bin/phpstan analyze",
+        "phpstan-ci": "vendor/bin/phpstan analyze -c phpstan.neon.dist --no-interaction --no-progress"
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

phpstan.neon.dist

@@ -0,0 +1,4 @@
+parameters:
+	level: max
+	paths:
+		- src

phpunit.xml.dist

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.0/phpunit.xsd"
+    colors="true"
+>
+    <testsuites>
+        <testsuite name="Duration Tests">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">src</directory>
+        </whitelist>
+    </filter>
+
+    <php>
+        <ini name="date.timezone" value="UTC" />
+    </php>
+</phpunit>