Initial commit of files

README.md

@@ -0,0 +1,78 @@
+# Google maps geocoding wrapper for Silverstripe
+
+Provides a safe and simple wrapper for geocoding in PHP using the Silverstripe framework.
+
+Features:
+
+* Safe-detection and prevention of daily request limit excession. This should help avoid getting your IP
+blocked from Google once you hit your daily limit.
+
+* Caching of requests to prevent unnecessary API calls.
+
+## Credits and Authors
+
+ * Damian Mooyman - <https://github.com/tractorcow/silverstripe-geocoding>
+
+## Requirements
+
+ * SilverStripe 3 or above
+ * PHP 5.3
+
+## Installation Instructions
+
+Extract all files into the 'geocoding' folder under your Silverstripe root, or install using composer
+
+```bash
+composer require "tractorcow/silverstripe-geocoding": "3.0.*@dev"
+```
+
+## Usage
+
+```php
+
+// Instance is explicitly created here, but it's better to have this as an injected dependency
+$address = '123 Fake Street, Fakuranga, New Fakeland';
+$service = Injector::inst()->get('GeocodingService');
+$result = $service->geocode($address);
+
+if($result['Success']) {
+	$latitude = $result['Latitude'];
+	$longitude = $result['Longitude'];
+	echo "Found address at $latitude,$longitude";
+} else {
+	user_error("Could not geocode address: ".$result['Message'], E_USER_ERROR);
+}
+```
+
+## Need more help?
+
+Message or email me at [email protected] or, well, read the code!
+
+## License
+
+Copyright (c) 2013, Damian Mooyman
+All rights reserved.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+ * The name of Damian Mooyman may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

_config/config.yml

@@ -0,0 +1,10 @@
+---
+Name: geocoding
+---
+Injector:
+  GeocodingService:
+    class: CachedGeocodingService
+    constructor:
+      - %$BackendGeocodingService
+  BackendGeocodingService:
+    class: GeocodingService

code/CachedGeocodingService.php

@@ -0,0 +1,53 @@
+<?php
+
+/**
+ * @package geocoding
+ */
+class CachedGeocodingService implements IGeocodingService {
+
+	/**
+	 * @var IGeocodingService
+	 */
+	protected $backend = null;
+
+	function __construct(IGeocodingService $backend) {
+		$this->backend = $backend;
+	}
+
+	/**
+	 * Gets the cache object
+	 * 
+	 * @return Zend_Cache_Frontend
+	 */
+	protected function getCache() {
+		return SS_Cache::factory('GeocodingService');
+	}
+
+	public function geocode($address) {
+
+		// Generate unique key for address
+		$address = $this->normaliseAddress($address);
+		$addressKey = md5('CachedGeocodingService_' . $address);
+
+		// Check if cached
+		$result = unserialize($this->getCache()->load($addressKey));
+		if($result) return $result;
+
+		// generate result, and check if it's a cachable result
+		$result = $this->backend->geocode($address);
+		if($result['Cache']) {
+			$oneWeek = 3600 * 24 * 7;
+			$this->getCache()->save(serialize($result), $addressKey, array(), $oneWeek);
+		}
+		return $result;
+	}
+
+	public function isOverLimit() {
+		return $this->backend->isOverLimit();
+	}
+
+	public function normaliseAddress($address) {
+		return $this->backend->normaliseAddress($address);
+	}
+
+}

code/GeocodingService.php

