PHPackages                             kusabi/datetime - 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. kusabi/datetime

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

kusabi/datetime
===============

An extension of PHPs datetime libraries

1.0.1(4y ago)13MITPHPPHP >=5.6

Since Nov 10Pushed 3y ago1 watchersCompare

[ Source](https://github.com/kusabi/datetime)[ Packagist](https://packagist.org/packages/kusabi/datetime)[ RSS](/packages/kusabi-datetime/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (4)Versions (3)Used By (0)

Datetime
========

[](#datetime)

[![Tests](https://github.com/kusabi/datetime/workflows/tests/badge.svg)](https://github.com/kusabi/datetime/workflows/tests/badge.svg)[![codecov](https://camo.githubusercontent.com/8f70b9cd286f6e6a895a3425b6579a78e384b5f78cebfcb234199f0b1a39fb36/68747470733a2f2f636f6465636f762e696f2f67682f6b75736162692f6461746574696d652f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/kusabi/datetime)[![Licence Badge](https://camo.githubusercontent.com/37773d6246fdfac7121afbf23cc592163ada28cc703c1f693fd3a898717f0887/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6b75736162692f6461746574696d652e737667)](https://img.shields.io/github/license/kusabi/datetime.svg)[![Release Badge](https://camo.githubusercontent.com/8a036d98cbaaea43b7754aa99291a78aea8076fe796e83d31543d57efa64d7ed/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6b75736162692f6461746574696d652e737667)](https://img.shields.io/github/release/kusabi/datetime.svg)[![Tag Badge](https://camo.githubusercontent.com/e90efa3b5f8ee72f858ea44d2e514a4fac1695cd57562238b555e55d3df38588/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7461672f6b75736162692f6461746574696d652e737667)](https://img.shields.io/github/tag/kusabi/datetime.svg)[![Issues Badge](https://camo.githubusercontent.com/201067c87b8afe87261693f07d26ce187688980e0451789fb28772b3bb92ac63/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6b75736162692f6461746574696d652e737667)](https://img.shields.io/github/issues/kusabi/datetime.svg)[![Code Size](https://camo.githubusercontent.com/1cd1530377b582b2bc58aecb18664b70333c4d9ff74d7395ca5d017cdb06eba9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6b75736162692f6461746574696d652e7376673f6c6162656c3d73697a65)](https://img.shields.io/github/languages/code-size/kusabi/datetime.svg)

A quality of life extension for PHPs datetime libraries

Compatibility and dependencies
------------------------------

[](#compatibility-and-dependencies)

This library is compatible with PHP version `7.2`, `7.3`, `7.4`, `8.0` and `8.1`.

This library has no dependencies.

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

[](#installation)

Installation is simple using composer.

```
composer require kusabi/datetime
```

Or simply add it to your `composer.json` file

```
{
    "require": {
        "kusabi/datetime": "^1.0"
    }
}
```

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

[](#contributing)

This library follows [PSR-1](https://www.php-fig.org/psr/psr-1/) & [PSR-2](https://www.php-fig.org/psr/psr-2/) standards.

#### Unit Tests

[](#unit-tests)

Before pushing any changes, please ensure the unit tests are all passing.

If possible, feel free to improve coverage in a separate commit.

```
vendor/bin/phpunit
```

#### Code sniffer

[](#code-sniffer)

Before pushing, please ensure you have run the code sniffer. **Only run it using the lowest support PHP version (5.6)**

```
vendor/bin/php-cs-fixer fix
```

#### Static Analyses

[](#static-analyses)

Before pushing, please ensure you have run the static analyses tool.

```
vendor/bin/phan
```

#### Benchmarks

[](#benchmarks)

Before pushing, please ensure you have checked the benchmarks and ensured that your code has not introduced any slowdowns.

Feel free to speed up existing code, in a separate commit.

Feel free to add more benchmarks for greater coverage, in a separate commit.

```
vendor/bin/phpbench run --report=quick
vendor/bin/phpbench run --report=quick --output=markdown
vendor/bin/phpbench run --report=quick --filter=benchNetFromTax --iterations=50 --revs=50000

vendor/bin/phpbench xdebug:profile
vendor/bin/phpbench xdebug:profile --gui
```

Documentation
-------------

[](#documentation)

This section covers documentation for using the datetime library.

The library extends each of the native PHP datetime classes to make each of them a little more useful and user-friendly.

### Examples of whole library

[](#examples-of-whole-library)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DatePeriod;
use Kusabi\Date\DateInterval;

// Tomorrow end of working day
$date = DateTime::tomorrow()->setTime(5,0,0);

// Password expires in 30 days
$date = DateTime::today()->addDays(30);

// Password expires in 30 days (end of day)
$date = DateTime::now()->addDays(30)->endOfDay();

// Get the number of days between two dates
$from = DateTime::createFromFormat('Y-m-d', '2000-01-01');
$to = DateTime::createFromFormat('Y-m-d', '2003-05-01');
$days = $from->diff($to)->getDays(); // 1120

// Get all the dates between two dates
$from = DateTime::createFromFormat('Y-m-d', '2022-01-01');
$to = DateTime::createFromFormat('Y-m-d', '2022-01-10');
$dates = DatePeriod::instance($from, DateInterval::day(), $to)->getDateTimes();
$dates = $from->getDateTimesTo($to);
```

### Using the DateTime class

[](#using-the-datetime-class)

The `DateTime` class has been extended to add new ways of creating, reading, modifying and converting the instance.

#### Creating DateTime instances

[](#creating-datetime-instances)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DateTimeZone;

// Create a basic instance
$date = new DateTime();
$date = new DateTime('monday');
$date = new DateTime('tomorrow');

// Create an instance with a chain-able static method
$date = DateTime::instance();
$date = DateTime::instance('monday');
$date = DateTime::instance('tomorrow');

// Create from values
$date = DateTime::createFromDate(2022, 12, 31);
$date = DateTime::createFromDateAndTime(2022, 12, 31, 12, 30, 12);
$date = DateTime::createFromDateAndTime(2022, 12, 31, 12, 30, 12, 6405);

// Create from custom format
$date = DateTime::createFromFormat('Y-m-d H:i:s', '2022-01-01 10:30:02');
$date = DateTime::createFromFormat('Y-m-d H:i:s', '2022-01-01 10:30:02', DateTimeZone::LondonEurope());

// Create an instance from another instance
$date = DateTime::createFromInstance(new \DateTime());
$date = DateTime::createFromInstance(new \Carbon());
$date = DateTime::createFromInstance(new DateTime());

// Quick shorthand creators
$date = DateTime::now();       // 2020-01-02 12:30:00
$date = DateTime::today();     // 2020-01-02 00:00:00
$date = DateTime::yesterday(); // 2020-01-01 00:00:00
$date = DateTime::tomorrow();  // 2020-01-03 00:00:00

// Create from timestamps or micro-time
$date = DateTime::createFromTimestamp(time());
$date = DateTime::createFromTimestamp(microtime(true));
$date = DateTime::createFromTimestamp(microtime());
$date = DateTime::createFromTimestamp(time(), DateTimeZone::LondonEurope());
$date = DateTime::createFromTimestamp(microtime(true), DateTimeZone::LondonEurope());
$date = DateTime::createFromTimestamp(microtime(), DateTimeZone::LondonEurope());
```

#### Reading DateTime instances

[](#reading-datetime-instances)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DateTimeZone;

$date = DateTime::createFromFormat('Y-m-d H:i:s', '2030-12-25 07:30:00');

// Reading units
$date->getDayOfMonth();      // 25
$date->getDayOfWeek();       // 1
$date->getDayName();         // Monday
$date->getDayShortName();    // Mon
$date->getDaysInMonth();     // 31
$date->getDaysLeftInMonth(); // 6
$date->getMonth();           // 1
$date->getMonthName();       // January
$date->getMonthShortName();  // Jan
$date->getYear();            // 2030
$date->getDayOfYear();       // 358
$date->getHours();           // 7
$date->getMinutes();         // 30
$date->getSeconds();         // 0
$date->getMicroseconds();    // 0

// Convert to native datetime
$native = $date->toNative();

// Get the timezone
$date->getTimezone();
$date->getTimezone()->getCountryCode(); // CZ

// Common checks
$date->isWeekday(); // true
$date->isWeekend(); // false
```

#### Modifying DateTime instances

[](#modifying-datetime-instances)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DateTimeZone;

// Set time zone
$date = new DateTime();
$date->setTimezone(DateTimeZone::LondonEurope());
$date->setTimezone(DateTimeZone::AbidjanAfrica(), true); // Lock the date time string, by translating the timestamp by the offset

// Update from format
$date = new DateTime();
$date->setFromFormat('Y-m-d H:i:s', '2030-12-25 07:30:00');

// Moving to limits
$date = new DateTime();
$date->endOfDay(); // 2020-01-02 23:59:59
$date->endOfMonth(); // 2020-01-31 00:00:00
$date->endOfMonth()->endOfDay(); // 2020-01-31 23:59:59
$date->startOfDay(); // 2020-01-02 00:00:00

// Setting units
$date->setDay(25);
$date->setMonth(12);
$date->setYear(12);
$date->setDate(2020, 12, 25);
$date->setHours(7);
$date->setMinutes(30);
$date->setSeconds(30);
$date->setMicroseconds(500);
$date->setTime(7, 30, 0);
$date->setTime(7, 30, 0, 500);
$date->setDay(25)->setMonth(12)->setYear(2020)->setTime(7, 30, 0);
$date->setDate(2020, 12, 25)->setTime(7, 30, 0);
$date->setDateAndTime(2020, 12, 25, 7, 30, 0);
$date->setDateAndTime(2020, 12, 25, 7, 30, 0, 34623);
$date->setFromFormat('Y-m-d H:i:s.u', '2023-12-31 12:30:00.555666');

// Adding units
$date->addMicrosecond();
$date->addMicroseconds(10);
$date->addSecond();
$date->addSeconds(10);
$date->addMinute();
$date->addMinutes(10);
$date->addHour();
$date->addHours(10);
$date->addDay();
$date->addDays(10);
$date->addMonth();
$date->addMonths(10);
$date->addYear();
$date->addYears(10);

// Subtracting units
$date->subMicrosecond();
$date->subMicroseconds(10);
$date->subSecond();
$date->subSeconds(10);
$date->subMinute();
$date->subMinutes(10);
$date->subHour();
$date->subHours(10);
$date->subDay();
$date->subDays(10);
$date->subMonth();
$date->subMonths(10);
$date->subYear();
$date->subYears(10);
```

#### Converting DateTime instances

[](#converting-datetime-instances)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DateTimeZone;

// Cast to string
$date = DateTime::createFromFormat('Y-m-d H:i:s', '2020-06-18 14:11:22', DateTimeZone::BrokenHillAustralia());
echo $datetime->toString(); // 2020-06-18T14:11:22+09:30
echo (string) $datetime; // 2020-06-18T14:11:22+09:30
```

Using the DateInterval class
----------------------------

[](#using-the-dateinterval-class)

The `DateInterval` class has been extended to add new ways of creating, reading, modifying, optimising, cloning and converting the instance.

#### Creating DateInterval instances

[](#creating-dateinterval-instances)

```
use Kusabi\Date\DateInterval;

// Create a basic instance
$interval = new DateInterval(); // Defaults to PT0S (0 second interval)
$interval = new DateInterval('P1YT10S');

// Create an instance with a chain-able static method
$interval = DateInterval::instance(); // Defaults to PT0S (0 second interval)
$interval = DateInterval::instance('P1YT10S');

// Create an instance from another instance
$interval = DateInterval::createFromInstance(new \DateInterval('P1YT10S'));
$interval = DateInterval::createFromInstance(new \Carbon\CarbonInterval('P1YT10S'));
$interval = DateInterval::createFromInstance(new DateInterval('P1YT10S'));

// Create from values
$interval = DateInterval::createFromValues(1, 2, 3, 4, 5, 6); // years, months, days, hours, minutes, seconds

// Quickly create common intervals
$interval = DateInterval::second();
$interval = DateInterval::seconds(15);
$interval = DateInterval::minute();
$interval = DateInterval::minutes(30);
$interval = DateInterval::hour();
$interval = DateInterval::hours(8);
$interval = DateInterval::day();
$interval = DateInterval::days(7);
$interval = DateInterval::week();
$interval = DateInterval::weeks(4);
$interval = DateInterval::month();
$interval = DateInterval::months(6);
$interval = DateInterval::year();
$interval = DateInterval::years(100);
```

#### Reading DateInterval instances

[](#reading-dateinterval-instances)

```
use Kusabi\Date\DateInterval;

// Get the spec from the instance
$interval = DateInterval::year()->getSpec(); // P1Y
```

#### Modifying DateInterval instances

[](#modifying-dateinterval-instances)

```
use Kusabi\Date\DateInterval;

// Optimise the interval into it's larger components
$interval = DateInterval::seconds(125)->optimise(); // Becomes PT2M5S (2 minutes and 5 seconds)

// Optimise into a cloned instance
$interval = DateInterval::seconds(125);
$optimisedClone = $interval->optimised();

// Clone the instance
$interval = new DateInterval();
$cloned = $interval->cloned();

// Modifying the instance
$interval = new DateInterval();
$interval->addSecond();
$interval->addSeconds(10);
$interval->addMinute();
$interval->addMinutes(10);
$interval->addHour();
$interval->addHours(10);
$interval->addDay();
$interval->addDays(10);
$interval->addMonth();
$interval->addMonths(10);
$interval->addYear();
$interval->addYears(10);
$interval->addInterval(new \DateInterval('P1YT10S'));
$interval->addInterval(DateInterval::month());

$interval->subSecond();
$interval->subSeconds(10);
$interval->subMinute();
$interval->subMinutes(10);
$interval->subHour();
$interval->subHours(10);
$interval->subDay();
$interval->subDays(10);
$interval->subMonth();
$interval->subMonths(10);
$interval->subYear();
$interval->subYears(10);
$interval->subInterval(new \DateInterval('P1YT10S'));
$interval->subInterval(DateInterval::month());
```

Using the DatePeriod class
--------------------------

[](#using-the-dateperiod-class)

The `DatePeriod` class has been extended to add new ways of creating, reading, modifying, optimising, cloning and converting the instance.

#### Creating DatePeriod instances

[](#creating-dateperiod-instances)

```
use Kusabi\Date\DateTime;
use Kusabi\Date\DatePeriod;

// Create a basic instance
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5));

// Create an instance with a chain-able static method
$period = DatePeriod::instance(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5));

// Create an instance from another instance
$period = DatePeriod::createFromInstance(new \DatePeriod('P1YT10S'));
$period = DatePeriod::createFromInstance(new \Carbon\CarbonPeriod('P1YT10S'));
$period = DatePeriod::createFromInstance(new DatePeriod('P1YT10S'));
```

#### Reading DateInterval instances

[](#reading-dateinterval-instances-1)

```
use Kusabi\Date\DatePeriod;
use Kusabi\Date\DateInterval;

// Get the interval
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5))
$interval = $period->getDateInterval()->getSpec(); // P1D

// Get the start datetime
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5))
$datetime = $period->getStartDate()->format('Y-m-d'); // '2022-01-01'

// Get the end datetime
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5))
$datetime = $period->getEndDate()->format('Y-m-d'); // '2022-01-06'

// Get the all the date times as an array
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5))
$dates = $period->getDateTimes();

// Converting to a string
$period = new DatePeriod(DateTime::today(), DateInterval::day(), DateTime::today()->addDays(5))
$period->toString(); // every +1 day between 2022-01-01T00:00:00+00:00 and 2022-01-06T00:00:00+00:00
(string) $period; // every +1 day between 2022-01-01T00:00:00+00:00 and 2022-01-06T00:00:00+00:00
```

DateTimeZone
------------

[](#datetimezone)

```
use Kusabi\Date\DateTimeZone;

// Create a basic instance
$timezone = new DateTimeZone();
$timezone = new DateTimeZone('Asia/Yakutsk');

// Create an instance with a chain-able static method
$timezone = DateTimeZone::instance();
$timezone = DateTimeZone::instance('Asia/Yakutsk');

// Create an instance from another instance
$legacy = new \DateTimeZone('UTC');
$timezone = DateTimeZone::createFromInstance($legacy);

// Quickly create timezones for a particular area
$timezone = DateTimeZone::PerthAustralia();
$timezone = DateTimeZone::PhoenixAmerica();
$timezone = DateTimeZone::TokyoAsia();

// Quick access to timezone data
$lat = $timezone->getLatitude();
$lon = $timezone->getLongitude();
$code = $timezone->getCountryCode();
```

###  Health Score

23

—

LowBetter than 27% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

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

Every ~222 days

Total

2

Last Release

1793d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/62f4942978644437b5ff3d7bd3f6411580413d327b001104acd4914f43ab63b6?d=identicon)[kusabi](/maintainers/kusabi)

---

Top Contributors

[![kusabi](https://avatars.githubusercontent.com/u/22000941?v=4)](https://github.com/kusabi "kusabi (25 commits)")

---

Tags

datedatesdatetimeextensionlibraryphpphp5php7

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/kusabi-datetime/health.svg)

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

###  Alternatives

[producer/producer

Tools for releasing library packages; supports Git, Mercurial, Github, Gitlab, and Bitbucket.

10418.7k2](/packages/producer-producer)[fabianmichael/kirby-meta

Your all-in-one powerhouse for any SEO and metadata needs imaginable.

6910.7k1](/packages/fabianmichael-kirby-meta)[n98/headless-guillotine

Frontend routing whitelist configurations for headless setups.

2627.2k](/packages/n98-headless-guillotine)[silverstripe/multiuser-editing-alert

A module that indicates when people are editing the same page in the CMS

1530.7k1](/packages/silverstripe-multiuser-editing-alert)[evilfreelancer/openvpn-php

OpenVPN config generator writen on PHP

304.7k](/packages/evilfreelancer-openvpn-php)[lucapuddu/php-provably-fair

PhpProvablyFair is a library that generates and verifies provably fair games.

154.9k](/packages/lucapuddu-php-provably-fair)

PHPackages © 2026

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