Add Client::getStoreTime() method, update README

Author: TomA-R

README.md

@@ -12,7 +12,7 @@ https://developer.bigcommerce.com/
 Requirements
 ------------
 
-- PHP 7.1 or greater
+- PHP 8.1 or greater
 - `curl` extension enabled
 
 To generate an OAuth API token, [follow this guide.](https://support.bigcommerce.com/s/article/Store-API-Accounts)
@@ -96,12 +96,12 @@ Connecting to the store
 -----------------------
 
 To test that your configuration was correct and you can successfully connect to
-the store, ping the getTime method which will return a DateTime object
-representing the current timestamp of the store if successful or false if
+the store, ping the getStoreTime method which will return a DateTime object
+representing the current timestamp of the store if successful or null if
 unsuccessful:
 
 ~~~php
-$ping = Bigcommerce::getTime();
+$ping = Bigcommerce::getStoreTime();
 
 if ($ping) echo $ping->format('H:i:s');
 ~~~

src/Bigcommerce/Api/Client.php

@@ -482,15 +482,32 @@ public static function getTime()
     {
         $response = self::connection()->get(self::$api_url . '/time');
 
-        if (empty($response)) {
+        if (empty($response) || !is_numeric($response)) {
             return null;
         }
 
+        // The response from /time is unix time in milliseconds
         $seconds = floor($response / 1000);
         $microseconds = $response % 1000;
         return DateTime::createFromFormat('U.u', sprintf('%d.%03d', $seconds, $microseconds));
     }
 
+    /**
+     * Pings the time endpoint to test the connection to a store.
+     *
+     * @return ?DateTime
+     */
+    public static function getStoreTime()
+    {
+        $response = self::connection()->get(self::$api_path . '/time');
+
+        if (!is_object($response) || !property_exists($response, 'time')) {
+            return null;
+        }
+
+        return new DateTime("@{$response->time}");
+    }
+
     /**
      * Returns the default collection of products.
      *

test/Unit/Api/ClientTest.php

@@ -206,7 +206,6 @@ public function testDeleteResourceDeletesToTheRightPlace()
 
     public function testGetTimeReturnsTheExpectedTime()
     {
-        $now = new \DateTime();
         $this->connection->expects($this->once())
             ->method('get')
             ->with('https://api.bigcommerce.com/time', false)
@@ -215,6 +214,26 @@ public function testGetTimeReturnsTheExpectedTime()
         $this->assertEquals('2024-06-13 13:00:00', Client::getTime()->format('Y-m-d H:i:s'));
     }
 
+    public function testGetStoreTimeReturnsTheExpectedTime()
+    {
+        $this->connection->expects($this->once())
+            ->method('get')
+            ->with($this->basePath . '/time')
+            ->will($this->returnValue(json_decode('{"time": 1718283600}')));
+
+        $this->assertEquals('2024-06-13 13:00:00', Client::getStoreTime()->format('Y-m-d H:i:s'));
+    }
+
+    public function testGetStoreTimeReturnsNothing()
+    {
+        $this->connection->expects($this->once())
+            ->method('get')
+            ->with($this->basePath . '/time')
+            ->will($this->returnValue(false));
+
+        $this->assertEquals(null, Client::getStoreTime());
+    }
+
     public function testGetStoreReturnsTheResultBodyDirectly()
     {
         $body = [random_int(0, mt_getrandmax()) => random_int(0, mt_getrandmax())];