smhg / date-timespan

v6.0.0 2026-10-14 09:49 UTC

Requires

• php: >=8.3

Requires (Dev)

• phpmd/phpmd: ^2.15
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^12.5 || ^13.0

MIT

• smhg

• timespan

Published on Packagist.org on 2026-10-14 09:51 UTC

README

Collection of PHP classes to work with timespans.

It differs from DatePeriod in that it only defines a timespan/period by a start and end date. It offers algebraic methods to manipulate a timespan or a collection of them. Convert it to a DatePeriod passing a DateInterval to toPeriod() when you need to iterate over it.

Installation

$ composer require smhg/date-timespan

Methods

Timespan

use Timespan\Timespan;

$start = new DateTime('last monday');
$end = clone $start;
$end->modify('+1 week');

$timespan = new Timespan($start, $end);

contains(DateTime)

Returns whether the timespan contains a date.

overlaps(Timespan)

Returns whether the timespan overlaps with another timespan.

diff(Timespan)

Returns a collection of timespans (pieces of the original timespan) which do not appear in another timespan.

merge(Timespan)

Returns a collection with the merged timespan or both timespans when a merge was not possible.

trim(DateTime, DateTime)

Returns a new timespan fitting within the passed boundaries or null if no time remains.

compare(Timespan)

Returns whether the timespan occurs before, together or after another timespan.

toPeriod(DateInterval)

Converts the timespan to a DatePeriod using an interval.

__toString()

Converts the timespan to a string in ISO 8601 time interval format.

toArray()

Converts the timespan to an array with a single interval element containing the toString representation.

Collection

use Timespan\Timespan;
use Timespan\Collection;

$collection = new Collection();
$collection[] = new Timespan(...);

sort()

Sorts the collection based on the start of each timespan.

compress()

Joins timespans in the collection if they overlap. Also sorts the result.

merge(Collection)

Returns a new collection with the timespans of both collections merged together. Also compresses the result. Neither collection is modified.

diff(Collection)

Returns a new collection with the parts of the collection's timespans which do not appear in another collection. Neither collection is modified.