docs: update google maps code in readme (#1030)

* docs: update google maps code in readme

* fix: throw exception if API key is not provided

* fix: tests

* docs: update google maps docs

Author: atymic

README.md

@@ -89,7 +89,7 @@ use Geocoder\Query\GeocodeQuery;
 use Geocoder\Query\ReverseQuery;
 
 $httpClient = new \Http\Adapter\Guzzle6\Client();
-$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient);
+$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient, null, 'your-api-key');
 $geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');
 
 $result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));

src/Common/Tests/ProviderAggregatorTest.php

@@ -13,7 +13,6 @@
 namespace Geocoder\Tests;
 
 use Geocoder\Collection;
-use Geocoder\Geocoder;
 use Geocoder\Model\Address;
 use Geocoder\Model\AddressCollection;
 use Geocoder\Query\GeocodeQuery;

src/Provider/GoogleMaps/GoogleMaps.php

@@ -52,7 +52,7 @@ final class GoogleMaps extends AbstractHttpProvider implements Provider
     private $apiKey;
 
     /**
-     * @var string
+     * @var string|null
      */
     private $clientId;
 
@@ -68,7 +68,8 @@ final class GoogleMaps extends AbstractHttpProvider implements Provider
 
     /**
      * Google Maps for Business
-     * https://developers.google.com/maps/documentation/business/.
+     * https://developers.google.com/maps/documentation/business/
+     * Maps for Business is no longer accepting new signups
      *
      * @param HttpClient $client     An HTTP adapter
      * @param string     $clientId   Your Client ID
@@ -167,6 +168,10 @@ public function getName(): string
      */
     private function buildQuery(string $url, string $locale = null, string $region = null): string
     {
+        if (null === $this->apiKey && null === $this->clientId) {
+            throw new InvalidCredentials('You must provide an API key. Keyless access was removed in June, 2016');
+        }
+
         if (null !== $locale) {
             $url = sprintf('%s&language=%s', $url, $locale);
         }

src/Provider/GoogleMaps/Readme.md

@@ -10,15 +10,42 @@
 This is the Google Maps provider from the PHP Geocoder. This is a **READ ONLY** repository. See the
 [main repo](https://github.com/geocoder-php/Geocoder) for information and documentation. 
 
+## Usage
+
+```php
+$httpClient = new \Http\Adapter\Guzzle6\Client();
+
+// You must provide an API key
+$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient, null, 'your-api-key');
+
+$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
+```
+
+All requests require a valid API key, however google does have a [free tier](https://cloud.google.com/maps-platform/pricing/) available.
+Please see [this page for information on getting an API key](https://developers.google.com/maps/documentation/geocoding/get-api-key).
+
+### Google Maps for Business
+
+Previously, google offered a "Business" version of their APIs. The service has been deprecated, however existing clients
+can use the static `business` method on the provider to create a client:
+
+```php
+
+$httpClient = new \Http\Adapter\Guzzle6\Client();
+
+// Client ID is required. Private key is optional.
+$provider = \Geocoder\Provider\GoogleMaps\GoogleMaps::business($httpClient, 'your-client-id', 'your-private-key');
+
+$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
+```
+
 ### Install
 
 ```bash
 composer require geocoder-php/google-maps-provider
 ```
 
-### Note
 
-A valid `Client ID` is required for GoogleMaps for Business. The private key is optional. 
 
 ### Contribute
 

src/Provider/GoogleMaps/Tests/GoogleMapsTest.php

@@ -41,7 +41,7 @@ protected function getCacheDir()
 
     public function testGetName()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient());
+        $provider = new GoogleMaps($this->getMockedHttpClient(), null, 'mock-api-key');
         $this->assertEquals('google_maps', $provider->getName());
     }
 
@@ -50,7 +50,7 @@ public function testGetName()
      */
     public function testGeocodeWithLocalhostIPv4()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient());
+        $provider = new GoogleMaps($this->getMockedHttpClient(), null, 'mock-api-key');
         $provider->geocodeQuery(GeocodeQuery::create('127.0.0.1'));
     }
 
@@ -60,7 +60,7 @@ public function testGeocodeWithLocalhostIPv4()
      */
     public function testGeocodeWithLocalhostIPv6()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient());
+        $provider = new GoogleMaps($this->getMockedHttpClient(), null, 'mock-api-key');
         $provider->geocodeQuery(GeocodeQuery::create('::1'));
     }
 
@@ -80,7 +80,7 @@ public function testGeocodeWithRealIp()
      */
     public function testGeocodeWithQuotaExceeded()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient('{"status":"OVER_QUERY_LIMIT"}'));
+        $provider = new GoogleMaps($this->getMockedHttpClient('{"status":"OVER_QUERY_LIMIT"}'), null, 'mock-api-key');
         $provider->geocodeQuery(GeocodeQuery::create('10 avenue Gambetta, Paris, France'));
     }
 
@@ -148,7 +148,7 @@ public function testGeocodeBoundsWithRealAddressForNonRooftopLocation()
      */
     public function testReverse()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient());
+        $provider = new GoogleMaps($this->getMockedHttpClient(), null, 'mock-api-key');
         $provider->reverseQuery(ReverseQuery::fromCoordinates(1, 2));
     }
 
@@ -221,7 +221,7 @@ public function testGeocodeWithCityDistrict()
      */
     public function testGeocodeWithInvalidApiKey()
     {
-        $provider = new GoogleMaps($this->getMockedHttpClient('{"error_message":"The provided API key is invalid.", "status":"REQUEST_DENIED"}'));
+        $provider = new GoogleMaps($this->getMockedHttpClient('{"error_message":"The provided API key is invalid.", "status":"REQUEST_DENIED"}'), null, 'mock-api-key');
         $provider->geocodeQuery(GeocodeQuery::create('10 avenue Gambetta, Paris, France'));
     }
 
@@ -274,7 +274,9 @@ public function testCorrectlySerializesComponents()
                 function (RequestInterface $request) use (&$uri) {
                     $uri = (string) $request->getUri();
                 }
-            )
+            ),
+            null,
+            'test-api-key'
         );
 
         $query = GeocodeQuery::create('address')->withData('components', [
@@ -291,7 +293,7 @@ function (RequestInterface $request) use (&$uri) {
         $this->assertEquals(
             'https://maps.googleapis.com/maps/api/geocode/json'.
             '?address=address'.
-            '&components=country%3ASE%7Cpostal_code%3A22762%7Clocality%3ALund',
+            '&components=country%3ASE%7Cpostal_code%3A22762%7Clocality%3ALund&key=test-api-key',
             $uri
         );
     }
@@ -305,7 +307,9 @@ public function testCorrectlySetsComponents()
                 function (RequestInterface $request) use (&$uri) {
                     $uri = (string) $request->getUri();
                 }
-            )
+            ),
+            null,
+            'test-api-key'
         );
 
         $query = GeocodeQuery::create('address')
@@ -319,7 +323,7 @@ function (RequestInterface $request) use (&$uri) {
         $this->assertEquals(
             'https://maps.googleapis.com/maps/api/geocode/json'.
             '?address=address'.
-            '&components=country%3ASE%7Cpostal_code%3A22762%7Clocality%3ALund',
+            '&components=country%3ASE%7Cpostal_code%3A22762%7Clocality%3ALund&key=test-api-key',
             $uri
         );
     }