Merge pull request #398 from giosh94mhz/numbered_admin_levels

Use numbered administrative level instead of named one

README.md

@@ -106,12 +106,8 @@ objects (`AddressCollection`), each providing the following API:
 * `getLocality()` will return the `locality` or `city`;
 * `getPostalCode()` will return the `postalCode` or `zipcode`;
 * `getSubLocality()` will return the `city district`, or `sublocality`;
-* `getCounty()` will return a `County` object (with `name` and `code`
- properties);
-* `getCountyCode()` will return the `county` code (county short name);
-* `getRegion()` will return a `Region` object (with `name` and `code`
- properties);
-* `getRegionCode()` will return the `region` code (region short name);
+* `getAdminLevels()` will return an ordered collection (`AdminLevelCollection`)
+ of `AdminLevel` object (with `level`, `name` and `code` properties);
 * `getCountry()` will return a `Country` object (with `name` and `code`
  properties);
 * `getCountryCode()` will return the ISO `country` code;
@@ -478,13 +474,9 @@ Here is the mapping:
 
 * Zipcode: `%z`
 
-* County: `%P`
-
-* County Code: `%p`
-
-* Region: `%R`
+* Admin Level Name: `%A1`, `%A2`, `%A3`, `%A4`, `%A5`
 
-* Region Code: `%r`
+* Admin Level Code: `%a1`, `%a2`, `%a3`, `%a4`, `%a5`
 
 * Country: `%C`
 

src/Geocoder/Dumper/Gpx.php

@@ -69,20 +69,22 @@ public function dump(Address $address)
  */
  protected function formatName(Address $address)
  {
- $name = '';
+ $name = [];
  $array = $address->toArray();
- $attrs = array('streetNumber', 'streetName', 'postalCode', 'locality', 'county', 'region', 'country');
+ $attrs = [
+ ['streetNumber'],
+ ['streetName'],
+ ['postalCode'],
+ ['locality'],
+ ['adminLevels', 2, 'name'],
+ ['adminLevels', 1, 'name'],
+ ['country'],
+ ];
 
  foreach ($attrs as $attr) {
- if (isset($array[$attr]) && !empty($array[$attr])) {
- $name .= sprintf('%s, ', $array[$attr]);
- }
+ $name[] = \igorw\get_in($array, $attr);
  }
 
- if (strlen($name) > 1) {
- $name = substr($name, 0, strlen($name) - 2);
- }
-
- return $name;
+ return implode(', ', array_filter($name));
  }
 }

src/Geocoder/Exception/UnexpectedValue.php

@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * This file is part of the Geocoder package.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license MIT License
+ */
+
+namespace Geocoder\Exception;
+
+/**
+ * @author Giorgio Premi <giosh94mhz@gmail.com>
+ */
+class UnexpectedValue extends \UnexpectedValueException implements Exception
+{
+}

src/Geocoder/Formatter/StringFormatter.php

@@ -11,35 +11,33 @@
 namespace Geocoder\Formatter;
 
 use Geocoder\Model\Address;
+use Geocoder\Model\AdminLevel;
+use Geocoder\Model\AdminLevelCollection;
 
 /**
  * @author William Durand <william.durand1@gmail.com>
  */
 class StringFormatter
 {
- const STREET_NUMBER = '%n';
+ const STREET_NUMBER  = '%n';
 
- const STREET_NAME = '%S';
+ const STREET_NAME  = '%S';
 
- const LOCALITY = '%L';
+ const LOCALITY  = '%L';
 
- const POSTAL_CODE = '%z';
+ const POSTAL_CODE  = '%z';
 
- const SUB_LOCALITY = '%D';
+ const SUB_LOCALITY  = '%D';
 
- const COUNTY  = '%P';
+ const ADMIN_LEVEL = '%A';
 
- const COUNTY_CODE = '%p';
+ const ADMIN_LEVEL_CODE = '%a';
 
- const REGION = '%R';
+ const COUNTRY  = '%C';
 
- const REGION_CODE = '%r';
+ const COUNTRY_CODE  = '%c';
 
- const COUNTRY = '%C';
-
- const COUNTRY_CODE = '%c';
-
- const TIMEZONE = '%T';
+ const TIMEZONE = '%T';
 
  /**
  * Transform an `Address` instance into a string representation.
@@ -51,19 +49,27 @@ class StringFormatter
  */
  public function format(Address $address, $format)
  {
- return strtr($format, array(
+ $replace = [
  self::STREET_NUMBER => $address->getStreetNumber(),
  self::STREET_NAME => $address->getStreetName(),
  self::LOCALITY => $address->getLocality(),
  self::POSTAL_CODE => $address->getPostalCode(),
  self::SUB_LOCALITY => $address->getSubLocality(),
- self::COUNTY => $address->getCounty()->getName(),
- self::COUNTY_CODE => $address->getCounty()->getCode(),
- self::REGION => $address->getRegion()->getName(),
- self::REGION_CODE => $address->getRegion()->getCode(),
  self::COUNTRY => $address->getCountry()->getName(),
  self::COUNTRY_CODE => $address->getCountry()->getCode(),
  self::TIMEZONE => $address->getTimezone(),
- ));
+ ];
+
+ for ($level = 1; $level <= AdminLevelCollection::MAX_LEVEL_DEPTH; $level ++) {
+ $replace[self::ADMIN_LEVEL . $level] = null;
+ $replace[self::ADMIN_LEVEL_CODE . $level] = null;
+ }
+
+ foreach ($address->getAdminLevels() as $level => $adminLevel) {
+ $replace[self::ADMIN_LEVEL . $level] = $adminLevel->getName();
+ $replace[self::ADMIN_LEVEL_CODE . $level] = $adminLevel->getCode();
+ }
+
+ return strtr($format, $replace);
  }
 }

