When comparing based on time, it is desirable to be able to customize the time reference point.

[yankewei]

I believe we need a method to establish a fixed time reference point in the project.

Background

In a project, we typically introduce a time-handling library like Carbon, which offers two benefits:

1. Easy handling or retrieval of time, especially when performing various calculations involving time.
2. It allows setting a fixed time reference point so that retrieving the current time within the project does not change over real-world time. For example, if we set the initial project time to 2000-01-01 00:00:00, then any calls to get the current time via this library will always return 2000-01-01 00:00:00. In production environments, we wouldn’t configure it this way—but for testing purposes, this is extremely useful. For instance, projects may have baselines containing timestamps used in tests to verify whether method outputs match baseline data exactly. With fixed times, method results remain consistent regardless of real-world passage of time.

I encountered this issue while working with OAuth—specifically when testing scenarios where refresh tokens are exchanged for new access tokens. The new access token's expiration (expires_at) should be calculated as the current test execution timestamp plus API-provided expires_in. If system-time were frozen during tests (e.g., using Carbon), expires_at would remain predictable across test runs; however, since our code currently relies on PHP’s native new DateTimeImmutable(), its value changes dynamically with real-world clock progression—making assertions against expected values difficult and unreliable.

Proposal

Two potential solutions come to mind:

1. Adopt an existing third-party datetime library instead of relying solely on PHP’s built-in functionality.
2. Introduce configurable properties such as timeNow, allowing override during computations (falling back only conditionally). This approach facilitates deterministic behavior under controlled conditions without disrupting normal runtime logic elsewhere — similar implementations exist already (thephpleague/oauth2-client).