new geocodeAsync method

Author: mtmail

README.md

@@ -9,13 +9,8 @@ A [PHP](http://php.net/) library to use the [OpenCage geocoding API](https://ope
 ![Mastodon Follow](https://img.shields.io/mastodon/follow/109287663468501769?domain=https%3A%2F%2Fen.osm.town%2F&style=social)
 
 ## Overview
-This library attempts to use the [CURL](http://www.php.net/manual/en/book.curl.php)
-extension to access the OpenCage Geocoding API. If CURL support is not available, the
-library falls back to using [fopen wrappers](http://uk3.php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen).
-
-To use the library you must either have the CURL extension compiled into your version
-of PHP. Alternatively configure the use of fopen wrappers via the `allow_url_fopen`
-directive in your `php.ini`.
+This library uses [Guzzle](https://docs.guzzlephp.org/en/stable/) to access the
+OpenCage Geocoding API. Both synchronous and asynchronous requests are supported.
 
 ### Authentication
 
@@ -86,6 +81,28 @@ if ($result && $result['total_results'] > 0) {
 }
 ```
 
+### Async geocoding
+
+```php
+$geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
+
+// single async request
+$promise = $geocoder->geocodeAsync('82 Clerkenwell Road, London');
+$result = $promise->wait();
+print_r($result);
+
+// concurrent requests
+$promises = [
+    'london' => $geocoder->geocodeAsync('London'),
+    'paris'  => $geocoder->geocodeAsync('Paris'),
+    'tokyo'  => $geocoder->geocodeAsync('Tokyo'),
+];
+$results = \GuzzleHttp\Promise\Utils::unwrap($promises);
+print $results['london']['results'][0]['formatted'];
+print $results['paris']['results'][0]['formatted'];
+print $results['tokyo']['results'][0]['formatted'];
+```
+
 ### Set a proxy URL
 
 ```php

phpstan.neon

@@ -4,4 +4,3 @@ parameters:
         - src
         - tests
         - demo
-    reportUnmatchedIgnoredErrors: false

src/Geocoder.php

@@ -4,6 +4,7 @@
 
 use GuzzleHttp\Client;
 use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Promise\PromiseInterface;
 
 class Geocoder
 {
@@ -70,6 +71,43 @@ public function setHost(string $host): void
      * @return array{status: array{code: int, message: string}, results: list<mixed>, total_results: int, ...}
      */
     public function geocode(string $query, array $optParams = []): array
+    {
+        $url = $this->buildUrl($query, $optParams);
+
+        $ret = json_decode($this->getJSON($url), true);
+        if (!is_array($ret)) {
+            throw new \Exception('Failed to decode API response');
+        }
+        /** @var array{status: array{code: int, message: string}, results: list<mixed>, total_results: int, ...} */
+        return $ret;
+    }
+
+    /** @param array<string, string> $optParams */
+    public function geocodeAsync(string $query, array $optParams = []): PromiseInterface
+    {
+        $url = $this->buildUrl($query, $optParams);
+
+        if ($this->client === null) {
+            $this->client = $this->buildClient();
+        }
+
+        return $this->client->getAsync($url, ['http_errors' => false])
+            ->then(function (\Psr\Http\Message\ResponseInterface $response) {
+                $ret = json_decode((string) $response->getBody(), true);
+                if (!is_array($ret)) {
+                    throw new \Exception('Failed to decode API response');
+                }
+                return $ret;
+            }, function (\Throwable $e) {
+                if ($e instanceof ConnectException) {
+                    return json_decode($this->generateErrorJSON(498, 'network issue ' . $e->getMessage()), true);
+                }
+                throw $e;
+            });
+    }
+
+    /** @param array<string, string> $optParams */
+    protected function buildUrl(string $query, array $optParams = []): string
     {
         $url = $this->url . 'q=' . urlencode($query);
 
@@ -84,12 +122,7 @@ public function geocode(string $query, array $optParams = []): array
         }
         $url .= '&key=' . urlencode($this->key);
 
-        $ret = json_decode($this->getJSON($url), true);
-        if (!is_array($ret)) {
-            throw new \Exception('Failed to decode API response');
-        }
-        /** @var array{status: array{code: int, message: string}, results: list<mixed>, total_results: int, ...} */
-        return $ret;
+        return $url;
     }
 
     protected function isValidHost(string $host): bool

tests/GeocoderTest.php

@@ -75,6 +75,31 @@ public function testLondon(): void
         $this->assertEquals('OK', $result['status']['message']);
     }
 
+    public function testAsyncLondon(): void
+    {
+        // https://opencagedata.com/api#testingkeys
+        $geocoder = new Geocoder('6d0e711d72d74daeb2b0bfd2a5cdfdba');
+        $promise = $geocoder->geocodeAsync("82 Clerkenwell Road, London");
+        /** @var array{status: array{code: int, message: string}} $result */
+        $result = $promise->wait();
+
+        $this->assertEquals(200, $result['status']['code']);
+        $this->assertEquals('OK', $result['status']['message']);
+    }
+
+    public function testAsyncNetworkError(): void
+    {
+        // https://opencagedata.com/api#testingkeys
+        $geocoder = new Geocoder('6d0e711d72d74daeb2b0bfd2a5cdfdba');
+        $geocoder->setHost('doesnotexist.opencagedata.com');
+        $promise = $geocoder->geocodeAsync('London');
+        /** @var array{status: array{code: int, message: string}} $result */
+        $result = $promise->wait();
+
+        $this->assertEquals(498, $result['status']['code']);
+        $this->assertStringContainsString('network issue', $result['status']['message']);
+    }
+
     public function testProxy(): void
     {
         $proxy = getenv('PROXY');