Download the PHP package alexxiy/php-time-intervals without Composer

php-time-intervals

Describe the distance between two points in time in words — "3 days ago", "in 3 days", "3 days", or "3d ago" — in 35 languages, with CLDR plural rules applied in each.

Requirements

PHP 8.5 or newer. No extensions, no runtime dependencies.

Installation

Usage

The basics

inWords() accepts any DateTimeInterface, so DateTime and DateTimeImmutable both work, and neither argument is modified. When $now is omitted, it defaults to the current time in the given date's timezone.

Tense

By default, the direction of the interval decides how it is phrased: a date in the past reads "3 days ago", one in the future reads "in 3 days". Ask for Tense::Plain to get the bare span with no direction attached.

Pin a tense for every call by passing it to the constructor or derive a pinned instance from an existing one:

A pinned tense overrides the direction of the interval, so Tense::Past will say "3 days ago" about a date three days from now. withTense(null) goes back to following the interval.

The per-call tense: argument beats the pinned one and leaves the instance alone.

Style

Independently of the tense, the wording can be full or abbreviated:

The two axes are orthogonal, so every combination is available:

Style is set the same three ways as tense — constructor, withStyle(), or a per-call argument:

Abbreviations do not inflect, which is a feature rather than a shortcut: Russian writes 2 д, 5 д and 21 д alike where the spelled-out noun would need three different endings.

23 of the 35 languages ship abbreviations. The rest fall back to their full forms, which is the right answer rather than a gap — Japanese 5日前 is already as short as it gets. Locale::Japanese->language()->vocabulary()->abbreviates() tells you which is which, and TRANSLATIONS.md lists them.

Languages

Pick one of the bundled languages through the Locale enum:

Locale is a string-backed enum keyed by BCP 47 tag, which makes it easy to drive from user input without a lookup table of your own:

Locale::label() returns the English name of each locale for building a picker:

IntervalFormatter is immutable, so you can also derive one instance from another. The pinned tense carries across:

Plural forms

Counts are pluralized with the CLDR rules for each language, so the languages that need more than one plural form get them:

Arabic gets its dual, Latvian its form for the teens and the round tens, Czech and Polish their own splits. See PluralRule for the rules and which language uses each.

"Never"

For records that have no date at all:

Your own language

A language is a bag of strings: the three tenses of the full style, the word for "never", and optionally the three tenses of the short style. Implement Language and hand it to IntervalFormatter; it does not need to be registered anywhere.

Here is a complete one that signs the interval instead of wording it, which is handy for logs. Its output is already terse, so it omits short and lets the short style serve these same forms:

The full version of this example lives in tests/Fixtures/Signed.php and is asserted by tests/CustomLanguageTest.php, so it cannot drift from the code.

Every tense of the full style is a required constructor argument, so a language cannot be written half-finished. short is optional; supply it as a whole TenseSet or not at all, which stops a language knowing how to say "5m ago" but not "in 5m". Within a counted phrase only other is required, and the remaining plural categories fall back to it. For a phrase that genuinely does not inflect, say so with PluralForms::invariant('%sd ago') rather than repeating yourself.

Counted phrases are sprintf() patterns and must contain exactly one %s — except the zero, one and two forms, which may spell the number out as a word instead. Uncounted phrases are used verbatim and are never passed through sprintf(), so a literal percent sign in them is safe.

Note that Locale holds languages, not formats: its cases are real BCP 47 tags so that Locale::tryFrom($acceptLanguageHeader) is meaningful. Presentation choices belong on the Style axis, or in your own code.

How the interval is described

An interval is described by the unit it is nearest to, not the one it has merely reached. Every threshold below is the point at which the rounded count ticks over:

So 47 hours reads "2 days" rather than "1 day", and 59 days reads "2 months" rather than "about 1 month".

Minutes, hours and days have a fixed length and are decided on the exact number of elapsed seconds. Months and years vary, so they are decided on the calendar fields of the interval — which is why 1 February to 1 April is two months in every year, and not one month whenever February happens to be short.

over N years counts whole years elapsed rather than rounding, so it is never an overstatement: an interval of 1 year 11 months reads "over 1 year", never "over 2 years".

The rules live in Classifier, which is a constructor argument of IntervalFormatter, so they can be swapped out wholesale if the defaults do not suit you.

Translation quality

The past phrases come from the original contributors to jimmiw/php-time-ago. The future and plain phrases, the plural forms, and the abbreviations were added in this package and have not all been through a native speaker. TRANSLATIONS.md says which languages that applies to; corrections are very welcome.

The plural rules themselves are implemented from the published CLDR tables and are checked against them in tests/PluralRuleTest.php.

Development

The project ships a PHPUnit suite, PHPStan at level max, and PSR-12 linting.

Or individually:

Credits

This is a fork of jimmiw/php-time-ago by Jimmi Westerberg, whose translations are the bulk of the value here. The public API, the rule engine, and the type design were rewritten for this package; see CHANGELOG.md for what changed and why.

License

MIT. See LICENSE.