Add PSR-20 Clock Support

yankewei · yankewei · commit 302087a25728 · 2025-10-24T09:57:52.000+08:00
diff --git a/composer.json b/composer.json
@@ -23,6 +23,7 @@
         "guzzlehttp/guzzle": "^7.6",
         "guzzlehttp/promises": "^1.5 || ^2.0",
         "guzzlehttp/psr7": "^2.0",
+        "psr/clock": "^1.0",
         "psr/http-factory": "^1.0",
         "psr/http-message": "^1.1 || ^2.0"
     },
diff --git a/src/Helpers/SystemClock.php b/src/Helpers/SystemClock.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Saloon\Helpers;
+
+use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
+
+class SystemClock implements ClockInterface
+{
+    public function now(): DateTimeImmutable
+    {
+        return new DateTimeImmutable();
+    }
+}
diff --git a/src/Http/Auth/AccessTokenAuthenticator.php b/src/Http/Auth/AccessTokenAuthenticator.php
@@ -5,6 +5,8 @@
 namespace Saloon\Http\Auth;
 
 use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
+use Saloon\Helpers\SystemClock;
 use Saloon\Http\PendingRequest;
 use Saloon\Contracts\OAuthAuthenticator;
 
@@ -17,6 +19,7 @@ public function __construct(
         public readonly string             $accessToken,
         public readonly ?string            $refreshToken = null,
         public readonly ?DateTimeImmutable $expiresAt = null,
+        private readonly ?ClockInterface $clock = null,
     ) {
         //
     }
@@ -38,7 +41,7 @@ public function hasExpired(): bool
             return false;
         }
 
-        return $this->expiresAt->getTimestamp() <= (new DateTimeImmutable)->getTimestamp();
+        return $this->expiresAt->getTimestamp() <= ($this->clock ?? new SystemClock())->now()->getTimestamp();
     }
 
     /**
diff --git a/src/Http/BaseResource.php b/src/Http/BaseResource.php
@@ -9,7 +9,7 @@ class BaseResource
     /**
      * Constructor
      */
-    public function __construct(readonly protected Connector $connector)
+    public function __construct(protected readonly Connector $connector)
     {
         //
     }
diff --git a/src/Traits/OAuth2/AuthorizationCodeGrant.php b/src/Traits/OAuth2/AuthorizationCodeGrant.php
@@ -25,6 +25,7 @@
 trait AuthorizationCodeGrant
 {
     use HasOAuthConfig;
+    use HasClock;
 
     /**
      * The state generated by the getAuthorizationUrl method.
@@ -158,7 +159,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response, ?str
         $expiresAt = null;
 
         if (isset($responseData->expires_in) && is_numeric($responseData->expires_in)) {
-            $expiresAt = (new DateTimeImmutable)->add(
+            $expiresAt = $this->getClock()->now()->add(
                 DateInterval::createFromDateString((int)$responseData->expires_in . ' seconds')
             );
         }
@@ -171,7 +172,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response, ?str
      */
     protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator
     {
-        return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt);
+        return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt, $this->getClock());
     }
 
     /**
diff --git a/src/Traits/OAuth2/ClientCredentialsGrant.php b/src/Traits/OAuth2/ClientCredentialsGrant.php
@@ -19,6 +19,7 @@
 trait ClientCredentialsGrant
 {
     use HasOAuthConfig;
+    use HasClock;
 
     /**
      * Get the access token
@@ -62,7 +63,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response): OAu
         $expiresAt = null;
 
         if (isset($responseData->expires_in) && is_numeric($responseData->expires_in)) {
-            $expiresAt = (new DateTimeImmutable)->add(
+            $expiresAt = $this->getClock()->now()->add(
                 DateInterval::createFromDateString((int)$responseData->expires_in . ' seconds')
             );
         }
@@ -75,7 +76,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response): OAu
      */
     protected function createOAuthAuthenticator(string $accessToken, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator
     {
-        return new AccessTokenAuthenticator($accessToken, null, $expiresAt);
+        return new AccessTokenAuthenticator($accessToken, null, $expiresAt, $this->getClock());
     }
 
     /**
diff --git a/src/Traits/OAuth2/HasClock.php b/src/Traits/OAuth2/HasClock.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Saloon\Traits\OAuth2;
+
+use Psr\Clock\ClockInterface;
+use Saloon\Helpers\SystemClock;
+
+/**
+ * @phpstan-ignore trait.unused
+ */
+trait HasClock
+{
+    protected ?ClockInterface $clock = null;
+
+    protected function getClock(): ClockInterface
+    {
+        return $this->clock ??= new SystemClock();
+    }
+}
diff --git a/tests/Feature/Oauth2/AuthCodeFlowConnectorTest.php b/tests/Feature/Oauth2/AuthCodeFlowConnectorTest.php
@@ -4,9 +4,9 @@
 
 use Saloon\Http\Request;
 use Saloon\Http\Response;
-use Saloon\Tests\Helpers\Date;
 use Saloon\Http\Faking\MockClient;
 use Saloon\Http\Faking\MockResponse;
+use Saloon\Tests\Helpers\FrozenClock;
 use Saloon\Http\OAuth2\GetUserRequest;
 use Saloon\Exceptions\InvalidStateException;
 use Saloon\Http\OAuth2\GetAccessTokenRequest;
@@ -97,7 +97,8 @@
         MockResponse::make(['access_token' => 'access', 'refresh_token' => 'refresh', 'expires_in' => 3600], 200),
     ]);
 
