PHPackages                             opencafe/datium - 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. opencafe/datium

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

opencafe/datium
===============

The most flexible DataTime Package ever written in PHP

1.1.1(8y ago)197797[2 issues](https://github.com/opencafe/datium/issues)MITPHP

Since Jun 14Pushed 6y ago3 watchersCompare

[ Source](https://github.com/opencafe/datium)[ Packagist](https://packagist.org/packages/opencafe/datium)[ RSS](/packages/opencafe-datium/feed)WikiDiscussions develop Synced 2mo ago

READMEChangelog (10)Dependencies (1)Versions (14)Used By (0)

Datium
======

[](#datium)

[![Build Status](https://camo.githubusercontent.com/372a95015d0f85045da918b4a5829c74ffd031ab84cfb4e1b5eefbce3b943f67/68747470733a2f2f7472617669732d63692e6f72672f6f70656e636166652f64617469756d2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/opencafe/datium)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/24dcf47e7f6a0985b958058db54cb4cb0c60082922ce8ec126878280e565b8c4/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6f70656e636166652f64617469756d2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/opencafe/datium/?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/2a4a87f11a6b539a2649bbb9d5af2aa733093ca08b55cc63447902604b04d9b4/68747470733a2f2f706f7365722e707567782e6f72672f6f70656e636166652f64617469756d2f762f737461626c65)](https://packagist.org/packages/opencafe/datium)[![Total Downloads](https://camo.githubusercontent.com/3e60c5b913b25e57066e61dd6b12c97bfbc10cf96725ec34f6b312c874fd5ccc/68747470733a2f2f706f7365722e707567782e6f72672f6f70656e636166652f64617469756d2f646f776e6c6f616473)](https://packagist.org/packages/opencafe/datium)[![Join the chat at https://gitter.im/opencafe/datium](https://camo.githubusercontent.com/49dd8aaf27da26bb6caf438de3bfe31ebddf2a089afdc0821614429180bf6629/68747470733a2f2f6261646765732e6769747465722e696d2f6f70656e636166652f64617469756d2e737667)](https://gitter.im/opencafe/datium?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)![npm](https://camo.githubusercontent.com/b15dcb9a7a4b2851ffb0cf28c3cca7ed665c753844ef5268a3763c68fce4c041/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f657870726573732e7376673f6d61784167653d32353932303030)

Awesome DateTime package written in PHP, with generalization support in calendar and translation, which makes Datium powerful and simple.

- Simplicity in code and logic
- Expandable in every part
- Hijri, Jalali, Julian and Kurdish Calendars support

Support
=======

[](#support)

- ^PHP:5.4
- PHP:7

Installation
============

[](#installation)

Via Composer
------------

[](#via-composer)

```
composer require opencafe/datium
```

Manual
------

[](#manual)

Just require `Datium.php` in your project and use Datium namespace as following example:

```
require_once 'src/Datium.php';

use OpenCafe\Datium;

echo Datium::now()->get();
```

Usage
=====

[](#usage)

Simply get what you want:

As datium output

```
Datium::now()->get(); // ex: 2016-01-01 00:00:00

Datium::now()->timestamp(); // ex: 1420057800

Datium::now()->get('timestamp'); // ex: 1420057800
```

Or working with date as simple as you need:

```
Datium::now()->add('1 day')->get(); // ex: 2016-01-02 00:00:00
```

Get
---

[](#get)

Get Datium as DateTime PHP object:

```
Datium::now()->object();
```

Or return it as simple date and time string:

```
Datium::now()->get();
```

And even with custom PHP YMD [format](http://php.net/manual/en/function.date.php):

```
Datium::now()->get( 'l jS F Y h:i:s A' );
```

Timestamp format:

```
Datium::create(2016,10,16)->get('timestamp');
// Result : 1476563400
```

Easy usage:

```
Datium::now()->all();

// Result
object(stdClass)#5 (6) {
  ["second"]=>
  string(2) "03"
  ["minute"]=>
  string(2) "10"
  ["hour"]=>
  string(2) "15"
  ["day"]=>
  string(2) "12"
  ["month"]=>
  string(2) "10"
  ["year"]=>
  string(4) "2016"
}

Datium::now()->all()->year;    // 2016
Datium::now()->all()->month;   // 10
Datium::now()->all()->day;     // 12
Datium::now()->all()->hour;    // 15
Datium::now()->all()->minute;  // 10
Datium::now()->all()->second;  // 03
```

Create
------

[](#create)

You can also simply create new time:

```
// Create with YMD
Datium::create( 2016, 1, 1, 12, 56, 13 )->get(); //ouput: 2016-01-01 12:56:13

// Create with YMD without time
Datium::create( 2016, 1, 1 )->get(); // output: 2016-01-01 12:56:13

// Create with timestamp
Datium::createTimestamp( 1420057800 )->get() // output => 2015-01-01 00:00:00
```

Add Date
--------

[](#add-date)

This method allow you add some year, month, week, day, hour, minute and second to current date.

```
// If current date is 2016-01-01 00:00:00 then:

// Add 3 years
Datium::now()->add('3 year')->get();
// output => 2019-01-01 00:00:00

// Add 1 week
Datium::create(2016, 1, 1)->add('1 week')->get();
// output => 2016-01-08 00:00:00

// Add one month
Datium::now()->add('1 month')->get()
// output => 2016-02-01 00:00:00

// Add 1 year, 3 month and 2 days
Datium::now()->add('1 year')
             ->add('3 month')
             ->add('2 day')
             ->add('1 hour')
             ->add('2 minute')
             ->add('3 second')
             ->get();
// output => 2017-04-03 01:02:03
```

Sub Date
--------

[](#sub-date)

Sub some year, month, day, hour, minute and second from current date.

```
// If current date is 2016-01-01 00:00:00 then:

// Sub 3 years
Datium::now()->sub('3 year')->get();
// output => 2013-01-01 00:00:00

// Sub 1 week
Datium::create(2016, 1, 8)->sub('1 week')->get();
// output => 2016-01-01 00:00:00

// Sub one month
Datium::now()->sub('1 month')->get()
// output => 2015-12-01 00:00:00

// Sub 1 year, 3 month and 2 days
Datium::now()->sub('1 year')
             ->sub('3 month')
             ->sub('2 day')
             ->get();
// output => 2014-09-29 00:00:00
```

Date Difference
---------------

[](#date-difference)

This method will return the difference between two specific date with php date interval type.

```
// current generated date difference with next 5000 days
$diff = Datium::diff(
    Datium::now()->object(),
    Datium::now()->add('5000 day')->object()
);

echo $diff->days;
// output => 5000
echo $diff->year . ' year, ' .  $diff->month . ' month, ' . $diff->day . ' day ';
// ouput => 13 year, 8 month, 7 day
```

### Human readable time difference

[](#human-readable-time-difference)

Datium also supports human readable date and time difference.

```
// current generated date difference with next 5000 days
$diff = Datium::diff(
    Datium::now()->object(),
    Datium::now()->add('5000 day')->object()
)->simple->get();

// result => 13 years ago

// current generated date difference with next 5000 days
$diff = Datium::diff(
    Datium::now()->object(),
    Datium::now()->sub('5000 day')->object()
)->simple->get();

// result => 13 years remaining

// current generated date difference with next 5000 days
$diff = Datium::diff(
    Datium::now()->object(),
    Datium::now()->add('5000 day')->object()
)->simple->lang('fa')->get();

// result => ۱۳ سال پیش
```

Leap year
---------

[](#leap-year)

Define leap year of current year with generalization support.

```
// If current date was 2016

// Is 2016 a leap year?
Datium::now()->leap()->get();
// output => FALSE

// Is 2017 a leap year?
Datium::now()->add('1 year')->leap()->get();
// output => TRUE

Datium::now()->to('hijri')->leap()->get();
```

Get day of date
---------------

[](#get-day-of-date)

This method returns day of week or day of year with generalization support, you can add this feature to your custom calendars like other supported calendars in Datium.

Day of Year
-----------

[](#day-of-year)

What the day is in current year:

```
// If current date was 2015-09-03

Datium::now()->dayOf()->year();
// output => 246

// Day of year to Gregorian
Datium::now()->dayOf()->year();

// Day of year to Jalali
Datium::now()->to( 'jalali' )->dayOf()->year();

// Day of year to Hijri
Datium::now()->to( 'hijri' )->dayOf()->year();

// Day of year to kurdish
Datium::now()->to( 'kurdish' )->dayOf()->year();
```

Day of Week
-----------

[](#day-of-week)

What day of week is current day:

```
// If current date 'll be 2015-09-09 Thursday
Datium::now()->dayOf()->week();
// output => 5

// Day of week to Gregorian
Datium::now()->dayOf()->week();

// Day of week to Jalali
Datium::now()->to( 'jalali' )->dayOf()->week();

// Day of week to Hijri
Datium::now()->to( 'hijri' )->dayOf()->week();

// Day of week to Kurdish
Datium::now()->to( 'kurdish' )->dayOf()->week();
```

Last Day of Month
-----------------

[](#last-day-of-month)

How many days is current month

```
// Last Day of Current Month to Gregorian
Datium::now()->dayOf()->lastDayMonth();

// Last Day of Current Month to Jalali
Datium::now()->to( 'jalali' )->dayOf()->lastDayMonth();

// Last Day of Current Month to Hijri
Datium::now()->to( 'hijri' )->dayOf()->lastDayMonth();

// Last Day of Current Month to Kurdish
Datium::now()->to( 'kurdish' )->dayOf()->lastDayMonth();
```

Generalization
--------------

[](#generalization)

### Calendar generalization

[](#calendar-generalization)

Datium supports calendar generalization, you can add customized calendars to Datium and used them as it's own default calendars.

```
Datium::create( 2015, 11, 9 )->to( 'jalali' )->get()
//Convert Gregorian to Jalali calendar: 1394-08-18 00:00:00

Datium::create( 2015, 11, 9 )->to( 'hijri' )->get()
//Convert Gregorian to Hijri calendar: 1437-01-26 00:00:00

Datium::create( 2015, 11, 9 )->to( 'kurdish' )->get()
//Convert Gregorian to Kurdish calendar: 2715-08-18 00:00:00
```

Convert all calendars which supported on Datium or event your customized calendars as simple as possible:

```
Datium::create( 1395, 7, 25 )->from( 'jalali' )->get(); // Gregorian is default value for destination calendar.
// result: 2016-10-16 00:00:00

Datium::create( 1395, 7, 25 )->from( 'jalali' )->to( 'hijri' )->get();
// result: 1438-01-14 00:00:00
```

### Translation Generalization

[](#translation-generalization)

Generalization in translation is another Datium generalization support.

```
Datium::create( 2016, 6, 25, 12, 0, 0 )->to( 'jalali' )->lang( 'fa' )->get('l jS F Y h:i:s A');
// ex: شنبه ۵ تیر ۱۳۹۵ ۱۲:۰۰:۰۰ ب.ظ

Datium::create( 2016, 6, 25, 12, 0, 0 )->to( 'jalali' )->get('l jS F Y h:i:s A');
// ex: Shanbe 5th Tir 1395 12:00:00 PM

Datium::create(2016, 6, 25, 12, 0, 0)->to('hijri')->get('l jS F Y h:i:s A');
// ex: as-Sabt 19th Ramadan 1437 12:00:00 PM

Datium::create(2016, 6, 25, 12, 0, 0)->to('kurdish')->get('l jS F Y h:i:s A');
// ex: Şeme 5th Puşper 2716 12:00:00 PM

Datium::create(2016, 6, 25, 12, 0, 0)->get('l jS F Y h:i:s A');
// ex: Saturday 25th June 2016 12:00:00 PM
```

### Change Configuration

[](#change-configuration)

You can change any configuration after initialize Datium object.

```
$datium = Datium::create(
                $date->format('Y'),
                $date->format('m'),
                $date->format('d'),
                $date->format('h'),
                $date->format('i'),
                $date->format('s')
            );
$datium->setConfig(['timezone'=>'Europe/Istanbul']);
```

#### Default configuration

[](#default-configuration)

```
[
  'timezone' => 'Asia/Tehran',
  'language' =>     'en',
  'default_calendar' => 'gregorian',
  'date_interval' => [ 'D', 'M', 'Y', 'HT', 'MT', 'ST' ],
  'date_simple' => [ 'day', ' month', ' year', ' hour', ' minute', ' second' ],
]

```

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity24

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 61.3% 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 ~54 days

Recently: every ~24 days

Total

11

Last Release

3080d ago

Major Versions

0.0.8 → 1.0.02017-09-20

### Community

Maintainers

![](https://www.gravatar.com/avatar/777517a63bd0dc7990a0e1642b0660cc3662b49d8565ff3542a23e1560c7187f?d=identicon)[imehdihosseini](/maintainers/imehdihosseini)

![](https://www.gravatar.com/avatar/7d0d17c09494179436acaa9b450813e9dfb96c0e41fe3b20598ccc50707aaa0e?d=identicon)[ShahrokhNiakan](/maintainers/ShahrokhNiakan)

---

Top Contributors

[![imehdihosseini](https://avatars.githubusercontent.com/u/2538971?v=4)](https://github.com/imehdihosseini "imehdihosseini (111 commits)")[![shahrokhniakan](https://avatars.githubusercontent.com/u/12880941?v=4)](https://github.com/shahrokhniakan "shahrokhniakan (64 commits)")[![delirehberi](https://avatars.githubusercontent.com/u/803964?v=4)](https://github.com/delirehberi "delirehberi (3 commits)")[![gitter-badger](https://avatars.githubusercontent.com/u/8518239?v=4)](https://github.com/gitter-badger "gitter-badger (1 commits)")[![gladx](https://avatars.githubusercontent.com/u/9036557?v=4)](https://github.com/gladx "gladx (1 commits)")[![vahid-almasi](https://avatars.githubusercontent.com/u/8123263?v=4)](https://github.com/vahid-almasi "vahid-almasi (1 commits)")

---

Tags

calendarcalendarscustom-calendarcustom-calendarsdate-converterdate-formatdate-parserdatetimejalalijalali-calendarkurdishkurdishcalendarleap-yearphpconvertdatetimecalendarJalalihijrigregorian

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/opencafe-datium/health.svg)

```
[![Health](https://phpackages.com/badges/opencafe-datium/health.svg)](https://phpackages.com/packages/opencafe-datium)
```

###  Alternatives

[league/period

Time range API for PHP

7335.4M21](/packages/league-period)[fisharebest/ext-calendar

Implementation of the Arabic (Hijri), French, Gregorian, Jewish, Julian and Persian (Jalali) calendars. Also provides a replacement for the PHP ext/calendar extension.

36473.2k8](/packages/fisharebest-ext-calendar)[morilog/jalali

This Package helps developers to easily work with Jalali (Shamsi or Iranian) dates in PHP applications, based on Jalali (Shamsi) DateTime class.

9201.2M45](/packages/morilog-jalali)[aeon-php/calendar

PHP type safe, immutable calendar library

2079.7M16](/packages/aeon-php-calendar)[hekmatinasser/verta

This Package helps developers to work with Jalali Datetime class for Laravel Framework PHP

657530.5k27](/packages/hekmatinasser-verta)[p3ym4n/jdate

Date converter from Jalali to Georgian and vice versa. It has Carbon instance inside and it's Laravel friendly.

101.8k2](/packages/p3ym4n-jdate)

PHPackages © 2026

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