feat: add support for HERE Geocoding & Search API v7 (GS7)

- Implement GS7 geocoding and reverse geocoding endpoints.
- Add createUsingApiKey static factory for easier instantiation.
- Enhance HereAddress model with locationName and helper methods.
- Update documentation and migrate to PHPUnit 10.

BREAKING CHANGE: bump minimum PHP version to 8.2

Author: Giacomo92

Here.php

@@ -32,6 +32,16 @@
  */
 final class Here extends AbstractHttpProvider implements Provider
 {
+    /**
+     * @var string
+     */
+    public const GS7_GEOCODE_ENDPOINT_URL = 'https://geocode.search.hereapi.com/v1/geocode';
+
+    /**
+     * @var string
+     */
+    public const GS7_REVERSE_ENDPOINT_URL = 'https://revgeocode.search.hereapi.com/v1/revgeocode';
+
     /**
      * @var string
      */
@@ -96,43 +106,50 @@ final class Here extends AbstractHttpProvider implements Provider
     ];
 
     /**
-     * @var string
+     * @var string|null
      */
-    private $appId;
+    private ?string $appId;
 
     /**
-     * @var string
+     * @var string|null
      */
-    private $appCode;
+    private ?string $appCode;
 
     /**
      * @var bool
      */
-    private $useCIT;
+    private bool $useCIT;
+
+    /**
+     * @var string|null
+     */
+    private ?string $apiKey = null;
 
     /**
      * @var string
      */
-    private $apiKey;
+    private string $version;
 
     /**
      * @param ClientInterface $client  an HTTP adapter
-     * @param string          $appId   an App ID
-     * @param string          $appCode an App code
+     * @param string|null     $appId   an App ID
+     * @param string|null     $appCode an App code
      * @param bool            $useCIT  use Customer Integration Testing environment (CIT) instead of production
+     * @param string          $version version of the API to use ('6.2' or '7')
      */
-    public function __construct(ClientInterface $client, ?string $appId = null, ?string $appCode = null, bool $useCIT = false)
+    public function __construct(ClientInterface $client, ?string $appId = null, ?string $appCode = null, bool $useCIT = false, string $version = '6.2')
     {
         $this->appId = $appId;
         $this->appCode = $appCode;
         $this->useCIT = $useCIT;
+        $this->version = $version;
 
         parent::__construct($client);
     }
 
-    public static function createUsingApiKey(ClientInterface $client, string $apiKey, bool $useCIT = false): self
+    public static function createUsingApiKey(ClientInterface $client, string $apiKey, bool $useCIT = false, string $version = '7'): self
     {
-        $client = new self($client, null, null, $useCIT);
+        $client = new self($client, null, null, $useCIT, $version);
         $client->apiKey = $apiKey;
 
         return $client;
@@ -145,6 +162,10 @@ public function geocodeQuery(GeocodeQuery $query): Collection
             throw new UnsupportedOperation('The Here provider does not support IP addresses, only street addresses.');
         }
 