src/Geocoder/Geocoder.php

@@ -10,7 +10,7 @@
 
 namespace Geocoder;
 
-use Geocoder\Model\Address;
+use Geocoder\Model\AddressCollection;
 
 /**
  * @author William Durand <william.durand1@gmail.com>
@@ -27,17 +27,17 @@ interface Geocoder
  *
  * @param string $value
  *
- * @return Address[]
+ * @return AddressCollection
  */
  public function geocode($value);
 
  /**
  * Reverses geocode given latitude and longitude values.
  *
- * @param double $latitude.
+ * @param double $latitude
  * @param double $longitude
  *
- * @return Address[]
+ * @return AddressCollection
  */
  public function reverse($latitude, $longitude);
 

src/Geocoder/Model/Address.php

@@ -51,14 +51,9 @@ final class Address
  private $postalCode;
 
  /**
- * @var County
+ * @var AdminLevelCollection
  */
- private $county;
-
- /**
- * @var Region
- */
- private $region;
+ private $adminLevels;
 
  /**
  * @var Country
@@ -78,17 +73,16 @@ final class Address
  * @param string $subLocality
  */
  public function __construct(
- Coordinates $coordinates = null,
- Bounds $bounds = null,
- $streetNumber = null,
- $streetName = null,
- $postalCode = null,
- $locality = null,
- $subLocality = null,
- County $county = null,
- Region $region = null,
- Country $country = null,
- $timezone = null
+ Coordinates $coordinates = null,
+ Bounds $bounds = null,
+ $streetNumber = null,
+ $streetName = null,
+ $postalCode = null,
+ $locality = null,
+ $subLocality = null,
+ AdminLevelCollection $adminLevels = null,
+ Country $country = null,
+ $timezone = null
  ) {
  $this->coordinates = $coordinates;
  $this->bounds = $bounds;
@@ -97,8 +91,7 @@ public function __construct(
  $this->postalCode = $postalCode;
  $this->locality = $locality;
  $this->subLocality = $subLocality;
- $this->county = $county;
- $this->region = $region;
+ $this->adminLevels = $adminLevels ?: new AdminLevelCollection();
  $this->country = $country;
  $this->timezone = $timezone;
  }
@@ -203,43 +196,13 @@ public function getSubLocality()
  }
 
  /**
- * Returns the county value.
+ * Returns the administrative levels.
  *
- * @return County
+ * @return AdminLevelCollection
  */
- public function getCounty()
+ public function getAdminLevels()
  {
- return $this->county;
- }
-
- /**
- * Returns the county short name.
- *
- * @return string
- */
- public function getCountyCode()
- {
- return $this->county->getCode();
- }
-
- /**
- * Returns the region value.
- *
- * @return Region
- */
- public function getRegion()
- {
- return $this->region;
- }
-
- /**
- * Returns the region short name.
- *
- * @return string
- */
- public function getRegionCode()
- {
- return $this->region->getCode();
+ return $this->adminLevels;
  }
 
  /**
@@ -279,6 +242,14 @@ public function getTimezone()
  */
  public function toArray()
  {
+ $adminLevels = [];
+ foreach ($this->adminLevels as $adminLevel) {
+ $adminLevels[$adminLevel->getLevel()] = [
+ 'name' => $adminLevel->getName(),
+ 'code' => $adminLevel->getCode()
+ ];
+ }
+
  return array(
  'latitude' => $this->getLatitude(),
  'longitude' => $this->getLongitude(),
@@ -288,10 +259,7 @@ public function toArray()
  'postalCode' => $this->postalCode,
  'locality' => $this->locality,
  'subLocality' => $this->subLocality,
- 'county' => $this->county->getName(),
- 'countyCode' => $this->county->getCode(),
- 'region' => $this->region->getName(),
- 'regionCode' => $this->region->getCode(),
+ 'adminLevels' => $adminLevels,
  'country' => $this->country->getName(),
  'countryCode' => $this->country->getCode(),
  'timezone' => $this->timezone,

src/Geocoder/Model/AddressCollection.php

@@ -9,6 +9,9 @@ final class AddressCollection implements \IteratorAggregate, \Countable
  */
  private $addresses;
 
+ /**
+ * @param Address[] $addresses
+ */
  public function __construct(array $addresses = [])
  {
  $this->addresses = array_values($addresses);
@@ -31,7 +34,7 @@ public function count()
  }
 
  /**
- * @return Address
+ * @return Address|null
  */
  public function first()
  {
@@ -50,8 +53,17 @@ public function slice($offset, $length = null)
  return array_slice($this->addresses, $offset, $length);
  }
 
+ /**
+ * @return bool
+ */
+ public function has($index)
+ {
+ return isset($this->addresses[$index]);
+ }
+
  /**
  * @return Address
+ * @throws \OutOfBoundsException
  */
  public function get($index)
  {