PHPackages                             gokhankurtulus/chronos - 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. gokhankurtulus/chronos

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

gokhankurtulus/chronos
======================

A simple PHP library for working with date and time.

1.0.0(2y ago)05MITPHPPHP ^8.1 || ^8.2

Since Dec 31Pushed 2y ago1 watchersCompare

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

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

Chronos
=======

[](#chronos)

[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)](https://camo.githubusercontent.com/7535257ca228724c93658bd52583d4e47a9bab02c356abf6e54c1d575f2151e6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c75652e737667)[![Release](https://camo.githubusercontent.com/51dac79cdba7034dfab7de63a91b1d9745e2b5afbb29481ebb1f482e013b7dc7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f676f6b68616e6b757274756c75732f6368726f6e6f732e737667)](https://camo.githubusercontent.com/51dac79cdba7034dfab7de63a91b1d9745e2b5afbb29481ebb1f482e013b7dc7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f676f6b68616e6b757274756c75732f6368726f6e6f732e737667)

A simple PHP library for working with date and time.

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

[](#installation)

You can install the library using Composer. Run the following command:

```
composer require gokhankurtulus/chronos
```

Usage
-----

[](#usage)

Chronos uses DateTimeImmutable when working with instances.

- [Initialize](#initialize)
- [Date Creation](#date-creation)
- [Manipulation](#manipulation)
- [Comparison](#comparison)
- [Multi-Language Printing](#multi-language-printing)
- [More](#more)

### Initialize

[](#initialize)

You can set default timezone, format and current language for multi-language printing.

```
use Chronos\Chronos;
use Chronos\TimeUnitTranslator;

$format = "Y-m-d H:i:s";
$timezone = "Europe/Istanbul";
$allowedLanguages = ["en", "tr"];
$currentLanguage = "tr";
$defaultLanguage = "en";

Chronos::setDefaultFormat($format);

//If you want to trigger 'date_default_timezone_set' function, set second parameter as true on the 'setDefaultTimeZone' method.
Chronos::setDefaultTimeZone($timezone, true);

// Set current language by default to pretty print.
TimeUnitTranslator::initialize($currentLanguage, $defaultLanguage, $allowedLanguages);
```

### Date Creation

[](#date-creation)

```
use Chronos\Chronos;

$timestamp = 946677600;
$time = "2000-01-01 00:00:00";
$format = "Y-m-d H:i:s";
$timezone = "Europe/Istanbul";

Chronos::setDefaultFormat($format);
Chronos::setDefaultTimeZone($timezone, true);

/**
 * Format parameter is optional. If you don't give, tries to get from Chronos::getDefaultFormat()
 * Timezone parameter is optional.
 * Indicates that date was created from this timezone.
 * If you don't give, tries to get from Chronos::getDefaultTimeZone()
 * Then tries to get from 'date_default_timezone_get()'
 */
$createFromFormat = Chronos::createFromFormat($time, $format, $timezone);

/**
 * Timezone parameter is optional.
 * Indicates that created date from timestamp will be converted to this timezone.
 * If you don't give, tries to get from Chronos::getDefaultTimeZone()
 * Then tries to get from 'date_default_timezone_get()'
 */
$createFromTimestamp = Chronos::createFromTimestamp($timestamp, $timezone);

/** Usage Examples */

$yesterday  = Chronos::yesterday();
$now        = Chronos::now();
$tomorrow   = Chronos::tomorrow();

if (Chronos::isFormattable($time, $format) && Chronos::isValidTimeZone($timezone)) {
    $createFromFormat = Chronos::createFromFormat($time, $format, $timezone);
}

if (Chronos::isTimestamp($timestamp) && Chronos::isValidTimeZone($timezone)) {
    $createFromTimestamp = Chronos::createFromTimestamp($timestamp, $timezone);
}

var_dump($createFromTimestamp);
// output:
//object(Chronos\Chronos)#4 (1) {
//  ["dateTimeImmutable":protected]=>
//  object(DateTimeImmutable)#2 (3) {
//    ["date"]=>
//    string(26) "2000-01-01 00:00:00.000000"
//    ["timezone_type"]=>
//    int(3)
//    ["timezone"]=>
//    string(15) "Europe/Istanbul"
//  }
//}
```

### Manipulation

[](#manipulation)

```
$time = "2023-12-12 00:00:00";
$format = "Y-m-d H:i:s";
$timezone = "Europe/Istanbul";

$createFromFormat = Chronos::createFromFormat($time, $format, $timezone);

$manipulatedDate = $createFromFormat
    ->addSeconds(1)
    ->addMinutes(1)
    ->addHours(1)
    ->addDays(1)
    ->addMonths(1)
    ->addYears(1);

// change timezone to actual date by timezone
$timezoneChanged = $manipulatedDate->toTimeZone('Europe/Berlin');

echo '';
var_dump($timezoneChanged->date($format));
var_dump($manipulatedDate->date($format));
var_dump($createFromFormat->date($format));
echo '';

// Output:
// string(19) "2025-01-12 23:01:01"
// string(19) "2025-01-13 01:01:01"
// string(19) "2023-12-12 00:00:00"
```

### Comparison

[](#comparison)

```
$time = "2000-01-01 00:00:00";
$format = "Y-m-d H:i:s";
$timezone1 = "Europe/Istanbul";
$timezone2 = "Europe/Berlin";

$first = Chronos::createFromFormat($time, $format, $timezone1);
$second = Chronos::createFromFormat($time, $format, $timezone2);

var_dump($first->age()); // executed in: 2023, output: 23.

/** $targetDateTime can be Chronos|DateTimeInterface */
var_dump($first->isPast($second)); // output: true

/** $targetDateTime can be Chronos|DateTimeInterface */
var_dump($first->isFuture($second)); // output: false

/** $targetDateTime can be Chronos|DateTimeInterface */
var_dump($first->isSameDay($second)); // output: true

var_dump($first->isWeekday()); // output: false
var_dump($first->isWeekend()); // output: true

/** $targetDateTime can be Chronos|DateTimeInterface */
var_dump($first->dayDiff($second)); // output: int(0)

/** $targetDateTime can be Chronos|DateTimeInterface */
var_dump($first->diff($second)); // output is similar to diffFromFormat method

var_dump($first->diffFromFormat($time, $format, $timezone2));
// same output for diff and diffFromFormat methods:
//object(DateInterval)#7 (10) {
//  ["y"]=>
//  int(0)
//  ["m"]=>
//  int(0)
//  ["d"]=>
//  int(0)
//  ["h"]=>
//  int(1)
//  ["i"]=>
//  int(0)
//  ["s"]=>
//  int(0)
//  ["f"]=>
//  float(0)
//  ["invert"]=>
//  int(0)
//  ["days"]=>
//  int(0)
//  ["from_string"]=>
//  bool(false)
//}
}
```

### Multi-Language Printing

[](#multi-language-printing)

Visit [gokhankurtulus/multilanguage](https://github.com/gokhankurtulus/multilanguage) repository for more about the library.

```
// If you want to initialize TimeUnitTranslator,
// then you can give null to $lang parameter when you want to use translations
// default language is 'en'.
// If you don't set current language and give null it will try to get default language
/** @see https://github.com/gokhankurtulus/multilanguage for more usage examples */

use Chronos\TimeUnitTranslator;

// check src/Lang for supported languages
$allowedLanguages = ["en"]; // then you can set allowed languages whatever you want.
$currentLanguage = "en";
$defaultLanguage = "en";

if (!TimeUnitTranslator::isAllowedLanguage($currentLanguage)) {
    die("Language: '$currentLanguage' is not allowed.");
}
if (!TimeUnitTranslator::isAllowedLanguage($defaultLanguage)) {
    die("Language: '$defaultLanguage' is not allowed.");
}
TimeUnitTranslator::initialize($currentLanguage, $defaultLanguage, $allowedLanguages);

$time1 = "2000-01-01 00:00:00";
$time2 = "2006-06-05 03:02:01";
$format = "Y-m-d H:i:s";
$timezone = "Europe/Istanbul";

$first = Chronos::createFromFormat($time1, $format, $timezone);
$second = Chronos::createFromFormat($time2, $format, $timezone);

/**
 * you can give a $language if its supported,
 * if you want to use current language set null
 *
 * $depth can be 0-6 represents how many units do you want
 * priority order: year, month, day, hour, minute, second
 * $depth = 0 means first unit but also includes (now, today, yesterday, tomorrow)
 *
 * $targetDateTime can be Chronos|DateTimeInterface
 * if you don't give it will be Chronos::now()
* */

var_dump($first->prettyDiff(null, 6, $second));
// output: string(54) "6 years 5 months 4 days 3 hours 2 minutes 1 second ago"

var_dump($first->prettyDiff(null, 2, $second));
// output: string(20) "6 years 5 months ago"

$time1 = "2000-01-01 00:00:00";
$time2 = "2000-01-01 00:01:59";
// If times are given like this then,
$first = Chronos::createFromFormat($time1, $format, $timezone);
$second = Chronos::createFromFormat($time2, $format, $timezone);

var_dump($first->prettyDiff("en", 0, $second));
// output: string(3) "now"

var_dump($first->prettyDiff("en"));
// executed in: 2023, output: string(12) "23 years ago"

var_dump($first->prettyDiff("tr", 0, $second));
// will throw LanguageException because given language is not set as allowed language

var_dump($first->date($format)); // if you don't pass $format default format is 'Y-m-d'
// output: string(19) "2000-01-01 00:00:00"

var_dump($first->time(false)); // $includeSeconds to false if you don't want seconds
// output: string(5) "00:00"

var_dump($first->prettyDatePrint(null, false)); // $includeYears to false if you don't want years
// output: string(10) "01 January"

// parameters are $lang, $includeYears, $includeSeconds
var_dump($first->prettyPrint());
// output: string(24) "01 January 2000 00:00:00"

var_dump($first->dayName($currentLanguage));
// output: string(8) "Saturday"

var_dump($first->monthName($currentLanguage));
// output: string(7) "January"

var_dump(\Chronos\Enums\Day::MONDAY->translate("en"));
// output: string(6) "Monday"

var_dump(\Chronos\Enums\Month::JANUARY->translate("en"));
// output: string(7) "January"

var_dump($first->second()); // output: string(2) "00"
var_dump($first->minute()); // output: string(2) "00"
var_dump($first->hour());   // output: string(4) "00"
var_dump($first->day());    // output: string(2) "01"
var_dump($first->month());  // output: string(2) "01"
var_dump($first->year());   // output: string(4) "2000"
```

### More

[](#more)

```
use Chronos\Chronos;

$time = "2000-01-01 00:00:00";
$format = "Y-m-d H:i:s";
$timezone = "Europe/Istanbul";

Chronos::getDefaultFormat();
Chronos::setDefaultFormat($format);

Chronos::getDefaultTimeZone();
Chronos::setDefaultTimeZone($timezone);

Chronos::isTimestamp($timestamp);
Chronos::isFormattable($time, $format);
Chronos::isValidFormat($format);
Chronos::isValidTimeZone($timezone);

$now = Chronos::now($timezone);
$now->format($format);
$now->timestamp();

$now->getTime(); // returns DateTimeImmutable object
$now->setTime($dateTimeImmutableObject);
```

License
-------

[](#license)

Chronos is open-source software released under the [MIT License](LICENSE). Feel free to modify and use it in your projects.

Contributions
-------------

[](#contributions)

Contributions to Chronos are welcome! If you find any issues or have suggestions for improvements, please create an issue or submit a pull request on the [GitHub repository](https://github.com/gokhankurtulus/chronos).

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

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

860d ago

### Community

Maintainers

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

---

Top Contributors

[![gokhankurtulus](https://avatars.githubusercontent.com/u/43145716?v=4)](https://github.com/gokhankurtulus "gokhankurtulus (3 commits)")

---

Tags

datetimepretty-datepretty-printdatetimepretty-printpretty date

### Embed Badge

![Health badge](/badges/gokhankurtulus-chronos/health.svg)

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

###  Alternatives

[nette/utils

🛠 Nette Utils: lightweight utilities for string & array manipulation, image handling, safe JSON encoding/decoding, validation, slug or strong password generating etc.

2.1k394.3M1.5k](/packages/nette-utils)[league/period

Time range API for PHP

7335.4M21](/packages/league-period)[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)[brick/date-time

Date and time library

3623.3M60](/packages/brick-date-time)[aeon-php/calendar

PHP type safe, immutable calendar library

2079.7M16](/packages/aeon-php-calendar)[tplaner/when

Date/Calendar recursion library.

5261.0M5](/packages/tplaner-when)

PHPackages © 2026

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