Skip to content

Commit d7363b2

Browse files
willdurandwilldurand
committed
Merge pull request #386 from geocoder-php/collection
[RFC] Introduce AddressCollection class
2 parents 0792a1a + 19134d7 commit d7363b2

24 files changed

+322
-239
lines changed

‎README.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -112,8 +112,10 @@ It also contains methods to control the number of results:
112112
* `limit($limit)`
113113
* `getLimit()`
114114

115-
Both `geocode()` and `reverse()` methods return an array of `Address` objects,
116-
each providing the following API:
115+
### Address & AddressCollection
116+
117+
Both `geocode()` and `reverse()` methods return a collection of `Address`
118+
objects (`AddressCollection`), each providing the following API:
117119

118120
* `getCoordinates()` will return a `Coordinates` object (with `latitude` and
119121
`longitude` properties);
@@ -137,6 +139,16 @@ each providing the following API:
137139
* `getCountryCode()` will return the ISO `country` code;
138140
* `getTimezone()` will return the `timezone`.
139141

142+
The `AddressCollection` exposes the following methods:
143+
144+
* `count()` (this class implements `Countable`);
145+
* `first()` retrieves the first `Address`;
146+
* `slice($offset, $length = null)` returns `Address` objects between `$offset`
147+
and `length`;
148+
* `get($index)` fetches an `Address` using its `$index`;
149+
* `all()` returns all `Address` objects;
150+
* `getIterator()` (this class implements `IteratorAggregate`).
151+
140152
### Locale Aware Providers
141153

142154
Providers that are _locale aware_ expose the following methods:
@@ -208,7 +220,7 @@ $reader = new \GeoIp2\Database\Reader('/path/to/database');
208220
$adapter = new \Geocoder\Adapter\GeoIP2Adapter($reader);
209221
$geocoder = new \Geocoder\Provider\GeoIP2($adapter);
210222

