Add premium endpoint and token authentication support for Geonames provider

- Add optional token parameter to Geonames constructor
- Add secure flag to enable https://secure.geonames.net endpoint
- Support dynamic base URL (api.geonames.org or secure.geonames.net)
- Append token parameter to all API requests when provided
- Maintain backward compatibility with existing username-only authentication

Author: web-flow

src/Provider/Geonames/Geonames.php

@@ -52,17 +52,38 @@ final class Geonames extends AbstractHttpProvider implements Provider
      */
     private $username;
 
+    /**
+     * @var string|null
+     */
+    private $token;
+
+    /**
+     * @var string
+     */
+    private $baseUrl;
+
     /**
      * @param ClientInterface $client   An HTTP adapter
      * @param string          $username Username login (Free registration at http://www.geonames.org/login)
+     * @param string|null     $token    Optional token for premium accounts
+     * @param bool            $secure   Use secure endpoint (https://secure.geonames.net) for premium accounts
      */
-    public function __construct(ClientInterface $client, string $username)
+    public function __construct(ClientInterface $client, string $username, ?string $token = null, bool $secure = false)
     {
         if (empty($username)) {
             throw new InvalidCredentials('No username provided.');
         }
 
         $this->username = $username;
+        $this->token = $token;
+
+        // Determine base URL based on secure flag
+        if ($secure) {
+            $this->baseUrl = 'https://secure.geonames.net';
+        } else {
+            $this->baseUrl = 'http://api.geonames.org';
+        }
+
         parent::__construct($client);
     }
 
@@ -75,7 +96,15 @@ public function geocodeQuery(GeocodeQuery $query): Collection
             throw new UnsupportedOperation('The Geonames provider does not support IP addresses.');
         }
 
-        $url = sprintf(self::GEOCODE_ENDPOINT_URL, urlencode($address), $query->getLimit(), $this->username);
+        $url = sprintf(
+            '%s/searchJSON?q=%s&maxRows=%d&style=full&username=%s',
+            $this->baseUrl,
+            urlencode($address),
+            $query->getLimit(),
+            $this->username
+        );
+
+        $url = $this->appendToken($url);
 
         return $this->executeQuery($url, $query->getLocale());
     }
@@ -86,7 +115,16 @@ public function reverseQuery(ReverseQuery $query): Collection
         $longitude = $coordinates->getLongitude();
         $latitude = $coordinates->getLatitude();
 
-        $url = sprintf(self::REVERSE_ENDPOINT_URL, $latitude, $longitude, $query->getLimit(), $this->username);
+        $url = sprintf(
+            '%s/findNearbyPlaceNameJSON?lat=%F&lng=%F&style=full&maxRows=%d&username=%s',
+            $this->baseUrl,
+            $latitude,
+            $longitude,
+            $query->getLimit(),
+            $this->username
+        );
+
+        $url = $this->appendToken($url);
 
         return $this->executeQuery($url, $query->getLocale());
     }
@@ -96,7 +134,7 @@ public function reverseQuery(ReverseQuery $query): Collection
      */
     public function getCountryInfo(?string $country = null, ?string $locale = null): array
     {
-        $url = sprintf(self::BASE_ENDPOINT_URL, 'countryInfoJSON', $this->username);
+        $url = sprintf('%s/countryInfoJSON?username=%s', $this->baseUrl, $this->username);
 
         if (isset($country)) {
             $url = sprintf('%s&country=%s', $url, $country);
@@ -109,6 +147,8 @@ public function getCountryInfo(?string $country = null, ?string $locale = null):
             $url = sprintf('%s&lang=%s', $url, substr($locale, 0, 2));
         }
 
+        $url = $this->appendToken($url);
+
         $content = $this->getUrlContents($url);
         if (null === $json = json_decode($content)) {
             throw InvalidServerResponse::create($url);
@@ -217,4 +257,16 @@ private function executeQuery(string $url, ?string $locale = null): AddressColle
 
         return new AddressCollection($results);
     }
+
+    /**
+     * Append token parameter to URL if token is provided.
+     */
+    private function appendToken(string $url): string
+    {
+        if (null !== $this->token && '' !== $this->token) {
+            $url = sprintf('%s&token=%s', $url, $this->token);
+        }
+
+        return $url;
+    }
 }