Good news for PHP developers using our geocoding API - version 4.0.0 of opencage/geocode has been released.

The new version of the SDK brings with it some meaningful changes, hence why we bumped to v4.0.0.

Specifically

  • Minimum PHP is now 8.2 (was 8.0).

  • Guzzle replaces the internal cURL/fopen logic. The SDK now depends on guzzlehttp/guzzle ^7.0, which Composer installs automatically. There is no longer a cURL/fopen fallback and no need to fiddle with allow_url_fopen.

  • Dedicated reverse geocoding: new geocodeReverse($latitude, $longitude) method — you no longer have to build a "lat,lng" string yourself.

  • Asynchronous requests: new geocodeAsync() and geocodeReverseAsync() methods return a Guzzle PromiseInterface, allowing concurrent geocoding.

  • Type declarations everywhere. All method parameters and return values are now typed. In particular geocode() always returns an array or throws an \Exception — it no longer returns null/false (see Handling the Response below).

  • Network failures are reported with a synthetic status.code of 498 instead of failing silently; the API key is redacted from the message.

Further Reading

Final Points

As with all of the 40+ SDKs for our geocoding API we welcome your ideas for improvement. We are continually rolling out various fixes and improvements in the future, but code contributions are of course also gladly received.

Our geocoding Agent Skill, which includes a reference file for working with PHP, has been adjusted accordingly.

Happy geocoding (whether in PHP or other languages),

Ed