Merge branch 'master' into PHP-8-0

# Conflicts:
#	tests/integration/DeepLApiTest.php

Author: sathielemann

README.md

@@ -99,12 +99,21 @@ foreach ($targetLanguagesArray as $targetLanguage) {
 }
 ```
 ### Monitoring usage
-You can now check ow much you translate, as well as the limit:
+You can now check how much you translate, as well as the limit:
 ```php
 $usageArray = $deepl->usage();
 
 echo 'You have used '.$usageArray['character_count'].' of '.$usageArray['character_limit'].' in the current billing period.'.PHP_EOL;
 
+```
+
+### Configuring cURL requests
+If you need to use a proxy, you can configure the underlying curl client to use one. You can also specify a timeout to avoid waiting for several minutes if Deepl is unreachable
+```php
+$deepl->setTimeout(10); //give up after 10 seconds
+$deepl->setProxy('http://corporate-proxy.com:3128');
+$deepl->setProxyCredentials('username:password');
+
 ```
 ## Testing
 

src/DeepL.php

@@ -56,6 +56,27 @@ class DeepL
      */
     protected $host;
 
+    /**
+     * URL of the proxy used to connect to DeepL (if needed)
+     *
+     * @var string|null
+     */
+    protected $proxy = null;
+
+    /**
+     * Credentials for the proxy used to connect to DeepL (username:password)
+     *
+     * @var string|null
+     */
+    protected $proxyCredentials = null;
+
+    /**
+     * Maximum number of seconds the query should take
+     *
+     * @var int|null
+     */
+    protected $timeout = null;
+
     /**
      * DeepL constructor
      *
@@ -100,6 +121,37 @@ public function languages($type = null)
         return $languages;
     }
 
+    /**
+     * Set a proxy to use for querying the DeepL API if needed
+     *
+     * @param string $proxy Proxy URL (e.g 'http://proxy-domain.com:3128')
+     */
+    public function setProxy($proxy)
+    {
+
+        $this->proxy = $proxy;
+    }
+
+    /**
+     * Set the proxy credentials
+     *
+     * @param string $proxyCredentials proxy credentials (using 'username:password' format)
+     */
+    public function setProxyCredentials($proxyCredentials)
+    {
+        $this->proxyCredentials = $proxyCredentials;
+    }
+
+    /**
+     * Set a timeout for queries to the DeepL API
+     *
+     * @param int $timeout Timeout in seconds
+     */
+    public function setTimeout($timeout)
+    {
+        $this->timeout = $timeout;
+    }
+
     /**
      * Translate the text string or array from source to destination language
      * For detailed info on Parameters see README.md
@@ -248,10 +300,22 @@ protected function request($url, $body = '')
         curl_setopt($this->curl, CURLOPT_POSTFIELDS, $body);
         curl_setopt($this->curl, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded'));
 
+        if ($this->proxy !== null) {
+            curl_setopt($this->curl, CURLOPT_PROXY, $this->proxy);
+        }
+
+        if ($this->proxyCredentials !== null) {
+            curl_setopt($this->curl, CURLOPT_PROXYAUTH, $this->proxyCredentials);
+        }
+
+        if ($this->timeout !== null) {
+            curl_setopt($this->curl, CURLOPT_TIMEOUT, $this->timeout);
+        }
+
         $response = curl_exec($this->curl);
 
         if (curl_errno($this->curl)) {
-            throw new DeepLException('There was a cURL Request Error.');
+            throw new DeepLException('There was a cURL Request Error : ' . curl_error($this->curl));
         }
         $httpCode      = curl_getinfo($this->curl, CURLINFO_HTTP_CODE);
         $responseArray = json_decode($response, true);

tests/integration/DeepLApiTest.php

@@ -21,6 +21,18 @@ class DeepLApiTest extends TestCase
      */
     protected static $authKey = false;
 
+    /**
+     * Proxy URL
+     * @var bool|string
+     */
+    private static $proxy;
+
+    /**
+     * Proxy Credentials
+     * @var bool|string
+     */
+    private static $proxyCredentials;
+
     /**
      * Setup DeepL Auth Key.
      */
@@ -29,12 +41,16 @@ public static function setUpBeforeClass(): void
         parent::setUpBeforeClass();
 
         $authKey = getenv('DEEPL_AUTH_KEY');
+        $proxy = getenv('HTTP_PROXY');
+        $proxyCredentials = getenv('HTTP_PROXY_CREDENTIALS');
 
         if ($authKey === false) {
             return;
         }
 
         self::$authKey = $authKey;
+        self::$proxy = $proxy;
+        self::$proxyCredentials = $proxyCredentials;
     }
 
     /**
@@ -276,6 +292,49 @@ public function testTranslateWithAllParams()
         self::assertEquals($expectedText, $translatedText[0]['text']);
     }
 
+    /**
+     * Test translate() with all Params
+     */
+    public function testWithProxy()
+    {
+        if (self::$authKey === false) {
+            $this->markTestSkipped('DeepL Auth Key (DEEPL_AUTH_KEY) is not configured.');
+        }
+
+        if (self::$proxy === false) {
+            // The test would succeed with $proxy === false but it wouln't mean anything.
+            $this->markTestSkipped('Proxy is not configured.');
+        }
+
+        $deepl = new DeepL(self::$authKey);
+        $deepl->setProxy(self::$proxy);
+        $deepl->setProxyCredentials(self::$proxyCredentials);
+
+        $englishText  = 'please translate this text';
+        $expectedText = 'Bitte übersetzen Sie diesen Text';
+
+        $translatedText = $deepl->translate($englishText, 'en', 'de');
+
+        $this->assertEquals($expectedText, $translatedText[0]['text']);
+    }
+
+    /**
+     * Test translate() with all Params
+     */
+    public function testCustomTimeout()
+    {
+        $deepl = new DeepL(self::$authKey, 2, '10.255.255.1'); // non routable IP, should timeout.
+        $deepl->setTimeout(2);
+
+        $start = time();
+        try {
+            $deepl->translate('some text');
+        } catch (\Exception $e) {
+            $time = time() - $start;
+            $this->assertLessThan(4, $time);
+        }
+    }
+
     /**
      * Test translate() $formality
      */