PHPackages                             haltsir/semantic-date - 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. haltsir/semantic-date

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

haltsir/semantic-date
=====================

Dates for humans

1.0.0(3y ago)16MITPHPPHP ^8.0

Since Apr 13Pushed 3y ago1 watchersCompare

[ Source](https://github.com/haltsir/semantic-date)[ Packagist](https://packagist.org/packages/haltsir/semantic-date)[ RSS](/packages/haltsir-semantic-date/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Semantic Date
=============

[](#semantic-date)

Semantic Date is a PHP library that provides an easy way to convert dates into human-readable, semantic expressions. The library is framework-agnostic but includes specific instructions for integration with the Laravel framework. The package supports two calendar types: Orthodox and Catholic.

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

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Examples](#examples)
- [Integration with Laravel](#integration-with-laravel)
- [Contributing](#contributing)

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

[](#requirements)

- PHP >= 8.0
- Composer

Installation
------------

[](#installation)

To install the Semantic Date library, use the following Composer command:

```
composer require haltsir/semantic-date
```

Usage
-----

[](#usage)

To use the Semantic Date library, first create an instance of the DateConverter class, then call the convert method with the date you want to convert:

```
use Haltsir\SemanticDate\DateConverter;

$converter = new DateConverter();
$semanticDate = $converter->convert(new DateTime('your date here'));
```

You can also pass additional options to the DateConverter constructor, such as custom holidays, excluded date conditions, and a calendar type. The package supports the Orthodox (default) and Catholic calendars. To use a specific calendar, set the calendarType option.

By default, the locale is set to 'en' (English). The library uses the given locale to determine the translations for holidays and other date-related expressions. You can change the default locale by passing it as the second parameter to the DateConverter constructor.

### Laravel

[](#laravel)

To set up on Laravel, follow these steps:

1. Add the service provider to the providers array:

```
'providers' => [
    // ...
    Haltsir\SemanticDate\SemanticDateServiceProvider::class,
],
```

2. Add the facade to the aliases array:

```
'aliases' => [
    // ...
    'SemanticDate' => Haltsir\SemanticDate\Facades\SemanticDateFacade::class,
],
```

Now you can use the SemanticDate facade in your Laravel application:

```
use SemanticDate;

$date = new DateTime('2023-04-10');
$convertedDate = SemanticDate::convert($date);
```

Examples
--------

[](#examples)

Here are some examples of how to use the Semantic Date library:

### Basic usage

[](#basic-usage)

```
use Haltsir\SemanticDate\DateConverter;

$converter = new DateConverter();
echo $converter->convert(new DateTime('today')); // Output: Today
echo $converter->convert(new DateTime('yesterday')); // Output: Yesterday
```

### Custom holidays

[](#custom-holidays)

```
use Haltsir\SemanticDate\DateConverter;

$configuration = [
    'customHolidays' => ['27-12' => 'Stefan Name Day']
];

$converter = new DateConverter($configuration);
echo $converter->convert(new DateTime('2023-12-27')); // Output: Stefan Name Day
```

### Excluding date conditions

[](#excluding-date-conditions)

```
use Haltsir\SemanticDate\DateConverter;
use Haltsir\SemanticDate\DateConditions\Today;

$configuration = [
    'excludedDateConditions' => [Today::class]
];

$converter = new DateConverter($configuration);
echo $converter->convert(new DateTime('today')); // Output: the actual date instead of "Today"
```

### Changing calendar type and locale

[](#changing-calendar-type-and-locale)

```
use Haltsir\SemanticDate\DateConverter;
use Haltsir\SemanticDate\CalendarType;

$configuration = [
    'calendarType' => CalendarType::CATHOLIC
];

$converter = new DateConverter($configuration, 'fr');
echo $converter->convert(new DateTime('2023-04-09')); // Output: Pâques (Catholic Easter in French)
```

### Custom Easter observation

[](#custom-easter-observation)

You can also set the method to 'none'.

```
use Haltsir\SemanticDate\DateConverter;
use Haltsir\SemanticDate\CalendarType;

$configuration = [
    'calendarType' => CalendarType::CUSTOM
];

$converter = new DateConverter(['calendarType' => CalendarType::CUSTOM, 'easterMethod' => 'MyClass::myMethod']);
```

Integration with Laravel
------------------------

[](#integration-with-laravel)

To integrate the Semantic Date library with a Laravel application, follow these steps:

1. Publish the configuration and language files using the following Artisan command:

```
php artisan vendor:publish --provider="Haltsir\SemanticDate\SemanticDateServiceProvider"
```

2. Modify the published configuration file (config/semantic-date.php) to customize the library behavior, such as default holidays and other settings.
3. If you want to add your own custom translations, create a new translations file in your app's lang directory. For example, if you want to add custom translations for the English language, create a semantic-date.php file inside the resources/lang/en directory and add your translations there.
4. In your Laravel application, use the Semantic Date library as shown in the Usage and Examples sections. The library will automatically detect the locale set in your Laravel application's configuration (config/app.php). If you want to change the locale for a specific instance of the DateConverter class, pass the desired locale as the second parameter to the constructor:

```
use Haltsir\SemanticDate\DateConverter;
use Haltsir\SemanticDate\CalendarType;

$configuration = [
    'calendarType' => CalendarType::CATHOLIC
];

$converter = new DateConverter($configuration, 'es');
echo $converter->convert(new DateTime('2023-04-16')); // Output: Pascua Ortodoxa (Orthodox Easter in Spanish)
```

Contributing
------------

[](#contributing)

Contributions to the Semantic Date library are welcome! To contribute, please follow these steps:

1. Fork the repository on GitHub.
2. Create a new branch for your changes.
3. Write extensive tests for your changes using the Pest testing framework.
4. Submit a pull request with your proposed changes or feature requests.

If you encounter any problems or need assistance, feel free to create an issue or reach out to the maintainers for help.

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 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

Unknown

Total

1

Last Release

1131d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7768c88d78f0bd2436a344d92eacdad506b7db3666a9bee1c9c5aa49b23160e8?d=identicon)[strahil](/maintainers/strahil)

---

Top Contributors

[![haltsir](https://avatars.githubusercontent.com/u/4955925?v=4)](https://github.com/haltsir "haltsir (2 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/haltsir-semantic-date/health.svg)

```
[![Health](https://phpackages.com/badges/haltsir-semantic-date/health.svg)](https://phpackages.com/packages/haltsir-semantic-date)
```

PHPackages © 2026

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