@@ -0,0 +1,111 @@
+<?php
+
+/**
+ * @package geocoding
+ */
+class GeocodingService implements IGeocodingService {
+
+	/**
+	 * Gets the cache object
+	 * 
+	 * @return Zend_Cache_Frontend
+	 */
+	protected function getCache() {
+		return SS_Cache::factory('GeocodingService');
+	}
+
+	/**
+	 * Marks as over daily limit
+	 */
+	protected function markLimit() {
+		$this->getCache()->save(time(), 'dailyLimit', array(), null);
+	}
+
+	public function isOverLimit() {
+		$limit = $this->getCache()->load('dailyLimit');
+		if(empty($limit)) return false;
+
+		// It's ok if it's been 24 hours
+		return (time() - $limit) > (3600 * 24);
+	}
+
+	public function normaliseAddress($address) {
+		if(is_array($address)) {
+			$address = implode(', ', $address);
+		}
+        return trim(preg_replace('/\n+/', ', ', $address));
+	}
+
+	/**
+	 * Returns resulting geocode in the format
+	 * 
+	 * array(
+	 *    'Success' => true,
+	 *    'Latitude' => '0.000',
+	 *	  'Longitude' => '0.000',
+	 *	  'Error' => '', // error code (if error)
+	 *    'Message' => '', // error message (if error)
+	 *	  'Cache' => true // true if this result can be reproduced (cached)
+	 * )
+	 * 
+	 * Success and Cache are always required.
+	 * If success, Latitude and Longitude are required.
+	 * If failure, Error and Message are required.
+	 * 
+	 * @param string|array $address Address, or list of components
+	 * @return array Result
+	 */
+	public function geocode($address) {
+
+		// Don't attempt geocoding if over limit
+		if($this->isOverLimit()) {
+			return array(
+				'Success' => false,
+				'Error' => 'OVER_QUERY_LIMIT',
+				'Message' => 'Google geocoding service is over the daily limit. Please try again later.',
+				'Cache' => false // Don't cache broken results
+			);
+		}
+
+		// Geocode
+		$address = $this->normaliseAddress($address);
+        $requestURL = "http://maps.googleapis.com/maps/api/geocode/xml?sensor=false&address=" . urlencode($address);
+        $xml = simplexml_load_file($requestURL);
+
+		// Check if there is a result
+		if(empty($xml)) {
+			return array(
+				'Success' => false,
+				'Error' => 'UNKNOWN_ERROR',
+				'Message' => "Could not call google api at url $requestURL",
+				'Cache' => false // Retry later
+			);
+		}
+
+		// Check if result has specified error
+        $status = (string)$xml->status;
+        if (strcmp($status, "OK") != 0) {
+			// check if limit hasbeen breached
+			$cache = true;  // failed results should still be cacheable
+			if(strcmp($status, 'OVER_QUERY_LIMIT') == 0) {
+				$cache = false; // Don't cache over limit values
+				$this->markLimit();
+			}
+			return array(
+				'Success' => false,
+				'Error' => $status,
+				'Message' => "Google error code: $status at url $requestURL",
+				'Cache' => $cache
+			);
+		}
+
+        $coordinates = $xml->result->geometry->location;
+
+		return array(
+			'Success' => true,
+			'Latitude' => floatval($coordinates->lat),
+			'Longitude' => floatval($coordinates->lng),
+			'Cache' => true
+		);
+	}
+}

code/IGeocodingService.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * @package geocoding
+ */
+interface IGeocodingService {
+
+	/**
+	 * Is this service over the daily limit?
+	 * 
+	 * @return boolean
+	 */
+	public function isOverLimit();
+
+	/**
+	 * Returns resulting geocode in the format
+	 * 
+	 * array(
+	 *    'Success' => true,
+	 *    'Latitude' => '0.000',
+	 *	  'Longitude' => '0.000',
+	 *	  'Error' => '', // error code
+	 *    'Message' => '' // error message
+	 * )
+	 * 
+	 * @param string $address
+	 * @return array Result
+	 */
+	public function geocode($address);
+
+
+	/**
+	 * Cleans up an address for geocoding
+	 * 
+	 * @param string|array $address
+	 * @return string
+	 */
+	public function normaliseAddress($address);
+}

composer.json

@@ -0,0 +1,23 @@
+{
+	"name": "tractorcow/silverstripe-geocoding",
+	"description": "Google maps geocoding wrapper for Silverstripe",
+	"type": "silverstripe-module",
+	"keywords": ["silverstripe", "google", "maps", "geocoding", "geocode"],
+	"license": "BSD-3-Clause",
+	"authors": [
+		{
+			"name": "Damian Mooyman",
+			"email": "[email protected]"
+		}
+	],
+	"support": {
+		"issues": "http://github.com/tractorcow/silverstripe-geocoding/issues"
+	},
+	"require": {
+		"silverstripe/framework": "3.*",
+		"composer/installers": "*"
+	},
+	"extra": {
+		"installer-name": "geocoding"
+	}
+}