fresh / datetime
PHP library that provides additional functions for processing dates & times.
Fund package maintenance!
fre5h
Installs: 187 090
Dependents: 3
Suggesters: 0
Security: 0
Stars: 15
Watchers: 1
Forks: 1
Open Issues: 0
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
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.