Creating interfaces to be more SOLID

CHANGELOG.md

@@ -1,6 +1,21 @@
 CHANGELOG
 =========
 
+### 4.0.0 (2016-xx-xx)
+
+* Added: Interface for `Geocoder\Model\AddressCollection` called `Geocoder\Collection`. Public APIs are updated to type hint for `Geocoder\GeocoderResult`.
+* Added: Interface for `Geocoder\Model\Address` called `Geocoder\Location`. Public APIs are updated to type hint for `Geocoder\Location`.
+* Changed: `Location::getCoordinates` will return null or a `Coordinates` object with coordinates data. It will never return `Coordinates` without data. 
+* Changed: `Location::getBounds` will return null or a `Bounds` object with coordinates data. It will never return `Bounds` without data. 
+* Removed: `AdminLevel::toString` in favor for `AdminLevel::__toString`.
+* Removed: `Country::toString` in favor for `Country::__toString`.
+* Removed: `Address::getCountryCode` in favor for `Address::getCountry()->getCode()`.
+* Removed: `Address::getLongitude` in favor for `Address::getCoordinates()->getLongitude()`.
+* Removed: `Address::getLatitude` in favor for `Address::getCoordinates()->getLatitude()`.
+* Removed: `Bounds::isDefined` as it is always defined. 
+
+
+
 ### 3.3.0 (2015-12-06)
 
 * Added: timezone field for `FreeGeoIp` provider

src/Geocoder/Assert.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Geocoder;
+
+class Assert
+{
+    /**
+     * @param float  $value
+     * @param string $message
+     */
+    public static function latitude($value, $message = '')
+    {
+        if (!is_double($value)) {
+            throw new \InvalidArgumentException(
+                sprintf($message ?: 'Expected a double. Got: %s', self::typeToString($value))
+            );
+        }
+
+        if ($value < -90 || $value > 90) {
+            throw new \InvalidArgumentException(
+                sprintf($message ?: 'Latitude should be between -90 and 90. Got: %s', $value)
+            );
+        }
+    }
+
+    /**
+     * @param float  $value
+     * @param string $message
+     */
+    public static function longitude($value, $message = '')
+    {
+        if (!is_double($value)) {
+            throw new \InvalidArgumentException(
+                sprintf($message ?: 'Expected a doable. Got: %s', self::typeToString($value))
+            );
+        }
+
+        if ($value < -180 || $value > 180) {
+            throw new \InvalidArgumentException(
+                sprintf($message ?: 'Latitude should be between -90 and 90. Got: %s', $value)
+            );
+        }
+    }
+
+    private static function typeToString($value)
+    {
+        return is_object($value) ? get_class($value) : gettype($value);
+    }
+
+}

src/Geocoder/Collection.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Geocoder;
+
+/**
+ * This is the interface that is always return from a Geocoder.
+ *
+ * @author William Durand <[email protected]>
+ * @author Tobias Nyholm <[email protected]>
+ */
+interface Collection extends \IteratorAggregate, \Countable
+{
+    /**
+     * @return Location
+     */
+    public function first();
+
+    /**
+     * @return Location[]
+     */
+    public function slice($offset, $length = null);
+
+    /**
+     * @return bool
+     */
+    public function has($index);
+
+    /**
+     * @return Location
+     * @throws \OutOfBoundsException
+     */
+    public function get($index);
+
+    /**
+     * @return Location[]
+     */
+    public function all();
+}

src/Geocoder/Dumper/Dumper.php

@@ -10,20 +10,20 @@
 
 namespace Geocoder\Dumper;
 
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author William Durand <[email protected]>
  */
 interface Dumper
 {
     /**
-     * Dumps an `Address` object as a string representation of
+     * Dumps an `Location` object as a string representation of
      * the implemented format.
      *
-     * @param Address $address
+     * @param Location $location
      *
      * @return string
      */
-    public function dump(Address $address);
+    public function dump(Location $location);
 }

src/Geocoder/Dumper/GeoJson.php

@@ -10,7 +10,7 @@
 
 namespace Geocoder\Dumper;
 
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author Jan Sorgalla <[email protected]>
@@ -20,9 +20,9 @@ class GeoJson implements Dumper
     /**
      * {@inheritDoc}
      */
