Manual

Generate textual time differences that are easily understandable by humans ("5 minutes ago"). The package supports minutes, hours, days, weeks, months and years.

Basic usage: Getting a human readable time difference

Just include the Date/HumanDiff.php file, instantiate a Date_HumanDiff object and run get() on it.

<?php
require_once 'Date/HumanDiff.php';
$dh = new Date_HumanDiff();
echo $dh->get(time() - 5 * 60) . "\n";
//prints out "5 minutes ago"
?>

get() accepts two parameters: The timestamp and the reference time. If the reference time is not provided, the current time is used. Both parameters may be unix timestamps, DateTime objects as well as strings that can be converted to a unix timestamp with strtotime.

The difference between timestamp and reference time is then converted into a human readable string.

Using translations

Date_HumanDiff ships a number of translations that provide localized messages. Version 0.4.0 comes with German (de), Greek (el) and Persian (fa) translations.

The setLocale method accepts locale names (de_AT, en_US) as well as ISO 639-1 two-letter language codes (de, fr, en). If the combination of language code + country code does not match, the language code alone is tried. If that also fails, the english variant is used.

Using the German translation

<?php
require_once 'Date/HumanDiff.php';
$dh = new Date_HumanDiff();
$dh->setLocale('de_DE');
echo $dh->get(time() - 5 * 60) . "\n";
//prints out "vor 5 Minuten"
?>

Generating HTML

When generating HTML you should keep in mind that the relative time difference generated by Date_HumanDiff is only valid for the very moment it got created. A couple of seconds later it may be wrong - if it was "one minute ago", it needs to be "two minutes ago" then.

The first step to cater for that problem is to provide the original date and time value together with the relative difference. The Microformats project has a matching convention for this task, the datetime-design-pattern, and HTML5 has a semantically equivalent element: <time>.

Both methods use RFC 3339 style date and time values, for example 1996-12-19T16:39:57-08:00.

Expressing the original timestamp using a microformat

<?php
require_once 'Date/HumanDiff.php';
$dh = new Date_HumanDiff();

//fictive creation date of e.g. a blog post
$creationDate = 1346277600;
$relDiff = $dh->get($creationDate);//age of blog post
?>
<abbrev title="<?php echo date('c', $creationDate); ?>">
 <?php echo htmlspecialchars($relDiff); ?>
</abbrev>

Expressing the original timestamp with the HTML5 time tag

<?php
require_once 'Date/HumanDiff.php';
$dh = new Date_HumanDiff();

//fictive creation date of e.g. a blog post
$creationDate = 1346277600;
$relDiff = $dh->get($creationDate);//age of blog post
?>
<time datetime="<?php echo date('c', $creationDate); ?>">
 <?php echo htmlspecialchars($relDiff); ?>
</time>