glucnac / datetimeinterval
DateTimeInterval is wrapper of DateInterval that provides useful methods for calculating delays.
Requires
- php: ^7.4|^8.1
Requires (Dev)
- mockery/mockery: ^1.5
- php-parallel-lint/php-parallel-lint: ^1.3
- phpstan/phpstan: ^1.8
- phpstan/phpstan-mockery: ^1.1
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.7
README
When you want to compute a delay between two DateTimes, it can be quickly tricky to get the result you are expecting for, and sometimes you need to perform some calculations, which can lead to incorrect result.
DateTimeInterval is wrapper of DateInterval that provides useful methods for calculating delays. Thanks to this library, there is no need to compute results returned from DateInterval anymore. Moreover, all of its methods are fully tested, and are explicitly named and commented.
In that way, you don't have to copy/paste the logic you implemented on another project, just install this library and enjoy.
Installation
The preferred method of installation is via Composer. Run the following
command to install the package and add it as a requirement to your project's
composer.json:
composer require glucnac/datetimeinterval
What is the purpose ?
To understand the usefulness of this library, let's try to compute some delays.
Get delays using date_diff()
// Let's say you want to compute some delays between 2022-07-15 and 2022-08-15.
$firstDate = new DateTimeImmutable('2022-07-15');
$secondDate = new DateTimeImmutable('2022-08-15');
$dateInterval = date_diff($secondDate, $firstDate);
// OR
$dateInterval = $firstDate->diff($secondDate);
// You want to count the days between these two dates. Using DateInterval,
// you notice that two properties are available :
// PhpDoc : Totals number of days in the interval span.
$dateInterval->days;
// PhpDoc : Number of days.
$dateInterval->d;
// Well, the doc of ->d is not really clear, let's see the difference between these two returns
$dateInterval->days; // 30
$dateInterval->d; // 0
// Nice, it seems ->d is a relative count, whereas ->days give an absolute count
// What about getting the number of months then ?
// PhpDoc : number of months
$dateInterval->m // 1
// Seems to be ok. What about changing the year to next one :
$firstDate = new DateTimeImmutable('2022-07-15');
$secondDate = new DateTimeImmutable('2023-08-15');
$dateInterval = date_diff($secondDate, $firstDate);
$dateInterval->m // 1
// ->m also returns a relative count
Actually, ->y, ->m, ->d, ->h, ->i, ->s, ->f : all are returning a relative count, which means that for any absolute result, you must perform some calculations using ->days, which is the only result to be absolute. Even though these calculations are simple, rewriting them on each of your project is boring and can lead to inattention mistakes.
That's why this library has been made for : to abstract the calculations and to get a more object-oriented coding.
Get delays using DateTimeInterval
$firstDate = new DateTimeImmutable('2022-07-15');
$secondDate = new DateTimeImmutable('2022-08-15');
$dateTimeInterval = new DateTimeInterval($firstDate, $secondDate);
// Absolute count of days
$dateTimeInterval->getDays();
// Relative count of days
$dateTimeInterval->getDays(false);
// Absolute count of months
$dateTimeInterval->getMonths();
// Relative count of months
$dateTimeInterval->getMonths(false);
// And so on...
// Nostalgic about DateInterval ?
$dateInterval = $dateTimeInterval->getDateInterval();
Copyright and License
The GlucNAc/DateTimeInterval library is copyright © GlucNAc and licensed for use under the MIT License (MIT). Please see LICENSE for more information.