PHPackages                             smhg/date-timespan - 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. smhg/date-timespan

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

smhg/date-timespan
==================

Collection of PHP classes to work with timespans.

v5.1.0(11mo ago)620.4k↓32.8%21MITPHPPHP >=8.1CI passing

Since Mar 8Pushed 11mo ago2 watchersCompare

[ Source](https://github.com/smhg/date-timespan-php)[ Packagist](https://packagist.org/packages/smhg/date-timespan)[ RSS](/packages/smhg-date-timespan/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (21)Used By (1)

date-timespan [![CI](https://github.com/smhg/date-timespan-php/workflows/CI/badge.svg)](https://github.com/smhg/date-timespan-php/actions)
==========================================================================================================================================

[](#date-timespan-)

Collection of PHP classes to work with timespans.

It differs from [DatePeriod](http://php.net/manual/en/class.dateperiod.php) 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
------------

[](#installation)

```
$ composer require smhg/date-timespan
```

Methods
-------

[](#methods)

### Timespan

[](#timespan)

```
use Timespan\Timespan;

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

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

#### contains(DateTime)

[](#containsdatetime)

Returns whether the timespan contains a date.

#### overlaps(Timespan)

[](#overlapstimespan)

Returns whether the timespan overlaps with another timespan.

#### diff(Timespan)

[](#difftimespan)

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

#### merge(Timespan)

[](#mergetimespan)

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

#### trim(DateTime, DateTime)

[](#trimdatetime-datetime)

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

#### compare(Timespan)

[](#comparetimespan)

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

#### toPeriod(DateInterval)

[](#toperioddateinterval)

Converts the timespan to a [DatePeriod](http://www.php.net/dateperiod) using an interval.

#### \_\_toString()

[](#__tostring)

Converts the timespan to a string in [ISO 8601 time interval](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) format.

#### toArray()

[](#toarray)

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

### Collection

[](#collection)

```
use Timespan\Timespan;
use Timespan\Collection;

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

#### sort()

[](#sort)

Sorts the collection based on the start of each timespan.

#### compress()

[](#compress)

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

#### merge()

[](#merge)

Merges the collection with another collection. Also compresses the result.

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance50

Moderate activity, may be stable

Popularity33

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 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.

###  Release Activity

Cadence

Every ~215 days

Recently: every ~187 days

Total

20

Last Release

352d ago

Major Versions

v0.2.3 → v1.0.02017-11-16

v1.0.0 → v2.0.02018-12-20

v2.1.0 → v3.0.02023-05-15

v3.0.1 → v4.0.02023-06-26

v4.0.0 → v5.0.02023-06-30

PHP version history (6 changes)0.1.0PHP >=5.3.0

v1.0.0PHP >=5.5.9

v2.1.0PHP >=5.6

v3.0.0PHP ^7||^8

v4.0.0PHP ^7.2||^8

v5.0.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/8f5aff3cb1755a1fbf76ff89754e1ad996338a7ebfa1c24301f319a28938f517?d=identicon)[smhg](/maintainers/smhg)

---

Top Contributors

[![smhg](https://avatars.githubusercontent.com/u/2411348?v=4)](https://github.com/smhg "smhg (50 commits)")

---

Tags

iso8601phptimespantimespan

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/smhg-date-timespan/health.svg)

```
[![Health](https://phpackages.com/badges/smhg-date-timespan/health.svg)](https://phpackages.com/packages/smhg-date-timespan)
```

###  Alternatives

[vaimo/composer-patches

Applies a patch from a local or remote file to any package that is part of a given composer project. Patches can be defined both on project and on package level. Optional support for patch versioning, sequencing, custom patch applier configuration and patch command for testing/troubleshooting added patches.

2994.3M16](/packages/vaimo-composer-patches)[symfony/semaphore

Symfony Semaphore Component

373.9M6](/packages/symfony-semaphore)

PHPackages © 2026

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