-    $connector = new OAuth2Connector;
+    $frozenClock = FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    $connector = new OAuth2Connector($frozenClock);
 
     $connector->withMockClient($mockClient);
 
@@ -107,6 +108,7 @@
     expect($authenticator->getAccessToken())->toEqual('access');
     expect($authenticator->getRefreshToken())->toEqual('refresh');
     expect($authenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($authenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
 });
 
 test('you can tap into the access token request and modify it', function () {
@@ -151,7 +153,7 @@
     $connector = new OAuth2Connector;
 
     $state = 'secret';
-    $url = $connector->getAuthorizationUrl(['scope-1', 'scope-2'], $state);
+    $connector->getAuthorizationUrl(['scope-1', 'scope-2'], $state);
 
     $connector->getAccessToken('code', 'invalid', $state);
 })->throws(InvalidStateException::class, 'Invalid state.');
@@ -161,18 +163,20 @@
         MockResponse::make(['access_token' => 'access-new', 'refresh_token' => 'refresh-new', 'expires_in' => 3600]),
     ]);
 
-    $connector = new OAuth2Connector;
+    $frozenClock = FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    $connector = new OAuth2Connector($frozenClock);
 
     $connector->withMockClient($mockClient);
 
-    $authenticator = new AccessTokenAuthenticator('access', 'refresh', Date::now()->addSeconds(3600)->toDateTime());
+    $authenticator = new AccessTokenAuthenticator('access', 'refresh', $frozenClock->addSeconds(3600), $frozenClock);
 
     $newAuthenticator = $connector->refreshAccessToken($authenticator);
 
     expect($newAuthenticator)->toBeInstanceOf(AccessTokenAuthenticator::class);
     expect($newAuthenticator->getAccessToken())->toEqual('access-new');
     expect($newAuthenticator->getRefreshToken())->toEqual('refresh-new');
     expect($newAuthenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($newAuthenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
 });
 
 test('you can tap into the refresh token request', function () {
@@ -184,7 +188,7 @@
 
     $connector->withMockClient($mockClient);
 
-    $authenticator = new AccessTokenAuthenticator('access', 'refresh', Date::now()->addSeconds(3600)->toDateTime());
+    $authenticator = new AccessTokenAuthenticator('access', 'refresh', FrozenClock::fromString('2024-01-01T12:00:00+00:00')->addSeconds(3600));
 
     $newAuthenticator = $connector->refreshAccessToken($authenticator, requestModifier: function (Request $request) {
         $request->query()->add('yee', 'haw');
@@ -209,7 +213,7 @@
 
     $connector->withMockClient($mockClient);
 
-    $authenticator = new AccessTokenAuthenticator('access', null, Date::now()->addSeconds(3600)->toDateTime());
+    $authenticator = new AccessTokenAuthenticator('access', null, FrozenClock::fromString('2024-01-01T12:00:00+00:00')->addSeconds(3600));
 
     $this->expectException(InvalidArgumentException::class);
     $this->expectExceptionMessage('The provided OAuthAuthenticator does not contain a refresh token.');
@@ -226,7 +230,7 @@
 
     $connector->withMockClient($mockClient);
 
-    $authenticator = new AccessTokenAuthenticator('access', 'refresh', Date::now()->addSeconds(3600)->toDateTime());
+    $authenticator = new AccessTokenAuthenticator('access', 'refresh', FrozenClock::fromString('2024-01-01T12:00:00+00:00')->addSeconds(3600));
 
     $response = $connector->refreshAccessToken($authenticator, true);
 
@@ -242,7 +246,7 @@
     $connector = new OAuth2Connector;
     $connector->withMockClient($mockClient);
 
-    $accessToken = new AccessTokenAuthenticator('access', 'refresh', Date::now()->addSeconds(3600)->toDateTime());
+    $accessToken = new AccessTokenAuthenticator('access', 'refresh', FrozenClock::fromString('2024-01-01T12:00:00+00:00')->addSeconds(3600));
 
     $response = $connector->getUser($accessToken);
 
@@ -265,7 +269,7 @@
     $connector = new OAuth2Connector;
     $connector->withMockClient($mockClient);
 
-    $accessToken = new AccessTokenAuthenticator('access', 'refresh', Date::now()->addSeconds(3600)->toDateTime());
+    $accessToken = new AccessTokenAuthenticator('access', 'refresh', FrozenClock::fromString('2024-01-01T12:00:00+00:00')->addSeconds(3600));
 
     $response = $connector->getUser($accessToken, function (Request $request) {
         $request->query()->add('yee', 'haw');
@@ -305,7 +309,8 @@
         GetUserRequest::class => MockResponse::make(['user' => 'Sam']),
     ]);
 
-    $connector = new OAuth2Connector;
+    $frozenClock = FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    $connector = new OAuth2Connector($frozenClock);
     $requests = [];
 
     $connector->oauthConfig()->setRequestModifier(function (Request $request) use (&$requests) {
@@ -326,6 +331,7 @@
     expect($authenticator->getAccessToken())->toEqual('access');
     expect($authenticator->getRefreshToken())->toEqual('refresh');
     expect($authenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($authenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
     expect($mockClient->getLastPendingRequest()->query()->all())->toEqual(['request' => 'access']);
 
     $newAuthenticator = $connector->refreshAccessToken($authenticator);
@@ -334,6 +340,7 @@
     expect($newAuthenticator->getAccessToken())->toEqual('access-new');
     expect($newAuthenticator->getRefreshToken())->toEqual('refresh-new');
     expect($newAuthenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($authenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
     expect($mockClient->getLastPendingRequest()->query()->all())->toEqual(['request' => 'refresh']);
 
     $response = $connector->getUser($newAuthenticator);
diff --git a/tests/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php b/tests/Feature/Oauth2/ClientCredentialsFlowConnectorTest.php
@@ -6,6 +6,7 @@
 use Saloon\Http\Response;
 use Saloon\Http\Faking\MockClient;
 use Saloon\Http\Faking\MockResponse;
+use Saloon\Tests\Helpers\FrozenClock;
 use Saloon\Http\Auth\AccessTokenAuthenticator;
 use Saloon\Exceptions\OAuthConfigValidationException;
 use Saloon\Tests\Fixtures\Connectors\ClientCredentialsConnector;
@@ -19,7 +20,9 @@
         MockResponse::make(['access_token' => 'access', 'expires_in' => 3600], 200),
     ]);
 
-    $connector = new ClientCredentialsConnector;
+
+    $frozenClock = FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    $connector = new ClientCredentialsConnector($frozenClock);
     $connector->withMockClient($mockClient);
 
     $authenticator = $connector->getAccessToken();
@@ -29,6 +32,7 @@
     expect($authenticator->getRefreshToken())->toBeNull();
     expect($authenticator->isRefreshable())->toBeFalse();
     expect($authenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($authenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
 
     $mockClient->assertSentCount(1);
 
@@ -203,7 +207,8 @@
         MockResponse::make(['access_token' => 'access', 'expires_in' => 3600], 200),
     ]);
 
-    $connector = new ClientCredentialsBasicAuthConnector;
+    $frozenClock = FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    $connector = new ClientCredentialsBasicAuthConnector($frozenClock);
     $connector->withMockClient($mockClient);
 
     $authenticator = $connector->getAccessToken();
@@ -213,6 +218,7 @@
     expect($authenticator->getRefreshToken())->toBeNull();
     expect($authenticator->isRefreshable())->toBeFalse();
     expect($authenticator->getExpiresAt())->toBeInstanceOf(DateTimeImmutable::class);
+    expect($authenticator->getExpiresAt()->getTimestamp() - $frozenClock->now()->getTimestamp())->toEqual(3600);
 
     $mockClient->assertSentCount(1);
 
diff --git a/tests/Fixtures/Authenticators/CustomOAuthAuthenticator.php b/tests/Fixtures/Authenticators/CustomOAuthAuthenticator.php
@@ -13,10 +13,10 @@ class CustomOAuthAuthenticator extends AccessTokenAuthenticator
      * Constructor
      */
     public function __construct(
-        readonly public string             $accessToken,
-        readonly public string             $greeting,
-        readonly public ?string            $refreshToken = null,
-        readonly public ?DateTimeImmutable $expiresAt = null,
+        public readonly string             $accessToken,
+        public readonly string             $greeting,
+        public readonly ?string            $refreshToken = null,
+        public readonly ?DateTimeImmutable $expiresAt = null,
     ) {
         //
     }
diff --git a/tests/Fixtures/Connectors/ClientCredentialsBasicAuthConnector.php b/tests/Fixtures/Connectors/ClientCredentialsBasicAuthConnector.php
@@ -5,13 +5,20 @@
 namespace Saloon\Tests\Fixtures\Connectors;
 
 use Saloon\Http\Connector;
+use Psr\Clock\ClockInterface;
+use Saloon\Tests\Helpers\FrozenClock;
 use Saloon\Helpers\OAuth2\OAuthConfig;
 use Saloon\Traits\OAuth2\ClientCredentialsBasicAuthGrant;
 
 class ClientCredentialsBasicAuthConnector extends Connector
 {
     use ClientCredentialsBasicAuthGrant;
 
+    public function __construct(?ClockInterface $clock = null)
+    {
+        $this->clock = $clock ?? FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    }
+
     /**
      * Define the base URL.
      */
diff --git a/tests/Fixtures/Connectors/ClientCredentialsConnector.php b/tests/Fixtures/Connectors/ClientCredentialsConnector.php
@@ -5,13 +5,20 @@
 namespace Saloon\Tests\Fixtures\Connectors;
 
 use Saloon\Http\Connector;
+use Psr\Clock\ClockInterface;
+use Saloon\Tests\Helpers\FrozenClock;
 use Saloon\Helpers\OAuth2\OAuthConfig;
 use Saloon\Traits\OAuth2\ClientCredentialsGrant;
 
 class ClientCredentialsConnector extends Connector
 {
     use ClientCredentialsGrant;
 
+    public function __construct(?ClockInterface $clock = null)
+    {
+        $this->clock = $clock ?? FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    }
+
     /**
      * Define the base URL.
      */
diff --git a/tests/Fixtures/Connectors/OAuth2Connector.php b/tests/Fixtures/Connectors/OAuth2Connector.php
@@ -5,13 +5,20 @@
 namespace Saloon\Tests\Fixtures\Connectors;
 
 use Saloon\Http\Connector;
+use Psr\Clock\ClockInterface;
+use Saloon\Tests\Helpers\FrozenClock;
 use Saloon\Helpers\OAuth2\OAuthConfig;
 use Saloon\Traits\OAuth2\AuthorizationCodeGrant;
 
 class OAuth2Connector extends Connector
 {
     use AuthorizationCodeGrant;
 
+    public function __construct(?ClockInterface $clock = null)
+    {
+        $this->clock = $clock ?? FrozenClock::fromString('2024-01-01T12:00:00+00:00');
+    }
+
     /**
      * Define the base URL.
      */
diff --git a/tests/Fixtures/Requests/QueryParameterRequest.php b/tests/Fixtures/Requests/QueryParameterRequest.php
@@ -25,7 +25,7 @@ class QueryParameterRequest extends Request
     /**
      * Constructor
      */
-    public function __construct(readonly public string $endpoint = '/user')
+    public function __construct(public readonly string $endpoint = '/user')
     {
         //
     }
diff --git a/tests/Helpers/Date.php b/tests/Helpers/Date.php
diff --git a/tests/Helpers/FrozenClock.php b/tests/Helpers/FrozenClock.php
diff --git a/tests/Unit/Oauth2/AccessTokenAuthenticatorTest.php b/tests/Unit/Oauth2/AccessTokenAuthenticatorTest.php
diff --git a/tests/Unit/Oauth2/AuthCodeFlowConnectorTest.php b/tests/Unit/Oauth2/AuthCodeFlowConnectorTest.php

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ class BaseResource`
`9`	`9`	`/**`
`10`	`10`	`* Constructor`
`11`	`11`	`*/`
`12`		`- public function __construct(readonly protected Connector $connector)`
	`12`	`+ public function __construct(protected readonly Connector $connector)`
`13`	`13`	`{`
`14`	`14`	`//`
`15`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,7 @@`
`25`	`25`	`trait AuthorizationCodeGrant`
`26`	`26`	`{`
`27`	`27`	`use HasOAuthConfig;`
	`28`	`+ use HasClock;`
`28`	`29`
`29`	`30`	`/**`
`30`	`31`	`* The state generated by the getAuthorizationUrl method.`
`@@ -158,7 +159,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response, ?str`
`158`	`159`	`$expiresAt = null;`
`159`	`160`
`160`	`161`	`if (isset($responseData->expires_in) && is_numeric($responseData->expires_in)) {`
`161`		`- $expiresAt = (new DateTimeImmutable)->add(`
	`162`	`+ $expiresAt = $this->getClock()->now()->add(`
`162`	`163`	`DateInterval::createFromDateString((int)$responseData->expires_in . ' seconds')`
`163`	`164`	`);`
`164`	`165`	`}`
`@@ -171,7 +172,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response, ?str`
`171`	`172`	`*/`
`172`	`173`	`protected function createOAuthAuthenticator(string $accessToken, ?string $refreshToken = null, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator`
`173`	`174`	`{`
`174`		`- return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt);`
	`175`	`+ return new AccessTokenAuthenticator($accessToken, $refreshToken, $expiresAt, $this->getClock());`
`175`	`176`	`}`
`176`	`177`
`177`	`178`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`trait ClientCredentialsGrant`
`20`	`20`	`{`
`21`	`21`	`use HasOAuthConfig;`
	`22`	`+ use HasClock;`
`22`	`23`
`23`	`24`	`/**`
`24`	`25`	`* Get the access token`
`@@ -62,7 +63,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response): OAu`
`62`	`63`	`$expiresAt = null;`
`63`	`64`
`64`	`65`	`if (isset($responseData->expires_in) && is_numeric($responseData->expires_in)) {`
`65`		`- $expiresAt = (new DateTimeImmutable)->add(`
	`66`	`+ $expiresAt = $this->getClock()->now()->add(`
`66`	`67`	`DateInterval::createFromDateString((int)$responseData->expires_in . ' seconds')`
`67`	`68`	`);`
`68`	`69`	`}`
`@@ -75,7 +76,7 @@ protected function createOAuthAuthenticatorFromResponse(Response $response): OAu`
`75`	`76`	`*/`
`76`	`77`	`protected function createOAuthAuthenticator(string $accessToken, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticator`
`77`	`78`	`{`
`78`		`- return new AccessTokenAuthenticator($accessToken, null, $expiresAt);`
	`79`	`+ return new AccessTokenAuthenticator($accessToken, null, $expiresAt, $this->getClock());`
`79`	`80`	`}`
`80`	`81`
`81`	`82`	`/**`