211-
$address = $geocoder->geocode('74.200.247.59');
223+
$address = $geocoder->geocode('74.200.247.59')->first();
212224
```
213225

214226
### TomTom

‎src/Geocoder/Model/AddressCollection.php‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
<?php
2+
3+
namespace Geocoder\Model;
4+
5+
final class AddressCollection implements \IteratorAggregate, \Countable
6+
{
7+
/**
8+
* @var Address[]
9+
*/
10+
private $addresses;
11+
12+
public function __construct(array $addresses = [])
13+
{
14+
$this->addresses = array_values($addresses);
15+
}
16+
17+
/**
18+
* {@inheritDoc}
19+
*/
20+
public function getIterator()
21+
{
22+
return new \ArrayIterator($this->all());
23+
}
24+
25+
/**
26+
* {@inheritDoc}
27+
*/
28+
public function count()
29+
{
30+
return count($this->addresses);
31+
}
32+
33+
/**
34+
* @return Address
35+
*/
36+
public function first()
37+
{
38+
if (empty($this->addresses)) {
39+
return null;
40+
}
41+
42+
return reset($this->addresses);
43+
}
44+
45+
/**
46+
* @return Address[]
47+
*/
48+
public function slice($offset, $length = null)
49+
{
50+
return array_slice($this->addresses, $offset, $length);
51+
}
52+
53+
/**
54+
* @return Address
55+
*/
56+
public function get($index)
57+
{
58+
if (!isset($this->addresses[$index])) {
59+
throw new \OutOfBoundsException(sprintf('The index "%s" does not exist in this collection.', $index));
60+
}
61+
62+
return $this->addresses[$index];
63+
}
64+
65+
/**
66+
* @return Address[]
67+
*/
68+
public function all()
69+
{
70+
return $this->addresses;
71+
}
72+
}

‎src/Geocoder/Model/AddressFactory.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ public function createFromArray(array $results)
5252
);
5353
}
5454

55-
return $addresses;
55+
return new AddressCollection($addresses);
5656
}
5757

5858
/**

‎src/Geocoder/Provider/IpInfoDb.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@ class IpInfoDb extends AbstractHttpProvider implements Provider
4242
private $endpointUrl;
4343

4444
/**
45-
* @param HttpAdapterInterface $adapter An HTTP adapter.
46-
* @param string $apiKey An API key.
45+
* @param HttpAdapterInterface $adapter An HTTP adapter.
46+
* @param string $apiKey An API key.
4747
* @param string $precision The endpoint precision. Either "city" or "country" (faster)
4848
*
4949
* @throws Geocoder\Exception\InvalidArgument

‎tests/Geocoder/Tests/Model/AddressFactoryTest.php‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ public function testCreateFromArray()
2727
[ 'streetNumber' => 3 ],
2828
]);
2929

30-
$this->assertTrue(is_array($addresses));
30+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $addresses);
3131
$this->assertCount(3, $addresses);
3232

3333
$i = 1;
@@ -52,8 +52,7 @@ public function testFormatStringWithLeadingNumeral()
5252
$addresses = $this->factory->createFromArray([
5353
[ 'streetName' => '1st ave 1A' ],
5454
]);
55-
$address = current($addresses);
5655

57-
$this->assertEquals('1st ave 1A', $address->getStreetName());
56+
$this->assertEquals('1st ave 1A', $addresses->first()->getStreetName());
5857
}
5958
}

‎tests/Geocoder/Tests/Provider/ArcGISOnlineTest.php‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -77,11 +77,11 @@ public function testGeocodeWithRealAddress()
7777
$provider = new ArcGISOnline($this->getAdapter());
7878
$results = $provider->geocode('10 avenue Gambetta, Paris, France');
7979

80-
$this->assertInternalType('array', $results);
80+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
8181
$this->assertCount(5, $results);
8282

8383
/** @var \Geocoder\Model\Address $result */
84-
$result = $results[0];
84+
$result = $results->first();
8585
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
8686
$this->assertEquals(48.863279997000461, $result->getLatitude(), '', 0.0001);
8787
$this->assertEquals(2.3890199980004354, $result->getLongitude(), '', 0.0001);
@@ -106,11 +106,11 @@ public function testGeocodeWithRealAddressAndHttps()
106106
$provider = new ArcGISOnline($this->getAdapter(), null, true);
107107
$results = $provider->geocode('10 avenue Gambetta, Paris, France');
108108

109-
$this->assertInternalType('array', $results);
109+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
110110
$this->assertCount(5, $results);
111111

112112
/** @var \Geocoder\Model\Address $result */
113-
$result = $results[0];
113+
$result = $results->first();
114114
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
115115
$this->assertEquals(48.863279997000461, $result->getLatitude(), '', 0.0001);
116116
$this->assertEquals(2.3890199980004354, $result->getLongitude(), '', 0.0001);
@@ -176,11 +176,11 @@ public function testReverseWithRealCoordinates()
176176
$provider = new ArcGISOnline($this->getAdapter());
177177
$results = $provider->reverse(48.863279997000461, 2.3890199980004354);
178178

179-
$this->assertInternalType('array', $results);
179+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
180180
$this->assertCount(1, $results);
181181

182182
/** @var \Geocoder\Model\Address $result */
183-
$result = $results[0];
183+
$result = $results->first();
184184
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
185185
$this->assertEquals(48.863279997000461, $result->getLatitude(), '', 0.0001);
186186
$this->assertEquals(2.3890199980004354, $result->getLongitude(), '', 0.0001);
@@ -205,11 +205,11 @@ public function testReverseWithRealCoordinatesWithHttps()
205205
$provider = new ArcGISOnline($this->getAdapter(), null, true);
206206
$results = $provider->reverse(48.863279997000461, 2.3890199980004354);
207207

208-
$this->assertInternalType('array', $results);
208+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
209209
$this->assertCount(1, $results);
210210

211211
/** @var \Geocoder\Model\Address $result */
212-
$result = $results[0];
212+
$result = $results->first();
213213
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
214214
$this->assertEquals(48.863279997000461, $result->getLatitude(), '', 0.0001);
215215
$this->assertEquals(2.3890199980004354, $result->getLongitude(), '', 0.0001);
@@ -234,11 +234,11 @@ public function testGeocodeWithCity()
234234
$provider = new ArcGISOnline($this->getAdapter());
235235
$results = $provider->geocode('Hannover');
236236

237-
$this->assertInternalType('array', $results);
237+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
238238
$this->assertCount(5, $results);
239239

240240
/** @var \Geocoder\Model\Address $result */
241-
$result = $results[0];
241+
$result = $results->first();
242242
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
243243
$this->assertEquals(52.370518568000477, $result->getLatitude(), '', 0.0001);
244244
$this->assertEquals(9.7332166860004463, $result->getLongitude(), '', 0.0001);
@@ -258,7 +258,7 @@ public function testGeocodeWithCity()
258258
$this->assertNull($result->getTimezone());
259259

260260
/** @var \Geocoder\Model\Address $result */
261-
$result = $results[1];
261+
$result = $results->get(1);
262262
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
263263
$this->assertEquals(47.111386795000499, $result->getLatitude(), '', 0.0001);
264264
$this->assertEquals(-101.4265391569997, $result->getLongitude(), '', 0.0001);
@@ -268,7 +268,7 @@ public function testGeocodeWithCity()
268268
$this->assertEquals('USA', $result->getCountry()->getCode());
269269

270270
/** @var \Geocoder\Model\Address $result */
271-
$result = $results[2];
271+
$result = $results->get(2);
272272
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
273273
$this->assertEquals(39.391768472000479, $result->getLatitude(), '', 0.0001);
274274
$this->assertEquals(-77.440257128999633, $result->getLongitude(), '', 0.0001);
@@ -278,7 +278,7 @@ public function testGeocodeWithCity()
278278
$this->assertEquals('USA', $result->getCountry()->getCode());
279279

280280
/** @var \Geocoder\Model\Address $result */
281-
$result = $results[3];
281+
$result = $results->get(3);
282282
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
283283
$this->assertEquals(53.174198173, $result->getLatitude(), '', 0.0001);
284284
$this->assertEquals(8.5069383810005, $result->getLongitude(), '', 0.0001);
@@ -289,7 +289,7 @@ public function testGeocodeWithCity()
289289
$this->assertEquals('DEU', $result->getCountry()->getCode());
290290

291291
/** @var \Geocoder\Model\Address $result */
292-
$result = $results[4];
292+
$result = $results->get(4);
293293
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
294294
$this->assertEquals(-26.281805980999593, $result->getLatitude(), '', 0.0001);
295295
$this->assertEquals(-48.849389793999649, $result->getLongitude(), '', 0.0001);

‎tests/Geocoder/Tests/Provider/BingMapsTest.php‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,11 @@ public function testGeocodeReturnsMultipleResults()
9191
$provider = new BingMaps($this->getMockAdapterReturns($json), 'api_key', 'fr_FR');
9292
$results = $provider->geocode('10 avenue Gambetta, Paris, France');
9393

94-
$this->assertInternalType('array', $results);
94+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
9595
$this->assertCount(3, $results);
9696

9797
/** @var \Geocoder\Model\Address $result */
98-
$result = $results[0];
98+
$result = $results->first();
9999
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
100100
$this->assertEquals(48.86321675999999, $result->getLatitude(), '', 0.01);
101101
$this->assertEquals(2.3887721299999995, $result->getLongitude(), '', 0.01);
@@ -116,7 +116,7 @@ public function testGeocodeReturnsMultipleResults()
116116
$this->assertNull($result->getTimezone());
117117

118118
/** @var \Geocoder\Model\Address $result */
119-
$result = $results[1];
119+
$result = $results->get(1);
120120
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
121121
$this->assertEquals(48.81342781, $result->getLatitude(), '', 0.01);
122122
$this->assertEquals(2.32503767, $result->getLongitude(), '', 0.01);
@@ -134,7 +134,7 @@ public function testGeocodeReturnsMultipleResults()
134134
$this->assertEquals('France', $result->getCountry()->getName());
135135

136136
/** @var \Geocoder\Model\Address $result */
137-
$result = $results[2];
137+
$result = $results->get(2);
138138
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
139139
$this->assertEquals(48.81014147, $result->getLatitude(), '', 0.01);
140140
$this->assertEquals(2.43568048, $result->getLongitude(), '', 0.01);
@@ -161,11 +161,11 @@ public function testReverseReturnsSingleResult()
161161
$provider = new BingMaps($this->getMockAdapterReturns($json), 'api_key');
162162
$results = $provider->reverse(48.86321648955345, 2.3887719959020615);
163163

164-
$this->assertInternalType('array', $results);
164+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
165165
$this->assertCount(1, $results);
166166

167167
/** @var \Geocoder\Model\Address $result */
168-
$result = $results[0];
168+
$result = $results->first();
169169
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
170170
$this->assertEquals(48.86321648955345, $result->getLatitude(), '', 0.0001);
171171
$this->assertEquals(2.3887719959020615, $result->getLongitude(), '', 0.0001);
@@ -195,11 +195,11 @@ public function testGeocodeWithRealAddressReturnsMultipleResults()
195195
$provider = new BingMaps($this->getAdapter(), $_SERVER['BINGMAPS_API_KEY'], 'fr-FR');
196196
$results = $provider->geocode('10 avenue Gambetta, Paris, France');
197197

198-
$this->assertInternalType('array', $results);
198+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
199199
$this->assertCount(3, $results);
200200

201201
/** @var \Geocoder\Model\Address $result */
202-
$result = $results[0];
202+
$result = $results->first();
203203
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
204204
$this->assertEquals(48.86321675999999, $result->getLatitude(), '', 0.01);
205205
$this->assertEquals(2.3887721299999995, $result->getLongitude(), '', 0.01);
@@ -220,7 +220,7 @@ public function testGeocodeWithRealAddressReturnsMultipleResults()
220220
$this->assertNull($result->getTimezone());
221221

222222
/** @var \Geocoder\Model\Address $result */
223-
$result = $results[1];
223+
$result = $results->get(1);
224224
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
225225
$this->assertEquals(48.81342781, $result->getLatitude(), '', 0.01);
226226
$this->assertEquals(2.32503767, $result->getLongitude(), '', 0.01);
@@ -238,7 +238,7 @@ public function testGeocodeWithRealAddressReturnsMultipleResults()
238238
$this->assertEquals('France', $result->getCountry()->getName());
239239

240240
/** @var \Geocoder\Model\Address $result */
241-
$result = $results[2];
241+
$result = $results->get(2);
242242
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
243243
$this->assertEquals(48.81014147, $result->getLatitude(), '', 0.01);
244244
$this->assertEquals(2.43568048, $result->getLongitude(), '', 0.01);
@@ -285,11 +285,11 @@ public function testReverseWithRealCoordinatesReturnsSingleResult()
285285
$provider = new BingMaps($this->getAdapter(), $_SERVER['BINGMAPS_API_KEY']);
286286
$results = $provider->reverse(48.86321648955345, 2.3887719959020615);
287287

288-
$this->assertInternalType('array', $results);
288+
$this->assertInstanceOf('Geocoder\Model\AddressCollection', $results);
289289
$this->assertCount(1, $results);
290290

291291
/** @var \Geocoder\Model\Address $result */
292-
$result = $results[0];
292+
$result = $results->first();
293293
$this->assertInstanceOf('\Geocoder\Model\Address', $result);
294294
$this->assertEquals(48.86321648955345, $result->getLatitude(), '', 0.0001);
295295
$this->assertEquals(2.3887719959020615, $result->getLongitude(), '', 0.0001);

0 commit comments

Comments
 (0)