PHPackages                             wookieb/relative-date - 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. wookieb/relative-date

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

wookieb/relative-date
=====================

Fully configurable tool to calculate and show date diff in human readable form like "2 minutes ago" or "10 minutes from now".

0.1(9y ago)23.6k1MITPHP

Since Jul 24Pushed 9y ago1 watchersCompare

[ Source](https://github.com/wookieb/relative-date)[ Packagist](https://packagist.org/packages/wookieb/relative-date)[ RSS](/packages/wookieb-relative-date/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependencies (2)Versions (2)Used By (1)

Relative-date
=============

[](#relative-date)

Library that helps you compute human readable information about dates.

This is especially useful for such cases like:

- Computing time ago - "2 seconds ago", "yesterday"
- Computing time in the future - "within 5 seconds", "tomorrow at 14:00" (in progress)

Features
--------

[](#features)

- Customizable rules and predefined rules ([see calculators](#calculators))
- Smart "yesterday" and "tomorrow" calculations
- Support for translations or any other customer formatter
- Symfony 2 and 3 integration via [relative-date-bundle](https://github.com/wookieb/relative-date-bundle)

Installation
------------

[](#installation)

```
composer require wookieb/relative-date
```

Usage
-----

[](#usage)

```
$formatter = new Wookieb\RelativeDate\Formatters\BasicFormatter();
// You can pick one of calculators. See "calculators" section for details
$calculator = Wookieb\RelativeDate\Calculators\TimeAgoDateDiffCalculator::full();

$date = new \DateTime('2016-01-01 14:00:00');
$now = new \DateTime('2016-01-01 16:00:00'); // not required, defaults to current date
$formatter->format($calculator->compute($date, $now)); // 2 hours ago
```

Rationale
---------

[](#rationale)

I've created this library because I was tired of tons of very simplistic relative date calculators that compute a result based on very strict, immutable rules. That's why *relative-date* consists of parts that allows you to redefine the whole logic of relative date computation that exactly suits to your needs.

You don't need "2 years ago" result since in most cases it's useless? Feel free to pick "upTo2Weeks" calculator and get exactly what you need!

Translation and support for different languages
-----------------------------------------------

[](#translation-and-support-for-different-languages)

Translations are supported via [TranslatorFormatter](src/Formatters/TranslatorFormatter.php).

Symfony users should use [relative-date-bundle](https://github.com/wookieb/relative-date-bundle).

```
// $translator - get Symfony translator somehow
$formatter = new Wookieb\RelativeDate\Formatters\TranslatorFormatter($translator);
$calculator = Wookieb\RelativeDate\Calculators\TimeAgoDateDiffCalculator::full();

$date = new \DateTime('2016-01-01 14:00:00');
$now = new \DateTime('2016-01-01 16:00:00');
$formatter->format($calculator->compute($date, $now)); // 2 godziny temu
```

Calculators
-----------

[](#calculators)

### TimeAgoCalculator::full

[](#timeagocalculatorfull)

Computes result in one of the units:

- seconds
- minutes
- hours
- days
- weeks
- months
- years

### TimeAgoCalculator::upTo2Weeks

[](#timeagocalculatorupto2weeks)

Computes result in one of the units:

- seconds
- minutes
- "yesterday"
- hours
- days
- weeks (up to 14 days)
- full date (if date is older than 14 days)

### TimeAgoCalculator::upTo2Days

[](#timeagocalculatorupto2days)

Computes result in one of the units:

- seconds
- minutes
- "yesterday"
- hours
- full date (if date is older than "yesterday")

Customization
-------------

[](#customization)

### Translator and custom placeholders

[](#translator-and-custom-placeholders)

By default TranslatorFormatter defines only one placeholder "%count%" for your translations. You can define custom ones, especially useful for more detailed final outputs.

```
$translator = new TranslatorFormatter($translator);
$translator->registerCustomPlaceholder(
    ['yesterday', 'tomorrow'], // applies only to specific result key names
    '%at%', // placeholder name
    function(DateDiffResult $result) {
        return $result->getRequest()
            ->getDate()
            ->format('H:i');
    }
);

// translation definition
tomorrow: tomorrow at %at%

// usage
$date = new \DateTime('2016-01-01 14:05:00');
$baseDate = new \DateTime('2016-01-02 00:00:00');
$result = $translator->format(TimeAgoCalculator::upTo2Weeks()->compute($date, $baseDate));
$result; // yesterday at 14:05
```

### Custom full date format

[](#custom-full-date-format)

Every built-in Formatter supports date format string applied to results representing full date.

```
$format = Wookieb\RelativeDate\Formatters\BasicFormatter::SHORT_FORMAT; // Y-m-d
$formatter = new Wookieb\RelativeDate\Formatters\BasicFormatter($format);
$calculator = Wookieb\RelativeDate\Calculators\TimeAgoDateDiffCalculator::upTo2Weeks();

$date = new \DateTime('2016-01-01 14:00:00');
$now = new \DateTime('2016-03-01 16:00:00');
$formatter->format($calculator->compute($date, $now)); // 2016-01-01
```

```

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 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

Unknown

Total

1

Last Release

3581d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5596087fec711d58384b3d8f8d80e71f49f5a4186a67b14fcf2fc8462924289b?d=identicon)[wookieb](/maintainers/wookieb)

---

Top Contributors

[![wookieb](https://avatars.githubusercontent.com/u/542596?v=4)](https://github.com/wookieb "wookieb (23 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wookieb-relative-date/health.svg)

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

###  Alternatives

[chrismallory/module-freeshipping-progress-bar

Display a progress bar on the shopping cart based on order total to encourage users to spend more to get free shipping

4915.4k](/packages/chrismallory-module-freeshipping-progress-bar)[corneltek/universal

Universal library for PHP

14146.3k5](/packages/corneltek-universal)[webparking/nova-belongs-to-dependency

Extended Laravel Nova BelongsTo field that can depend on other fields

1157.8k](/packages/webparking-nova-belongs-to-dependency)[professional-wiki/modern-timeline

Adds a modern timeline visualization as Semantic MediaWiki result format

1820.8k1](/packages/professional-wiki-modern-timeline)

PHPackages © 2026

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