Replace internal use of fopen and cURL fallback with Guzzle library (#23)

* replace internal use of fopen and cURL fallback with Guzzle library

* merged all code from AbstractGeocoder into Geocoder

* add type declarations to all methods

* cast json_encode return to string since this input can never fail to encode

* getenv can return false, make sure we receive null instead

* check if array is defined before accessing elements

* check that fetched JSON is array with certain required fields

* new geocodeAsync method

* add tests for more error cases

* add tests for network issue, no results, invalid proxy

* new public method geocodeReverse and geocodeReverseAsync

* split tests into multiple files

* user_agent variable can be marked readonly (starting PHP 8.1)

* redact half the API key in error messages

Author: mtmail

.github/workflows/ci.yml

@@ -35,16 +35,13 @@ jobs:
           if [ "${{ matrix.php-version }}" != "8.5" ]; then rm composer.lock; fi
           composer install --no-progress --no-suggest --no-interaction
 
-      - name: Run phpunit tests (with and without cURL)
-        run: |
-          ./vendor/bin/phpunit --display-deprecations
-          SKIP_CURL=1 ./vendor/bin/phpunit --display-deprecations
+      - name: Run phpunit tests
+        run: ./vendor/bin/phpunit --display-deprecations
 
-      - name: Run proxy tests (with and without cURL)
+      - name: Run proxy tests
         run: |
           docker run -d --name=tinyproxy -p 8888:8888 monokal/tinyproxy:latest ANY
           PROXY=http://0.0.0.0:8888 ./vendor/bin/phpunit
-          PROXY=http://0.0.0.0:8888 SKIP_CURL=1 ./vendor/bin/phpunit
           docker rm -f tinyproxy
 
       - name: Run PHPCS (Code Sniffer)

CHANGES.txt

@@ -1,3 +1,11 @@
+unreleased
+=====================================================
+- new method geocodeAsync
+- new methods geocodeReverse, geocodeReverseAsync
+- replace internal use of fopen and cURL fallback with Guzzle library
+- add type declaration to all method parameters and return values
+- many more tests
+
 3.4.0 -- Sat Mar 29 2026
 =====================================================
 - deprecate PHP 8.1

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
 
@@ -64,7 +59,7 @@ print_r($result);
 
 ```php
 $geocoder = new \OpenCage\Geocoder\Geocoder('YOUR-API-KEY');
-$result = $geocoder->geocode('43.831,4.360'); # latitude,longitude (y,x)
+$result = $geocoder->geocodeReverse(43.831, 4.360); # latitude, longitude
 print $result['results'][0]['formatted'];
 // 3 Rue de Rivarol, 30020 Nîmes, France
 ```
@@ -86,6 +81,33 @@ 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'];
+
+// async reverse geocoding
+$promise = $geocoder->geocodeReverseAsync(43.831, 4.360);
+$result = $promise->wait();
+print $result['results'][0]['formatted'];
+```
+
 ### Set a proxy URL
 
 ```php

composer.json

@@ -14,8 +14,14 @@
       "OpenCage\\Geocoder\\": "src"
     }
   },
+  "autoload-dev": {
+    "psr-4": {
+      "OpenCage\\Geocoder\\Test\\": "tests"
+    }
+  },
   "require": {
-    "php": ">=8.2"
+    "php": ">=8.2",
+    "guzzlehttp/guzzle": "^7.0"
   },
   "require-dev": {
     "phpunit/phpunit": "^12.5.8",
@@ -24,13 +30,11 @@
   },
   "scripts": {
     "test": "phpunit --display-deprecations",
-    "test:nocurl": "SKIP_CURL=1 phpunit --display-deprecations",
     "phpcs": "phpcs .",
     "phpstan": "phpstan analyse",
     "check": [
       "composer validate --strict",
       "@test",
-      "@test:nocurl",
       "@phpcs",
       "@phpstan"
     ]