fresh/datetime

PHP library that provides additional functions for processing dates & times.

v4.1.0 2024-12-04 21:22 UTC

Requires

• php: >=8.3
• psr/clock: ^1.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• phpstan/phpstan: ^1.12
• phpstan/phpstan-phpunit: ^1.4
• phpunit/phpunit: ^11.3
• slam/phpstan-extensions: ^6.4
• squizlabs/php_codesniffer: ^3.10
• thecodingmachine/phpstan-strict-rules: ^1.0

MIT

• Artem Henvald

• time
• date
• timezone
• datetime
• midnight

README

PHP library that provides additional functions for processing dates & times. 🐘 🕒 📅

Requirements

• PHP 8.3

Installation 🌱

composer req fresh/datetime

Features 🎁

Popular time constants

Number of seconds in a minute, number of minutes in an hour, etc.

use Fresh\DateTime\TimeConstants;

echo TimeConstants::NUMBER_OF_SECONDS_IN_AN_HOUR; // etc.

Methods for creating current \DateTime and \DateTimeImmutable objects (convenient for testing)

If you use separate class for creating datetime objects, you can mock these methods in your code and have the expected \DateTime object what you need.

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$now1 = $dateTimeHelper->getCurrentDatetime();
$now2 = $dateTimeHelper->getCurrentDatetime(new \DateTimeZone('Europe/Kyiv')); // Or with custom timezone
$now3 = $dateTimeHelper->getCurrentDatetimeUtc(); // Always in UTC
$now4 = $dateTimeHelper->getCurrentDatetimeImmutable();
$now5 = $dateTimeHelper->getCurrentDatetimeImmutable(new \DateTimeZone('Europe/Kyiv')); // Or with custom timezone
$now6 = $dateTimeHelper->getCurrentDatetimeImmutableUtc(); // Always in UTC

Compatible with PSR-20: Clock.

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$now = $dateTimeHelper->now(); // \DateTimeImmutable in UTC

Method for getting current timestamp

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$timestamp = $dateTimeHelper->getCurrentTimestamp();

Method for creating \DateTime or \DateTimeImmutable from format

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

// By default with format Y-m-d H:i:s and UTC timezone
$dateTime = $dateTimeHelper->createDateTimeFromFormat('2000-01-01 00:00:00');
$dateTimeImmutable = $dateTimeHelper->createDateTimeImmutableFromFormat('2000-01-01 00:00:00');

// With custom format
$dateTime = $dateTimeHelper->createDateTimeFromFormat('01.01.2000 00:00:00', 'd.m.Y H:i:s');

// With custom timezone
$dateTime = $dateTimeHelper->createDateTimeFromFormat('01.01.2000 00:00:00', 'd.m.Y H:i:s', new \DateTimeZone('Europe/Kyiv'));

Method for creating \DateTimeZone object

If you create a \DateTimeZone object directly in your code, you will not be able to mock it in tests. So there is a specific method for creating timezone object.

use Fresh\DateTime\DateTimeHelper;

$dateTimeHelper = new DateTimeHelper();

$dateTimeZone1 = $dateTimeHelper->createDateTimeZone(); // UTC by default
$dateTimeZone2 = $dateTimeHelper->createDateTimeZone('Europe/Kyiv'); // Or with custom timezone
$dateTimeZone3 = $dateTimeHelper->createDateTimeZoneUtc(); // Another method to get UTC timezone

Immutable DateRange ValueObject

You often needed to manipulate with since/till dates, so-called date ranges. By its nature, date range is a ValueObject, it can be reused many times for different purposes. This library provides a DateRange immutable class, which is not able to be changed after its creation. DateRange operates only with dates and ignore time.

use Fresh\DateTime\DateRange;

$dateRange1 = new DateRange(new \DateTime('yesterday'), new \DateTime('tomorrow'));
$dateRange2 = new DateRange(new \DateTime('yesterday'), new \DateTime('tomorrow', new \DateTimeZone('Europe/Kyiv')));

// There is also the `isEqual` method to compare two DateRange objects.
$dateRange1->isEqual($dateRange2); // Returns FALSE, because date ranges have different timezones

Immutable DateTimeRange ValueObject

This library provides also immutable class DateTimeRange, instead of DateRange it checks date and time.

use Fresh\DateTime\DateTimeRange;

$dateTimeRange1 = new DateTimeRange(new \DateTime('2000-01-01 19:00:00'), new \DateTime('2000-01-01 21:00:00'));
$dateTimeRange2 = new DateTimeRange(new \DateTime('2000-01-01 19:00:00'), new \DateTime('2000-01-01 21:00:00', new \DateTimeZone('Europe/Kyiv')));
$dateTimeRange3 = new DateTimeRange(new \DateTime('2000-01-01 20:00:00'), new \DateTime('2000-01-01 22:00:00'));

// There is also the `isEqual` method to compare two DateTimeRange objects.
$dateTimeRange1->isEqual($dateTimeRange2); // Returns FALSE, because datetime ranges have different timezones

// There is also the `intersects` method to check if datetime range intersected each other.
$dateTimeRange1->intersects($dateTimeRange3); // Returns TRUE, because datetime ranges are intersected

Examples of date ranges with intersection

Examples of date ranges without intersection

Getting array of objects/strings of all dates in date range

use Fresh\DateTime\DateTimeHelper;
use Fresh\DateTime\DateRange;

$dateTimeHelper = new DateTimeHelper();

$dateRange = new DateRange(new \DateTime('1970-01-01'), new \DateTime('1970-01-03'));

// Creates array with values ['1970-01-01', '1970-01-02', '1970-01-03']
$datesAsStrings = $dateTimeHelper->getDatesFromDateRangeAsArrayOfStrings($dateRange);

// Creates array of \DateTime objects for dates: '1970-01-01', '1970-01-02', '1970-01-03'
$datesAsObjects = $dateTimeHelper->getDatesFromDateRangeAsArrayOfObjects($dateRange);

DateTimeCloner allows to clone dates into \DateTime or \DateTimeImmutable instances

use Fresh\DateTime\DateTimeCloner;

$dateTimeCloner = new DateTimeCloner();

$date1 = new \DateTime();
$dateImmutable1 = $dateTimeCloner::cloneIntoDateTimeImmutable($date1); // Returns \DateTimeImmutable object
$date2 = $dateTimeCloner::cloneIntoDateTime($dateImmutable1); // Returns \DateTime object

Contributing 🤝

See CONTRIBUTING file.