PHPackages                             tobento/service-dater - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tobento/service-dater

ActiveLibrary[Utility & Helpers](/categories/utility)

tobento/service-dater
=====================

Useful methods to format, verify and display dates.

2.0(7mo ago)03548MITPHPPHP >=8.4

Since Jun 18Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/tobento-ch/service-dater)[ Packagist](https://packagist.org/packages/tobento/service-dater)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-dater/feed)WikiDiscussions 2.x Synced 1mo ago

READMEChangelog (4)Dependencies (3)Versions (6)Used By (8)

Dater Service
=============

[](#dater-service)

The Dater Service provides useful methods to format and display dates in an application.

Table of Contents
-----------------

[](#table-of-contents)

- [Getting started](#getting-started)
    - [Requirements](#requirements)
    - [Highlights](#highlights)
    - [Simple Example](#simple-example)
- [Documentation](#documentation)
    - [Date Formatter](#date-formatter)
        - [Display Date](#date)
        - [Display Date and Time](#date-and-time)
        - [Format Date](#format-date)
        - [In Past](#in-past)
        - [In Between](#in-between)
        - [Diff](#diff)
        - [Now](#now)
        - [Convert](#convert)
            - [To DateTime](#to-datetime)
            - [To Dater](#to-dater)
            - [To Current Year](#to-current-year)
            - [To Month](#to-month)
            - [To Month Number](#to-month-number)
            - [To Month Number String](#to-month-number-string)
            - [To Weekday](#to-weekday)
            - [To Weekday Number](#to-weekday-number)
    - [Dater](#dater)
- [Credits](#credits)

---

Getting started
===============

[](#getting-started)

Add the latest version of the dater service running this command.

```
composer require tobento/service-dater

```

Requirements
------------

[](#requirements)

- PHP 8.4 or greater

Highlights
----------

[](#highlights)

- Framework-agnostic, will work with any project
- Decoupled design

Simple Example
--------------

[](#simple-example)

Here is a simple example of how to use the Dater Service.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

// Intl. format date.
var_dump($df->date('now'));
// string(22) "Friday, 16. April 2021"

// Intl. format date and time.
var_dump($df->dateTime('now'));
// string(29) "Friday, 16. April 2021, 15:08"

// Intl. format date and time with specific timezone and locale.
var_dump($df->withTimezone('America/Chicago')->withLocale('de')->dateTime('now'));
// string(30) "Freitag, 16. April 2021, 08:08"
```

Documentation
=============

[](#documentation)

Date Formatter
--------------

[](#date-formatter)

```
use Tobento\Service\Dater\DateFormatter;

// Define the default settings:
$df = new DateFormatter(
    locale: 'en_US',
    dateFormat: 'EEEE, dd. MMMM yyyy',
    dateTimeFormat: 'EEEE, dd. MMMM yyyy, HH:mm',
    timezone: 'America/Chicago',
    mutable: true,
);

// or use the methods to change default settings.
$df = $df->withLocale('en_US');
var_dump($df->getLocale());
// string(5) "en_US"

var_dump($df->getLocale(delimiter: '-'));
// string(5) "en-US"

$df = $df->withDateFormat('EE, dd. MMMM yyyy');
var_dump($df->getDateFormat());
// string(17) "EE, dd. MMMM yyyy"

$df = $df->withDateTimeFormat('EEEE, dd. MMMM yyyy, HH:mm');
var_dump($df->getDateTimeFormat());
// string(26) "EEEE, dd. MMMM yyyy, HH:mm"

$df = $df->withTimezone('America/Chicago');
var_dump($df->getTimezone());
// object(DateTimeZone)#9 (2) { ["timezone_type"]=> int(3) ["timezone"]=> string(15) "America/Chicago" }

$df = $df->withMutable(true);
```

### Display Date

[](#display-date)

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

// with default date format and locale
var_dump($df->date('now'));
// string(22) "Friday, 16. April 2021"

// with custom format and locale
var_dump($df->date(value: 'now', format: 'EE, dd. MMMM yyyy', locale: 'de_DE'));
string(19) "Fr., 16. April 2021"
```

### Display Date and Time

[](#display-date-and-time)

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

// with default date format and locale
var_dump($df->dateTime('now'));
// string(29) "Friday, 16. April 2021, 15:33"

// with custom format and locale
var_dump($df->dateTime(value: 'now', format: 'EE, dd. MMMM yyyy, HH:mm', locale: 'de_DE'));
// string(26) "Fr., 16. April 2021, 15:33"
```

### Format Date

[](#format-date)

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->format('16-06-2021'));
// string(16) "16.06.2021 00:00"

// with custom
var_dump($df->format(value: 'now', format: 'd.m.Y H:i'));
// string(16) "16.06.2021 12:59"

// if the date provided is invalid it fallsback to 'now'
var_dump($df->format('16-06-19457'));
// string(16) "16.06.2021 13:01"
```

### In Past

[](#in-past)

Determine if a given date is in the past.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->inPast(date: '12.05.2000', currentDate: '13.05.2000', sameTimeIsPast: false));
// bool(true)

var_dump($df->inPast(date: '12.05.2000', currentDate: '11.05.2000', sameTimeIsPast: false));
// bool(false)
```

### In Between

[](#in-between)

Determine if the dates are between the current date.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->inBetween(
    dateFrom: '18.05.2000',
    dateTo: '20.05.2000',
    currentDate: '19.05.2000'
));
// bool(true)

var_dump($df->inBetween(
    dateFrom: '18.05.2000',
    dateTo: '20.05.2000',
    currentDate: '21.05.2000'
));
// bool(false)

// determine yearly independent
var_dump($df->inBetween(
    dateFrom: '18.05.2000',
    dateTo: '20.05.2000',
    currentDate: '19.05.2001',
    yearly: true
));
// bool(true)
```

### Diff

[](#diff)

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->diff(date: '17.05.2000', currentDate: '18.05.2001'));
// object(DateInterval)#10 (16) { ["y"]=> int(1) ["m"]=> int(0) ["d"]=> int(1) ["h"]=> int(0) ["i"]=> int(0) ["s"]=> int(0) ["f"]=> float(0) ["weekday"]=> int(0) ["weekday_behavior"]=> int(0) ["first_last_day_of"]=> int(0) ["invert"]=> int(1) ["days"]=> int(366) ["special_type"]=> int(0) ["special_amount"]=> int(0) ["have_weekday_relative"]=> int(0) ["have_special_relative"]=> int(0) }
```

### Now

[](#now)

A fluent way modifying the current date.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

// uses default timezone
$date = $df->now()->addMinutes(5)
                  ->subMinutes(3)
                  ->addDays(10)
                  ->subDays(2);

// use custom timezone
$date = $df->now('Europe/Berlin')->addMinutes(5);
```

### Convert

[](#convert)

#### To DateTime

[](#to-datetime)

Convert value to a DateTime or DateTimeImmutable object.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toDateTime('2019-06-24'));
// object(DateTimeImmutable)#8 (3) { ["date"]=> string(26) "2019-06-24 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

var_dump($df->withMutable(true)->toDateTime('2019-06-24'));
// object(DateTime)#6 (3) { ["date"]=> string(26) "2019-06-24 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

// with another timezone
var_dump($df->toDateTime(value: '2019-02-23', timezone: 'America/Chicago'));
// object(DateTimeImmutable)#8 (3) { ["date"]=> string(26) "2019-02-23 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(15) "America/Chicago" }

// if an invalid date value is provided, it fallsback to 'now' as default.
var_dump($df->toDateTime(value: 'a-06-24', fallback: 'now'));
// object(DateTimeImmutable)#8 (3) { ["date"]=> string(26) "2021-06-16 14:08:34.699816" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

// if you do not want a fallback.
var_dump($df->toDateTime(value: 'a-06-24', fallback: null));
// NULL

// set a value format for date verification.
var_dump($df->toDateTime(value: '2019-02-30'));
// object(DateTimeImmutable)#8 (3) { ["date"]=> string(26) "2019-03-02 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

// fallsback to the fallback date provided.
var_dump($df->toDateTime(value: '2019-02-30', valueFormat: 'Y-m-d'));
// object(DateTimeImmutable)#10 (3) { ["date"]=> string(26) "2021-06-16 14:12:00.043682" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }
```

#### To Dater

[](#to-dater)

Convert value to a Dater or DaterMutable object. This has same parameters and works like the toDateTime method.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toDater('2019-06-24'));
// object(Tobento\Service\Dater\Dater)#9 (3) { ["date"]=> string(26) "2019-06-24 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }
```

#### To Current Year

[](#to-current-year)

Converts the given date to the current date year.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toCurrentYear('2019-06-24'));
// object(DateTimeImmutable)#9 (3) { ["date"]=> string(26) "2021-06-24 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }

var_dump($df->toCurrentYear(date: '2019-06-24', currentDate: '2015-06-24'));
// object(DateTimeImmutable)#9 (3) { ["date"]=> string(26) "2015-06-24 00:00:00.000000" ["timezone_type"]=> int(3) ["timezone"]=> string(13) "Europe/Berlin" }
```

#### To Month

[](#to-month)

Returns the month or null on failure.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toMonth(5));
// string(3) "May"

var_dump($df->toMonth(number: 5, locale: 'de'));
// string(3) "Mai"

// pattern: 'M' = '1', 'MM' = '09', 'MMM' = 'Jan', 'MMMM' = 'January'
var_dump($df->toMonth(number: 5, pattern: 'MM'));
// string(2) "05"
```

#### To Month Number

[](#to-month-number)

Returns the month number or null on failure.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toMonthNumber('Feb'));
// int(2)

var_dump($df->toMonthNumber('Foo'));
// NULL
```

#### To Month Number String

[](#to-month-number-string)

Returns the month number as string or null on failure.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toMonthNumberString('Jan'));
// string(2) "01"
```

#### To Weekday

[](#to-weekday)

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

var_dump($df->toWeekday(5));
// string(6) "Friday"

var_dump($df->toWeekday(number: 5, locale: 'de'));
// string(7) "Freitag"

// pattern: E, EE, or EEE = 'Tue', 'EEEE' = 'Tuesday', 'EEEEE' = 'T', 'EEEEEE' = 'Tu'
var_dump($df->toWeekday(number: 5, pattern: 'EEE'));
// string(3) "Fri"
```

#### To Weekday Number

[](#to-weekday-number)

Returns the weekday number or null on failure.

```
use Tobento\Service\Dater\DateFormatter;

$df = new DateFormatter();

// 'Tuesday', 'Tue', 'Tu' (lower- and uppercase)
var_dump($df->toWeekdayNumber('Tue'));
// int(2)
```

### Dater

[](#dater)

A fluent way modifying dates.

```
use Tobento\Service\Dater\Dater;
use DateTimeImmutable;

$dater = new Dater('now');

var_dump($dater instanceof DateTimeImmutable); // bool(true)

$dater = $dater->addMinutes(5)
               ->subMinutes(3)
               ->addDays(10)
               ->subDays(2);
```

```
use Tobento\Service\Dater\DaterMutable;
use DateTime;

$dater = new DaterMutable('now');

var_dump($dater instanceof DateTime); // bool(true)

$dater = $dater->addMinutes(5)
               ->subMinutes(3)
               ->addDays(10)
               ->subDays(2);
```

Credits
=======

[](#credits)

- [Tobias Strub](https://www.tobento.ch)
- [All Contributors](../../contributors)

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance62

Regular maintenance activity

Popularity15

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~312 days

Recently: every ~388 days

Total

6

Last Release

236d ago

Major Versions

1.x-dev → 2.02025-09-24

PHP version history (2 changes)1.0.0PHP >=8.0

2.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/055d6a1b5c2384bb179c75ab0b55914231d898fdc4dffeb30770f81200e52206?d=identicon)[TOBENTOch](/maintainers/TOBENTOch)

---

Top Contributors

[![tobento-ch](https://avatars.githubusercontent.com/u/16684832?v=4)](https://github.com/tobento-ch "tobento-ch (8 commits)")

---

Tags

phppackagetimedatetobento

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tobento-service-dater/health.svg)

```
[![Health](https://phpackages.com/badges/tobento-service-dater/health.svg)](https://phpackages.com/packages/tobento-service-dater)
```

###  Alternatives

[kartik-v/php-date-formatter

A Javascript datetime formatting and manipulation library using PHP date-time formats.

461.5M3](/packages/kartik-v-php-date-formatter)[dater/dater

Compact PHP library for working with date/time in different formats & timezones.

14282.3k](/packages/dater-dater)[zjkal/time-helper

一个简单快捷的PHP日期时间助手类库。 a smart PHP datetime helper library.

21128.6k1](/packages/zjkal-time-helper)[maherelgamil/arabicdatetime

Easy and useful tool to generate arabic or hijri date with multi-language support for laravel

414.5k](/packages/maherelgamil-arabicdatetime)[danielstjules/php-pretty-datetime

Generates human-readable strings for PHP DateTime objects

5791.9k](/packages/danielstjules-php-pretty-datetime)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)