PSR-20: does it need to avoid any direct call to date, time and date time objects?

[clementvtrd]

Creating a standard way of accessing the clock would allow interoperability during testing, when testing behavior that has timing-based side effects. Common ways to get the current time include calling \time() or new \DateTimeImmutable('now'). However, this makes mocking the current time impossible in some situations.

Ambiguous

What about relative date? For example new \DateTimeImmutable('-1 day') ? For the same reason as for current timestamp, shouldn't it be made through the clock?

Before

- $yesterday = new \DateTimeImmutable('-1 day');
+ $yesterday = $clock->now()->modify('-1 day');

Sources

https://www.php-fig.org/psr/psr-20/

[eexit]

I find the way of bringing the poll a bit odd. The poll is not about the PSR but about the rule: if we decide to enforce the PSR via a rule, then, indeed, all time-related constructs should be reported, as it makes total sense to only use the ClockInterface.

[clementvtrd]

Yes I'm talking about the rule itself that is an interpretation of the PSR-20 specification from the link I shared. It does only mention the current timestamp ('now') but do not explicitly say relative date time should also use a clock, neither for the absolute date. So rather than just over-interpret it by myself I prefer to ask before. Two projects at least would be impacted by such update.

[EVDW]

I agree to forbid the usage of relative date, but not with "Forbid all usage of date time constructor". Because we might need to use a specific date as new DateTimeImmutable('2027-05-15') (not my birthday at all, but don't forget this date). What have to be forbiden is using the constructor to get a date starting from now.

[clementvtrd]

Yes but this could be done via the clock with $clock->now()->modify('2027-05-15') which also accept absolute date. You could also update it with fluent language like $clock->now()->modify('2027-05-15 at midnight'). It might be very hard to forbid all usage except absolute date IMHO. However if everything pass through the clock, relative date would be easily tested as well as absolute date

[eexit]

In B&S, we extended the PSR proposal:

<?php

declare(strict_types=1);

namespace App\Domain\Service;

use App\Domain\Data\ValueObject\Time\Duration;
use Psr;

interface Clock extends Psr\Clock\ClockInterface
{
    /**
     * Delays the program execution for the given number of seconds.
     *
     * @see https://www.php.net/manual/en/function.sleep.php
     *
     * @param int<0, max> $seconds
     */
    public function sleep(int $seconds): void;

    public function wait(Duration $timeout): void;

    /**
     * @param callable(): bool $callable returns TRUE if the end-of-wait condition is reached, FALSE otherwise. If FALSE, the method will wait until the next $interval.
     * @param ?Duration        $interval time to wait between each call to $callable (default: 1 second)
     *
     * @return bool TRUE if the condition has been met, FALSE otherwise and if $timeout has been reached
     */
    public function waitUntil(callable $callable, Duration $timeout, ?Duration $interval = null): bool;

    public function at(string $modifier): \DateTimeImmutable;

    public function time(): int;

    public function microtime(): float;

    public function format(string $format): string;
}

[EVDW]

I find it a bit overkill on this case, as there is no real reason for absolut date. (but you're right about specifying midnight to not get the current time of the DateTime 😅)
It's annoying to have to read $clock->now()->modify just to have a specific date.
But I agree it would be a mess to match only relative date 🥲

[clementvtrd]

Finally @EVDW it is not that hard. See #13 to have an overview of the implementation. Would it suit your use cases?