Enhanced Client and Region with support for Terminal Cloud LIVE regional endpoints (#724)

DjoykeAbyah · web-flow · commit 6d4d320fe8a1 · 2025-01-07T13:28:25.000+01:00
* added retrieveCloudEndpoint method

* test endpoint testcase added

* unmapped region test added

* updated client, region and regiontest
diff --git a/src/Adyen/Client.php b/src/Adyen/Client.php
@@ -173,6 +173,39 @@ public function setEnvironment(string $environment, ?string $liveEndpointUrlPref
             $msg = "This environment does not exist, use " . Environment::TEST . ' or ' . Environment::LIVE;
             throw new AdyenException($msg);
         }
+
+        // Retrieve and set the Terminal API Cloud Endpoint
+        $endpoint = $this->retrieveCloudEndpoint($this->config->get('terminalApiRegion'), $environment);
+        $this->config->set('terminalApiCloudEndpoint', $endpoint);
+    }
+
+    /**
+     * Retrieve the cloud endpoint for a given region and environment.
+     *
+     * @param string|null $region The region for which the endpoint is requested. Defaults to the EU endpoint if null or unsupported.
+     * @param string $environment The environment, either 'test' or 'live'.
+     * @return string The endpoint URL.
+     * @throws AdyenException
+     */
+    public function retrieveCloudEndpoint(?string $region, string $environment): string
+    {
+        // Check if the environment is TEST
+        if ($environment === Environment::TEST) {
+            return self::ENDPOINT_TERMINAL_CLOUD_TEST;
+        }
+
+        // Check if the environment is LIVE
+        if ($environment === Environment::LIVE) {
+            if ($environment === Environment::LIVE) {
+                $region = $region ?? Region::EU;
+                if (!array_key_exists($region, Region::TERMINAL_API_ENDPOINTS_MAPPING)) {
+                    throw new AdyenException("TerminalAPI endpoint for $region is not supported yet");
+                }
+                return Region::TERMINAL_API_ENDPOINTS_MAPPING[$region];
+            }
+        }
+        // Default to TEST endpoint if no valid environment is specified
+        return self::ENDPOINT_TERMINAL_CLOUD_TEST;
     }
 
     /**
@@ -446,18 +479,4 @@ protected function createDefaultHttpClient(): CurlClient
     {
         return new CurlClient();
     }
-
-    /**
-     * @param string $region
-     * @return void
-     * @throws AdyenException
-     */
-    public function setRegion(string $region): void
-    {
-        if (!in_array($region, Region::VALID_REGIONS)) {
-            throw new AdyenException('Trying to set an invalid region!');
-        }
-
-        $this->config->set('region', $region);
-    }
 }
diff --git a/src/Adyen/Region.php b/src/Adyen/Region.php
@@ -10,15 +10,15 @@ class Region
     const EU = "eu";
     
     /**
-     * United States region
+     * Australia region
      */
-    const US = "us";
+    const AU = "au";
 
     /**
-     * Australia region
+     * United States region
      */
-    const AU = "au";
-    
+    const US = "us";
+
     /**
      * India region
      */
@@ -29,26 +29,14 @@ class Region
      */
     const APSE = "apse";
 
-   /**
-     * List of all valid regions
-     * @var array<int,string>
-     */
-    const VALID_REGIONS = [
-        self::EU,
-        self::US,
-        self::AU,
-        self::IN,
-        self::APSE
-    ];
-
     /**
      * Maps regions to their respective Terminal API endpoints.
      * @var array<string, string>
      */
     const TERMINAL_API_ENDPOINTS_MAPPING = [
         self::EU => Client::ENDPOINT_TERMINAL_CLOUD_LIVE,
-        self::US => Client::ENDPOINT_TERMINAL_CLOUD_US_LIVE,
         self::AU => Client::ENDPOINT_TERMINAL_CLOUD_AU_LIVE,
+        self::US => Client::ENDPOINT_TERMINAL_CLOUD_US_LIVE,
         self::APSE => Client::ENDPOINT_TERMINAL_CLOUD_APSE_LIVE,
     ];
 }
diff --git a/tests/TestCase.php b/tests/TestCase.php
@@ -25,6 +25,8 @@
 
 use Adyen\AdyenException;
 use Adyen\Client;
+use Adyen\Region;
+use Adyen\Config;
 use Adyen\Environment;
 
 class TestCase extends \PHPUnit\Framework\TestCase
@@ -326,4 +328,103 @@ protected function getTestFilePath()
     {
         return __DIR__ . DIRECTORY_SEPARATOR . 'config' . DIRECTORY_SEPARATOR . 'test.ini';
     }
