ottosmops / antondate

v0.1.0 2026-10-29 10:36 UTC

Requires

• php: ^8.2
• ext-mbstring: *
• nesbot/carbon: ^2.72|^3.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/framework: ^12.0|^13.0
• orchestra/testbench: ^10.0|^11.0
• phpunit/phpunit: ^11.5|^12.0

Suggests

• laravel/framework: For the Eloquent casts, the validation rule and translations via lang/vendor/antondate

MIT

• ak

• date
• laravel
• Antondate
• historical dates
• partial dates

Published on Packagist.org on 2026-10-29 10:54 UTC

README

Partial and approximate historical dates as used in Anton (anton.ch): 1923, 1923-05, ca. 1923-05-14.

The package is plain PHP (8.2+, with Carbon for formatting). Laravel is optional: if it is installed, there are Eloquent casts, a validation rule, and the translations follow the application.

Installation

Via Composer

$ composer require ottosmops/antondate

Without Laravel

Set the locale for rendered dates (en by default; de, fr, it are included):

use Ottosmops\Antondate\Lang;

Lang::setLocale('de');

With Laravel

The service provider is discovered automatically. Locale and translations come from the application; the strings can be overridden in lang/vendor/antondate (php artisan vendor:publish --tag=antondate-lang).

Add date_start, date_start_ca, date_end, date_end_ca to the database table.

Add the casts to the model:

protected $casts = [
    'anton_date_interval' => AntonDateIntervalCast::class,
    'anton_date_start' => AntonDateStartCast::class,
    'anton_date_end' => AntonDateEndCast::class,
];

Usage

The package covers two ValueObjects: AntonDate, AntonDateInterval (consisting of two AntonDates).

Create an AntonDate

AntonDate::createFromString('1995-03-01', 1) : AntonDate
// ca. 1995-03-01

AntonDate::guessFromString('4. Mai 1905') : AntonDate
// 1905-05-04, also '4.5.1905' and '4. Mai. 1905'
// throws an InvalidArgumentException for a date that does not exist ('31.02.1900')

AntonDate::compose(1973, 12, 3, 1) : AntonDate
// ca. 1973-12-03

AntonDate::today() : AntonDate

Validate

AntonDate::isValidString('1997-13-01'); // false
AntonDate::isValidString('ca. 1997-11-01'); // true

Get

$antondate->toString();
$antondate->toArray();
$antondate->formatted();
$antondate->toMysqlDate();
$antondate->getCa();
$antondate->getYear();
$antondate->getMonth();
$antondate->getDay();

Compare

$antondate->isEqualTo($antondate2, true); // compare with ca
$antondate->isEqualTo($antondate2); // compare without ca
$antondate->intervalIsAfter($antondate2); // '1923-05-15' is not after '1923', but after '1922'
$antondate->isGreaterThan($antondate2); // compares YYYYMMDD with missing parts as 00
$antondate->isLessThan($antondate2);

DateHelper

Helpers for the date columns as they are stored (1923-05-00):

use Ottosmops\Antondate\DateHelper;

DateHelper::renderDate('0958-00-00', 1, '1050-03-01', 0); // 'ca. 958 – 1. Mär 1050'
DateHelper::formatDate('0000-06-16');                    // '16. Juni' (no year)
DateHelper::parseDateString('2. April 2014');            // '2014-04-02'
DateHelper::cleanDate('1923-05-00');                     // '1923-05'
DateHelper::composeDate(1923, 5, 0);                     // '1923-05-00'
DateHelper::joinNormalDate('1893', '0000');              // '1893' (apeEAD unitdate normal)
DateHelper::unpadYears('3. Mai 0958');                   // '3. Mai 958'

Rule (Laravel)

There is also a rule which you can use for validation:

use Ottosmops\Antondate\Rules\AntonDateRule;

// Strict mode (default) - uses AntonDate::createFromString()
new AntonDateRule()
new AntonDateRule(strict: true)

// Non-strict mode - uses AntonDate::guessFromString()
new AntonDateRule(strict: false)

License

MIT. Please see the license file for more information.