Date Column

Render date and datetime values with correct chronological sorting

DateColumn uses the DataTables date type for chronological sorting. The column expects values formatted as ISO 8601 strings by default (Y-m-d). Pass a custom format when your data uses a different pattern.

Basic Usage

use Pentiminax\UX\DataTables\Column\DateColumn;

DateColumn::new('createdAt', 'Created');

Returns values as-is. mapRow() must return a string in Y-m-d format (or the configured format) for correct sorting.

Custom Format

Use setFormat() to declare the date format of your values:

DateColumn::new('publishedAt', 'Published')
    ->setFormat('d/m/Y');

Pass null to revert to the default Y-m-d:

$column->setFormat(null);

Relative Dates

Call relative() to render the cell as a localized relative label (“3 minutes ago”) instead of a formatted date:

DateColumn::new('lastLoginAt', 'Last login')
    ->relative()
    ->setDefaultContent('Never');

The label is produced in the browser with Intl.RelativeTimeFormat, so it needs no extra dependency and follows the locale of the <html lang> attribute, falling back to navigator.language. Sorting and searching keep using the underlying date, and setDefaultContent() covers null values.

The label is recomputed on every draw — paging, sorting, searching, an Ajax reload, a Mercure update — and not on a timer. An idle table therefore keeps the labels it was last drawn with, so “20 seconds ago” stays on screen until the next draw. Call table.rows().invalidate().draw(false) on an interval if a table is meant to sit open on second-accurate values.

While relative() is enabled the serialized value switches to ISO 8601 so the browser can compute the offset, which makes any format set through setFormat() irrelevant. Disabling it with relative(false) restores the configured format.

Display Formatting

For anything other than a relative label, attach a renderer through the datatables:pre-connect event:

this.element.addEventListener('datatables:pre-connect', (event) => {
  const createdAtColumn = event.detail.config.columns.find(
    (column) => column.name === 'createdAt'
  )

  if (createdAtColumn) {
    createdAtColumn.render = (data) =>
      data ? new Date(data).toLocaleDateString('fr-FR') : ''
  }
})

API Reference

Method	Description
`DateColumn::new(string $name, string $title = '')`	Creates a new DateColumn (type: `date`). Default format: `Y-m-d`.
`setFormat(?string $format)`	Set the expected date format; `null` resets to default
`getFormat()`	Returns the active format string, or ISO 8601 while `relative()` is enabled
`relative(bool $relative = true)`	Render the cell as a localized relative label in the browser
`isRelative()`	Whether relative rendering is enabled

Complete Example

use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\DateColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(Article::class)]
final class ArticlesDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('title', 'Title');
        yield DateColumn::new('publishedAt', 'Published');
        yield DateColumn::new('updatedAt', 'Updated')->setFormat('Y-m-d H:i');
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'          => $row->getId(),
            'title'       => $row->getTitle(),
            'publishedAt' => $row->getPublishedAt()?->format('Y-m-d'),
            'updatedAt'   => $row->getUpdatedAt()?->format('Y-m-d H:i'),
        ];
    }
}