+
+    /**
+     * Data provider for cloud test endpoint test cases.
+     *
+     * @return array[]
+     */
+    public function provideCloudTestEndpointTestCases(): array
+    {
+        return [
+            [null, Environment::TEST, "https://terminal-api-test.adyen.com"],
+            [Region::EU, Environment::TEST, "https://terminal-api-test.adyen.com"],
+            [Region::AU, Environment::TEST, "https://terminal-api-test.adyen.com"],
+            [Region::US, Environment::TEST, "https://terminal-api-test.adyen.com"],
+            [Region::APSE, Environment::TEST, "https://terminal-api-test.adyen.com"]
+        ];
+    }
+
+    /**
+     * Test retrieving the correct Terminal API Cloud endpoint for the TEST environment.
+     *
+     * @dataProvider provideCloudTestEndpointTestCases
+     *
+     * @param string|null $region The region for which the endpoint is being retrieved.
+     * @param string $environment The environment being tested (e.g., TEST).
+     * @param string $expectedEndpoint The expected URL for the Terminal API Cloud endpoint.
+     */
+    public function testGetCloudEndpointForTestEnvironment(?string $region, string $environment, string $expectedEndpoint): void
+    {
+        $testConfig = new Config();
+        $testConfig->set("environment", $environment);
+        $testConfig->set("terminalApiRegion", $region);
+
+        $testClient = new Client($testConfig);
+
+        $actualEndpoint = "https://terminal-api-test.adyen.com";
+        $this->assertEquals($expectedEndpoint, $actualEndpoint);
+    }
+
+    /**
+     * Data provider for cloud live endpoint test cases.
+     *
+     * @return array[]
+     */
+    public function provideCloudLiveEndpointTestCases(): array
+    {
+        return [
+            [null, Environment::LIVE, "https://terminal-api-live.adyen.com"],
+            [Region::EU, Environment::LIVE, "https://terminal-api-live.adyen.com"],
+            [Region::AU, Environment::LIVE, "https://terminal-api-live-au.adyen.com"],
+            [Region::US, Environment::LIVE, "https://terminal-api-live-us.adyen.com"],
+            [Region::APSE, Environment::LIVE, "https://terminal-api-live-apse.adyen.com"]
+        ];
+    }
+
+    /**
+     * Test retrieving the correct Terminal API Cloud endpoint for the LIVE environment.
+     *
+     * @dataProvider provideCloudLiveEndpointTestCases
+     *
+     * @param string|null $region The region for which the endpoint is being retrieved.
+     * @param string $environment The environment being tested (e.g., LIVE).
+     * @param string $expectedEndpoint The expected URL for the Terminal API Cloud endpoint.
+     */
+    public function testGetCloudEndpointForLiveEnvironment(?string $region, string $environment, string $expectedEndpoint): void
+    {
+        $testConfig = new Config();
+        $testConfig->set("environment", $environment);
+        $testConfig->set("terminalApiRegion", $region);
+
+        $testClient = new Client($testConfig);
+
+        $actualEndpoint = $testClient->retrieveCloudEndpoint($region, $environment);
+        $this->assertEquals($expectedEndpoint, $actualEndpoint);
+    }
+
+    /**
+     * Ensures an exception is thrown for unsupported region India in LIVE environment
+     *
+     * @throws \Adyen\AdyenException
+     */
+    public function testUnmappedIndiaRegionThrowsException(): void
+    {
+        $testConfig = new Config();
+        $testConfig->set("environment", Environment::LIVE);
+        $testConfig->set("terminalApiRegion", Region::IN);
+
+        $testClient = new Client($testConfig);
+
+        try {
+            $region = Region::IN;
+            $environment = Environment::LIVE;
+
+            $testClient->retrieveCloudEndpoint($region, $environment);
+        } catch (AdyenException $e) {
+            $this->assertEquals("TerminalAPI endpoint for in is not supported yet", $e->getMessage());
+            return;
+        }
+        $this->fail("Expected AdyenException was not thrown for unmapped region.");
+    }
 }
diff --git a/tests/Unit/RegionTest.php b/tests/Unit/RegionTest.php
@@ -7,29 +7,61 @@
 
 class RegionTest extends TestCase
 {
-    public function testValidRegions()
+    /**
+     * Retrieves all region constants for comparison.
+     * Filters out non-string values to exclude mappings.
+     *
+     * @return array<string> A list of valid regions.
+     */
+    private function getRegionValues(): array
     {
+        $reflection = new \ReflectionClass(Region::class);
+        $constants = $reflection->getConstants();
+    
+        $enumConstants = array_filter($constants, function ($value) {
+            return is_string($value);
+        });
+
+        return array_values($enumConstants);
+    }
+
+    /**
+     * Tests that the list of valid regions matches the expected list.
+     * Compares the retrieved region constants with the expected list.
+     *
+     * @return void
+     */
+    public function testValidRegions(): void
+    {
+        $allRegions = $this->getRegionValues();
+
         $expected = [
             "eu",
-            "us",
             "au",
+            "us",
             "in",
             "apse",
         ];
 
         $this->assertEquals(
             $expected,
-            Region::VALID_REGIONS,
-            "VALID_REGIONS should match the expected regions."
+            $allRegions,
+            "The list of all regions should match the expected values."
         );
     }
 
-    public function testTerminalApiEndpointsMapping()
+    /**
+     * Tests that the Terminal API endpoints mapping matches the expected values.
+     * Compares the predefined endpoint mappings with the expected mappings.
+     *
+     * @return void
+     */
+    public function testTerminalApiEndpointsMapping(): void
     {
         $expected = [
             "eu" => "https://terminal-api-live.adyen.com",
-            "us" => "https://terminal-api-live-us.adyen.com",
             "au" => "https://terminal-api-live-au.adyen.com",
+            "us" => "https://terminal-api-live-us.adyen.com",
             "apse" => "https://terminal-api-live-apse.adyen.com",
         ];
 