-    public function dump(Address $address)
+    public function dump(Location $location)
     {
-        $properties = array_filter($address->toArray(), function ($value) {
+        $properties = array_filter($location->toArray(), function ($value) {
             return !empty($value);
         });
 
@@ -36,19 +36,24 @@ public function dump(Address $address)
             $properties = null;
         }
 
+        $lat = 0;
+        $lon = 0;
+        if (null !== $coordinates = $location->getCoordinates()) {
+            $lat = $coordinates->getLatitude();
+            $lon = $coordinates->getLongitude();
+        }
+
         $json = [
             'type' => 'Feature',
             'geometry' => [
                 'type'          => 'Point',
-                'coordinates'   => [ $address->getLongitude(), $address->getLatitude() ]
+                'coordinates'   => [$lon, $lat],
             ],
             'properties' => $properties,
         ];
 
-        if (null !== $bounds = $address->getBounds()) {
-            if ($bounds->isDefined()) {
-                $json['bounds'] = $bounds->toArray();
-            }
+        if (null !== $bounds = $location->getBounds()) {
+            $json['bounds'] = $bounds->toArray();
         }
 
         return json_encode($json);

src/Geocoder/Dumper/Gpx.php

@@ -11,19 +11,19 @@
 namespace Geocoder\Dumper;
 
 use Geocoder\Geocoder;
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author William Durand <[email protected]>
  */
 class Gpx implements Dumper
 {
     /**
-     * @param Address $address
+     * @param Location $location
      *
      * @return string
      */
-    public function dump(Address $address)
+    public function dump(Location $location)
     {
         $gpx = sprintf(<<<GPX
 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
@@ -37,23 +37,29 @@ public function dump(Address $address)
 GPX
         , Geocoder::VERSION);
 
-        if ($address->getBounds()->isDefined()) {
-            $bounds = $address->getBounds();
+        if (null !== $bounds = $location->getBounds()) {
             $gpx .= sprintf(<<<GPX
     <bounds minlat="%f" minlon="%f" maxlat="%f" maxlon="%f"/>
 
 GPX
             , $bounds->getWest(), $bounds->getSouth(), $bounds->getEast(), $bounds->getNorth());
         }
 
+        $lat = null;
+        $lon = null;
+        if (null !== $coordinates = $location->getCoordinates()) {
+            $lat = $coordinates->getLatitude();
+            $lon = $coordinates->getLongitude();
+        }
+
         $gpx .= sprintf(<<<GPX
     <wpt lat="%.7f" lon="%.7f">
         <name><![CDATA[%s]]></name>
         <type><![CDATA[Address]]></type>
     </wpt>
 
 GPX
-        , $address->getLatitude(), $address->getLongitude(), $this->formatName($address));
+        , $lat, $lon, $this->formatName($location));
 
         $gpx .= <<<GPX
 </gpx>
@@ -63,11 +69,11 @@ public function dump(Address $address)
     }
 
     /**
-     * @param Address $address
+     * @param Location $address
      *
      * @return string
      */
-    protected function formatName(Address $address)
+    protected function formatName(Location $address)
     {
         $name  = [];
         $array = $address->toArray();

src/Geocoder/Dumper/Kml.php

@@ -10,7 +10,7 @@
 
 namespace Geocoder\Dumper;
 
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author Jan Sorgalla <[email protected]>
@@ -20,9 +20,9 @@ class Kml extends Gpx implements Dumper
     /**
      * {@inheritDoc}
      */
-    public function dump(Address $address)
+    public function dump(Location $location)
     {
-        $name = $this->formatName($address);
+        $name = $this->formatName($location);
         $kml  = <<<KML
 <?xml version="1.0" encoding="UTF-8"?>
 <kml xmlns="http://www.opengis.net/kml/2.2">
@@ -38,6 +38,13 @@ public function dump(Address $address)
 </kml>
 KML;
 
-        return sprintf($kml, $name, $name, $address->getLongitude(), $address->getLatitude());
+        $lat = null;
+        $lon = null;
+        if (null !== $coordinates = $location->getCoordinates()) {
+            $lat = $coordinates->getLatitude();
+            $lon = $coordinates->getLongitude();
+        }
+
+        return sprintf($kml, $name, $name, $lon, $lat);
     }
 }

src/Geocoder/Dumper/Wkb.php

@@ -10,7 +10,7 @@
 
 namespace Geocoder\Dumper;
 
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author Jan Sorgalla <[email protected]>
@@ -20,8 +20,15 @@ class Wkb implements Dumper
     /**
      * {@inheritDoc}
      */
-    public function dump(Address $address)
+    public function dump(Location $location)
     {
-        return pack('cLdd', 1, 1, $address->getLongitude(), $address->getLatitude());
+        $lat = null;
+        $lon = null;
+        if (null !== $coordinates = $location->getCoordinates()) {
+            $lat = $coordinates->getLatitude();
+            $lon = $coordinates->getLongitude();
+        }
+
+        return pack('cLdd', 1, 1, $lon, $lat);
     }
 }

src/Geocoder/Dumper/Wkt.php

@@ -10,7 +10,7 @@
 
 namespace Geocoder\Dumper;
 
-use Geocoder\Model\Address;
+use Geocoder\Location;
 
 /**
  * @author Jan Sorgalla <[email protected]>
@@ -20,8 +20,15 @@ class Wkt implements Dumper
     /**
      * {@inheritDoc}
      */
-    public function dump(Address $address)
+    public function dump(Location $location)
     {
-        return sprintf('POINT(%F %F)', $address->getLongitude(), $address->getLatitude());
+        $lat = null;
+        $lon = null;
+        if (null !== $coordinates = $location->getCoordinates()) {
+            $lat = $coordinates->getLatitude();
+            $lon = $coordinates->getLongitude();
+        }
+
+        return sprintf('POINT(%F %F)', $lon, $lat);
     }
 }