+        if ('7' === $this->version && null !== $this->apiKey) {
+            return $this->geocodeQueryGS7($query);
+        }
+
         $queryParams = $this->withApiCredentials([
             'searchtext' => $query->getText(),
             'gen' => 9,
@@ -174,8 +195,44 @@ public function geocodeQuery(GeocodeQuery $query): Collection
         return $this->executeQuery(sprintf('%s?%s', $this->getBaseUrl($query), http_build_query($queryParams)), $query->getLimit());
     }
 
+    private function geocodeQueryGS7(GeocodeQuery $query): Collection
+    {
+        $queryParams = $this->withApiCredentials([
+            'q' => $query->getText(),
+            'limit' => $query->getLimit(),
+        ]);
+
+        $qq = [];
+        if (null !== $country = $query->getData('country')) {
+            $qq[] = 'country='.$country;
+        }
+        if (null !== $state = $query->getData('state')) {
+            $qq[] = 'state='.$state;
+        }
+        if (null !== $county = $query->getData('county')) {
+            $qq[] = 'county='.$county;
+        }
+        if (null !== $city = $query->getData('city')) {
+            $qq[] = 'city='.$city;
+        }
+
+        if (!empty($qq)) {
+            $queryParams['qq'] = implode(';', $qq);
+        }
+
+        if (null !== $query->getLocale()) {
+            $queryParams['lang'] = $query->getLocale();
+        }
+
+        return $this->executeQuery(sprintf('%s?%s', $this->getBaseUrl($query), http_build_query($queryParams)), $query->getLimit());
+    }
+
     public function reverseQuery(ReverseQuery $query): Collection
     {
+        if ('7' === $this->version && null !== $this->apiKey) {
+            return $this->reverseQueryGS7($query);
+        }
+
         $coordinates = $query->getCoordinates();
 
         $queryParams = $this->withApiCredentials([
@@ -188,12 +245,34 @@ public function reverseQuery(ReverseQuery $query): Collection
         return $this->executeQuery(sprintf('%s?%s', $this->getBaseUrl($query), http_build_query($queryParams)), $query->getLimit());
     }
 
+    private function reverseQueryGS7(ReverseQuery $query): Collection
+    {
+        $coordinates = $query->getCoordinates();
+
+        $queryParams = $this->withApiCredentials([
+            'at' => sprintf('%s,%s', $coordinates->getLatitude(), $coordinates->getLongitude()),
+            'limit' => $query->getLimit(),
+        ]);
+
+        if (null !== $query->getLocale()) {
+            $queryParams['lang'] = $query->getLocale();
+        }
+
+        return $this->executeQuery(sprintf('%s?%s', $this->getBaseUrl($query), http_build_query($queryParams)), $query->getLimit());
+    }
+
     private function executeQuery(string $url, int $limit): Collection
     {
         $content = $this->getUrlContents($url);
 
         $json = json_decode($content, true);
 
+        if (isset($json['error'])) {
+            if ('Unauthorized' === $json['error']) {
+                throw new InvalidCredentials('Invalid or missing api key.');
+            }
+        }
+
         if (isset($json['type'])) {
             switch ($json['type']['subtype']) {
                 case 'InvalidInputData':
@@ -205,6 +284,10 @@ private function executeQuery(string $url, int $limit): Collection
             }
         }
 
+        if (isset($json['items'])) {
+            return $this->parseGS7Response($json['items'], $limit);
+        }
+
         if (!isset($json['Response']) || empty($json['Response'])) {
             return new AddressCollection([]);
         }
@@ -215,6 +298,63 @@ private function executeQuery(string $url, int $limit): Collection
 
         $locations = $json['Response']['View'][0]['Result'];
 
+        return $this->parseV6Response($locations, $limit);
+    }
+
+    private function parseGS7Response(array $items, int $limit): Collection
+    {
+        $results = [];
+
+        foreach ($items as $item) {
+            $builder = new AddressBuilder($this->getName());
+
+            $position = $item['position'];
+            $builder->setCoordinates($position['lat'], $position['lng']);
+
+            if (isset($item['mapView'])) {
+                $mapView = $item['mapView'];
+                $builder->setBounds($mapView['south'], $mapView['west'], $mapView['north'], $mapView['east']);
+            }
+
+            $address = $item['address'];
+            $builder->setStreetNumber($address['houseNumber'] ?? null);
+            $builder->setStreetName($address['street'] ?? null);
+            $builder->setPostalCode($address['postalCode'] ?? null);
+            $builder->setLocality($address['city'] ?? null);
+            $builder->setSubLocality($address['district'] ?? null);
+            $builder->setCountryCode($address['countryCode'] ?? null);
+            $builder->setCountry($address['countryName'] ?? null);
+
+            /** @var HereAddress $hereAddress */
+            $hereAddress = $builder->build(HereAddress::class);
+            $hereAddress = $hereAddress->withLocationId($item['id'] ?? null);
+            $hereAddress = $hereAddress->withLocationType($item['resultType'] ?? null);
+            $hereAddress = $hereAddress->withLocationName($item['title'] ?? null);
+
+            $additionalData = [];
+            if (isset($address['countryName'])) {
+                $additionalData[] = ['key' => 'CountryName', 'value' => $address['countryName']];
+            }
+            if (isset($address['state'])) {
+                $additionalData[] = ['key' => 'StateName', 'value' => $address['state']];
+            }
+            if (isset($address['county'])) {
+                $additionalData[] = ['key' => 'CountyName', 'value' => $address['county']];
+            }
+
+            $hereAddress = $hereAddress->withAdditionalData($additionalData);
+            $results[] = $hereAddress;
+
+            if (count($results) >= $limit) {
+                break;
+            }
+        }
+
+        return new AddressCollection($results);
+    }
+
+    private function parseV6Response(array $locations, int $limit): Collection
+    {
         $results = [];
 
         foreach ($locations as $loc) {
@@ -245,7 +385,7 @@ private function executeQuery(string $url, int $limit): Collection
             $address = $builder->build(HereAddress::class);
             $address = $address->withLocationId($location['LocationId'] ?? null);
             $address = $address->withLocationType($location['LocationType']);
-            $address = $address->withAdditionalData(array_merge($additionalData, $extraAdditionalData));
+            $address = $address->withAdditionalData(array_merge($additionalData ?? [], $extraAdditionalData));
             $address = $address->withShape($location['Shape'] ?? null);
             $results[] = $address;
 
@@ -289,18 +429,13 @@ private function getAdditionalDataParam(GeocodeQuery $query): string
      */
     private function withApiCredentials(array $queryParams): array
     {
-        if (
-            empty($this->apiKey)
-            && (empty($this->appId) || empty($this->appCode))
-        ) {
-            throw new InvalidCredentials('Invalid or missing api key.');
-        }
-
         if (null !== $this->apiKey) {
             $queryParams['apiKey'] = $this->apiKey;
-        } else {
+        } elseif (!empty($this->appId) && !empty($this->appCode)) {
             $queryParams['app_id'] = $this->appId;
             $queryParams['app_code'] = $this->appCode;
+        } else {
+            throw new InvalidCredentials('Invalid or missing api key.');
         }
 
         return $queryParams;
@@ -310,6 +445,10 @@ public function getBaseUrl(Query $query): string
     {
         $usingApiKey = null !== $this->apiKey;
 
+        if ('7' === $this->version && $usingApiKey) {
+            return ($query instanceof ReverseQuery) ? self::GS7_REVERSE_ENDPOINT_URL : self::GS7_GEOCODE_ENDPOINT_URL;
+        }
+
         if ($query instanceof ReverseQuery) {
             if ($this->useCIT) {
                 return $usingApiKey ? self::REVERSE_CIT_ENDPOINT_URL_API_KEY : self::REVERSE_CIT_ENDPOINT_URL_APP_CODE;

Model/HereAddress.php

@@ -22,27 +22,27 @@ final class HereAddress extends Address
     /**
      * @var string|null
      */
-    private $locationId;
+    private ?string $locationId = null;
 
     /**
      * @var string|null
      */
-    private $locationType;
+    private ?string $locationType = null;
 
     /**
      * @var string|null
      */
-    private $locationName;
+    private ?string $locationName = null;
 
     /**
      * @var array<string, mixed>|null
      */
-    private $additionalData;
+    private ?array $additionalData = [];
 
     /**
      * @var array<string, mixed>|null
      */
-    private $shape;
+    private ?array $shape = [];
 
     /**
      * @return string|null
@@ -107,8 +107,10 @@ public function withAdditionalData(?array $additionalData = null): self
     {
         $new = clone $this;
 
-        foreach ($additionalData as $data) {
-            $new = $new->addAdditionalData($data['key'], $data['value']);
+        if (null !== $additionalData) {
+            foreach ($additionalData as $data) {
+                $new = $new->addAdditionalData($data['key'], $data['value']);
+            }
         }
 
         return $new;
@@ -136,7 +138,7 @@ public function getAdditionalDataValue(string $name, mixed $default = null): mix
 
     public function hasAdditionalDataValue(string $name): bool
     {
-        return array_key_exists($name, $this->additionalData);
+        return null !== $this->additionalData && array_key_exists($name, $this->additionalData);
     }
 
     /**
@@ -174,6 +176,6 @@ public function getShapeValue(string $name, mixed $default = null): mixed
 
     public function hasShapeValue(string $name): bool
     {
-        return array_key_exists($name, $this->shape);
+        return null !== $this->shape && array_key_exists($name, $this->shape);
     }
 }