---
title: "Formatting"
description: "DateFormatter describes dates, months and elapsed time as translatable messages, so a language is added with a catalogue and no code"
type: "docs"
category: "doc"
tags: []
authors: [Anonymous]
date: "2026-11-05"
last_update: "2026-11-05"
time_minutes: 2
draft: false
unlisted: false
url: "https://www.derafu.dev/docs/core/date/formatting"
---

# Formatting

```php
use Derafu\Date\Service\DateFormatter;
```

`DateFormatter` describes a date, a month and the time that has passed. It does not give text: every method gives a [`TranslatableMessage`](https://www.derafu.dev/docs/core/translation), and the language is decided by whoever translates it.

| Method | Message |
| --- | --- |
| `formatDate($date, $includeWeekday = true)` | `Monday, January 15, 2024` |
| `formatMonth($month)` | `January 2024`. It takes a [`Month`](months) or a number written as `AAAAMM`. |
| `formatElapsed($date, $full = false)` | `3 days ago`, `1 year, 5 days ago`, `just now`. |

```php
$formatter = new DateFormatter();

$message = $formatter->formatDate('2024-01-15');

$message->trans($translator, 'es');   // Lunes, 15 de Enero del 2024
(string) $message;                    // Monday, January 15, 2024
```

Without a translator the message is written in English, which is the language of its id.

`formatElapsed()` describes the time between the date and the clock (the system clock, or the one that is given to the constructor). It gives the two largest units (`1 year, 5 days`), or all of them with `$full`: years, months, weeks, days, hours, minutes and seconds. A difference of nothing is `just now`.

## The catalogues

The names and phrases are in the translation domain `date`. The English text of each message is its id, and the catalogue of a language translates it:

```php
// resources/translations/date+intl-icu.es.php
return [
    'Monday' => 'Lunes',
    'January' => 'Enero',
    '{weekday}, {month} {day}, {year}' => '{weekday}, {day} de {month} del {year}',
    '{month} {year}' => '{month} de {year}',
    '{count, plural, one {# day} other {# days}}' => '{count, plural, one {# día} other {# días}}',
    '{parts} ago' => 'hace {parts}',
    'just now' => 'recién',
];
```

The Spanish catalogue ships with the package. The order of the words, the plurals and the names are all in the catalogue, so another language is one more file (`date+intl-icu.fr.php`) and no code. The catalogue of a language must have every id of the domain `date`.

To have the catalogue in your translator, import the services of the package (see [Errors and Translations](errors)).



---
Last updated on 05/11/2026