A library that calculates the time difference between two dates and returns the result in words (Example: 5 minutes ago or 5 Minutes left). The library supports other languages aswell like Spanish and German.

License: MIT

Language: PHP


Build Status Scrutinizer Quality Score Code Coverage Latest Stable Version Total Downloads

RelativeTime is a lightweight and easy to use library that helps you calculate the time difference between two dates and returns the result in words (like, 5 minutes ago or 5 minutes left). The library supports other languages as well like Spanish, German, Czech, French and Portuguese.

It uses the standard \DateTime() and \DateInterval() classes found in modern PHP versions. For more information, please read the Usage section of this README.


  • PHP >= 5.3


Install with Composer

If you're using Composer to manage dependencies, you can use this library by creating a composer.json file and adding this:

    "require": {
        "mpratt/relativetime": "~1.0"

Save it and run composer.phar install

Standalone Installation (without Composer)

Download the latest release or clone this repository, place the Lib/RelativeTime directory somewhere in your project. Afterwards, you only need to include the included Autoload.php file.

    require '/path/to/RelativeTime/Autoload.php';
    $relativeTime = new \RelativeTime\RelativeTime();

Or if you already have PSR-0 compliant autoloader, you just need to register RelativeTime:

    $loader->registerNamespace('RelativeTime', 'path/to/RelativeTime');


Most of the times you are going to need the convert($fromDate, $toDate) method.

    $relativeTime = new \RelativeTime\RelativeTime();
    echo $relativeTime->convert('2010-09-05', '2010-03-30');
    // 5 months, 6 days ago

    $relativeTime = new \RelativeTime\RelativeTime();
    echo $relativeTime->convert('2012-03-05', '2013/02/05');
    // 11 months left

There are 2 other useful methods timeAgo($date) and timeLeft($date), that calculate the time since/until the current date/time.

    // Asumming Today is the 2013-09-23 17:23:47

    $relativeTime = new \RelativeTime\RelativeTime();
    echo $relativeTime->timeAgo('2012-08-29 06:00');
    // 1 year, 25 days, 16 hours, 23 minutes, 13 seconds ago

    $relativeTime = new \RelativeTime\RelativeTime();
    echo $relativeTime->timeLeft('2013-10-31 01:00:05');
    // 1 month, 7 days, 2 hours, 36 minutes, 52 seconds left

Configuration Options

The main object accepts an array with configuration directives

    $config = array(
        'language' => '\RelativeTime\Languages\English',
        'separator' => ', ',
        'suffix' => true,
        'truncate' => 0,

    $relativeTime = new \RelativeTime\RelativeTime($config);
Directive Definition
language The language to be used, for example English, Spanish, PortugueseBR, French, Czech or German are supported. Even The instantiated object is allowed, as in new \RelativeTime\Languages\English()
separator The separator between time units. , by default.
truncate The number of units you want to display. By default it displays all of the available ones.
suffix Whether or not to append the .... ago or ..... left


MIT For the full copyright and license information, please view the LICENSE file.


Hi! I'm Michael Pratt and I'm from Colombia! My Personal Website is in Spanish.

Project Statistics

Sourcerank 6
Repository Size 23.4 KB
Stars 17
Forks 9
Watchers 2
Open issues 0
Dependencies 1
Contributors 5
Tags 6
Last updated
Last pushed

Top Contributors See all

Michael Pratt PGP 2F93D5AF Martin Procházka Jon Jay JΩyε

Packages Referencing this Repo

A library that calculates the time difference between two dates and returns the result in words (...
Latest release 1.5.4 - Updated - 17 stars

Recent Tags See all

1.5.4 December 24, 2015
1.5.3 November 05, 2015
1.5.2 September 04, 2015
1.5.1 May 28, 2015
1.5 January 17, 2015
1.0 September 23, 2013

Something wrong with this page? Make a suggestion

Last synced: 2016-05-27 14:11:00 UTC

Login to resync this repository