feat: add Date::earliestOf and Date::latestOf helper functions

[Jan Jablonski (jan-j)]

I often find it necessary to compare two or more Date instances in order to establish which one of them is the earliest or the latest.

My proposal here is to add two static methods Date::max and Date::min that mimic PHP's native max and min function.

There's also an alternative naming to consider latest and earliest, but since we already use native max and min with DateTime I picked these ones.

I also considered adding these as non-static methods that would be used like

$dateA = Date::fromYearMonthDayString('2018-01-01');
$dateB = Date::fromYearMonthDayString('2018-01-02');
$dateC = Date::fromYearMonthDayString('2018-01-03');

$max = $dateA->max($dateB, $dateC);

but I think it feels a little wrong and calling it this way

$max = Date::max($dateA, $dateB, $dateC);

seems better.

Update

Methods were renamed to Date::earliestOf and Date::latestOf.

[Martin Georgiev (martin-georgiev)]

Wdyt about making this a bit more semantic with a rename to latestOf(Date ...$datesToCompare) and earliestOf(Date ...$datesToCompare)?

[Martin Georgiev (martin-georgiev)]

Suggested change

	public static function min(self $date, self ...$otherDates): self
	public static function min(self $initialCutOffDate, self ...$otherDates): self

So it is clear that the intention here is to use the date in a particular way.

[Jan Jablonski (jan-j)]

Martin Georgiev (@martin-georgiev)

I like the latestOf and earliestOf, happy to rename them like this.

Not sure if the initialCutOffDate isn't a little more confusing though. But I'm not too fussed really.

I was wondering if these methods should allow empty list of dates or not and ruled it out because it would make the return value nullable which is often a pain in the ass to handle on the user side.
Alternative to defining an initialCutOffDate first parameter is to do what you suggested as in latestOf(Date ...$datesToCompare) and then enforcing that $datesToCompare is a non-empty list via PHPStan and/or exception on empty list.

[Ksaveras Sakys (ksaveras)]

Suggested change

	public static function earliestOf(self ...$datesToCompare): self
	public static function earliestOf(self $date, self ...$datesToCompare): self

nit: this will require at least one argument in the fn invocation.

[Jan Jablonski (jan-j)]

Addressed, had it like this before, but changed it thinking I can enforce it with PHPStan, but that seemed impossible.

[Martin Georgiev (martin-georgiev)]

Nice, it reads more intuitive now and code feels self-documented. Upvote from me ;)