README

^{A quality of life extension for PHPs datetime libraries}

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 is simple using composer.

composer require kusabi/datetime

Or simply add it to your composer.json file

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

Contributing

This library follows PSR-1 & PSR-2 standards.

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

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

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

vendor/bin/phan

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

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

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

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

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

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

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

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

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

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

use Kusabi\Date\DateInterval;

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

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

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

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

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

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();

kusabi / datetime

Maintainers

Details

README

Compatibility and dependencies

Installation

Contributing

Unit Tests

Code sniffer

Static Analyses

Benchmarks

Documentation

Examples of whole library

Using the DateTime class

Creating DateTime instances

Reading DateTime instances

Modifying DateTime instances

Converting DateTime instances

Using the DateInterval class

Creating DateInterval instances

Reading DateInterval instances

Modifying DateInterval instances

Using the DatePeriod class

Creating DatePeriod instances

Reading DateInterval instances

DateTimeZone