Issue #3406303 by progga, itamair: Pass additional parameters to geocoders

geocoder.api.php

@@ -8,15 +8,26 @@
 /**
  * Alter the Address String to Geocode.
  *
- * Allow others modules to adjust the address string.
+ * Allow other modules to adjust the address string.
  *
  * @param string $address_string
  *   The address string to geocode.
- * */
+ */
 function hook_geocode_address_string_alter(string &$address_string) {
   // Make custom alterations to adjust the address string.
 }
 
+/**
+ * Alter the address GeocodeQuery.
+ *
+ * Allow other modules to adjust the address GeocodeQuery.
+ *
+ * @param Geocoder\Query\GeocodeQuery $address
+ *   The address query to geocode.
+ */
+function hook_geocode_address_geocode_query(Geocoder\Query\GeocodeQuery $address) {
+}
+
 /**
  * Alter the Coordinates to Reverse Geocode.
  *
@@ -26,7 +37,7 @@ function hook_geocode_address_string_alter(string &$address_string) {
  *   The latitude.
  * @param string $longitude
  *   The longitude.
- * */
+ */
 function hook_reverse_geocode_coordinates_alter(string &$latitude, string &$longitude) {
   // Make custom alterations to the Coordinates to Reverse Geocode.
 }
@@ -40,7 +51,7 @@ function hook_reverse_geocode_coordinates_alter(string &$latitude, string &$long
  *   The geojson array.
  *
  * @see DumperPluginManager->setCountryFromGeojson
- * */
+ */
 function hook_geocode_country_code_alter(string &$country_code, array $geojson_array) {
   // Make custom alterations to the Country Code.
 }

src/Geocoder.php

@@ -7,8 +7,10 @@ namespace Drupal\geocoder;
 use Drupal\Core\Config\ConfigFactoryInterface;
 use Drupal\Core\Logger\LoggerChannelTrait;
 use Geocoder\Model\AddressCollection;
+use Geocoder\Query\GeocodeQuery;
 use Drupal\Core\Extension\ModuleHandlerInterface;
 use Drupal\geocoder\Entity\GeocoderProvider;
+use Geocoder\Provider\Provider as ProviderInterface;
 
 /**
  * Provides a geocoder factory class.
@@ -57,9 +59,14 @@ class Geocoder implements GeocoderInterface {
   /**
    * {@inheritdoc}
    */
-  public function geocode(string $address_string, array $providers) {
-    // Allow others modules to adjust the address string.
-    $this->moduleHandler->alter('geocode_address_string', $address_string);
+  public function geocode(GeocodeQuery|string $address, array $providers) {
+    // Allow other modules to adjust the address.
+    if (is_string($address)) {
+      $this->moduleHandler->alter('geocode_address_string', $address);
+    }
+    else {
+      $this->moduleHandler->alter('geocode_address_geocode_query', $address);
+    }
 
     /** @var \Drupal\geocoder\GeocoderProviderInterface $provider */
     foreach ($providers as $provider) {
@@ -74,9 +81,23 @@ class Geocoder implements GeocoderInterface {
             throw new \Exception(sprintf("Unable to define a GeocoderProvider from string '%s'", $provider_id));
           }
         }
-        $result = $provider->getPlugin()->geocode($address_string);
+
+        if (is_string($address)) {
+          $result = $provider->getPlugin()->geocode($address);
+        }
+        elseif ($provider->getPlugin() instanceof ProviderInterface) {
+          /** @var \Geocoder\Provider\Provider $provider_plugin */
+          $provider_plugin = $provider->getPlugin();
+          try {
+            $result = $provider_plugin->geocodeQuery($address);
+          }
+          catch (\Exception $e) {
+            $this->getLogger('geocoder')->warning($e->getMessage());
+          }
+        }
+
         if (!isset($result) || $result->isEmpty()) {
-          throw new \Exception(sprintf('Unable to geocode "%s" with the %s provider.', $address_string, $provider->id()));
+          throw new \Exception(sprintf('Unable to geocode "%s" with the %s provider.', $address, $provider->id()));
         }
         return $result;
       }
@@ -91,7 +112,7 @@ class Geocoder implements GeocoderInterface {
    * {@inheritdoc}
    */
   public function reverse(string $latitude, string $longitude, array $providers): ?AddressCollection {
-    // Allow others modules to adjust the coordinates.
+    // Allow other modules to adjust the coordinates.
     $this->moduleHandler->alter('reverse_geocode_coordinates', $latitude, $longitude);
 
     /** @var \Drupal\geocoder\GeocoderProviderInterface $provider */

src/GeocoderInterface.php

@@ -3,6 +3,7 @@
 namespace Drupal\geocoder;
 
 use Geocoder\Model\AddressCollection;
+use Geocoder\Query\GeocodeQuery;
 
 /**
  * Provides a geocoder factory method interface.
@@ -12,15 +13,15 @@ interface GeocoderInterface {
   /**
    * Geocodes a string.
    *
-   * @param string $address_string
-   *   The string to geocode.
+   * @param \Geocoder\Query\GeocodeQuery|string $address
+   *   The GeocodeQuery or string to geocode.
    * @param \Drupal\geocoder\GeocoderProviderInterface[] $providers
    *   A list of Geocoder providers to use to perform the geocoding.
    *
    * @return \Geocoder\Model\AddressCollection|\Geometry|null
    *   An address collection or NULL on geocoding failure.
    */
-  public function geocode(string $address_string, array $providers);
+  public function geocode(GeocodeQuery|string $address, array $providers);
 
   /**
    * Reverse geocodes coordinates.

tests/src/Kernel/GeocoderKernelTest.php

@@ -4,6 +4,7 @@ namespace Drupal\Tests\geocoder\Kernel;
 
 use Drupal\geocoder\Entity\GeocoderProvider;
 use Drupal\KernelTests\KernelTestBase;
+use Geocoder\Query\GeocodeQuery;
 
 /**
  * Tests basic Geocoder functionality.
@@ -15,7 +16,7 @@ class GeocoderKernelTest extends KernelTestBase {
   /**
    * {@inheritdoc}
    */
-  protected static $modules = ['geocoder'];
+  protected static $modules = ['geocoder', 'geocoder_test_provider'];
 
   /**
    * Our test provider.
@@ -58,4 +59,36 @@ class GeocoderKernelTest extends KernelTestBase {
     ]));
   }
 
+  /**
+   * Tests geocoding a GeocodeQuery.
+   *
+   * Tries the "random" Geocoder which cannot geocode a GeocodeQuery.
+   */
+  public function testRandomGeocodeWithGeocodeQuery() {
+    /** @var \Drupal\geocoder\GeocoderInterface $geocoder */
+    $geocoder = \Drupal::service('geocoder');
+    $this->assertEmpty($geocoder->geocode(GeocodeQuery::create('123 Foo Street'), [
+      'random',
+    ]));
+  }
+
+  /**
+   * Tests geocoding a GeocodeQuery.
+   *
+   * Tries the "geocoder_test_provider" Geocoder which can geocode a
+   * GeocodeQuery.
+   */
+  public function testGeocodeWithGeocodeQuery() {
+    GeocoderProvider::create([
+      'id'     => 'geocoder_test_provider',
+      'plugin' => 'geocoder_test_provider',
+    ])->save();
+
+    /** @var \Drupal\geocoder\GeocoderInterface $geocoder */
+    $geocoder = \Drupal::service('geocoder');
+    $this->assertNotEmpty($geocoder->geocode(GeocodeQuery::create('123 Foo Street'), [
+      'geocoder_test_provider',
+    ]));
+  }
+
 }