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 4w 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 52% 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

3628d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/542596?v=4)[Łukasz Kużyński](/maintainers/wookieb)[@wookieb](https://github.com/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

[ijpatricio/mingle

Use Vue and React in Laravel Livewire Applications.

43961.0k2](/packages/ijpatricio-mingle)[immocaster/php-sdk

ImmobilienScout24 PHP-SDK

6439.1k](/packages/immocaster-php-sdk)[nfourtythree/entriessubset

Craft field type plugin that extends the core Entries field type to give extra settings with ability to restrict by entry type

1683.4k](/packages/nfourtythree-entriessubset)[daandelange/simplestats

Very minimal visitor analytics for your kirby website.

711.9k](/packages/daandelange-simplestats)[simple-updates/phpwhois

This package contains a Whois (RFC954) library for PHP. It allows a PHP program to create a Whois object, and obtain the output of a whois query with the Lookup function.

251.4k](/packages/simple-updates-phpwhois)[mikefunk/bustersphp

A simple class to generate js/css tags with cache names from busters.json. This is related to gulp-buster.

115.3k](/packages/mikefunk-bustersphp)

PHPackages © 2026

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