common_memcache() => Cache::instance()
[statusnet-biz:statusnet-biz.git] / plugins / GeonamesPlugin.php
1 <?php
2 /**
3  * StatusNet, the distributed open-source microblogging tool
4  *
5  * Plugin to convert string locations to Geonames IDs and vice versa
6  *
7  * PHP version 5
8  *
9  * LICENCE: This program is free software: you can redistribute it and/or modify
10  * it under the terms of the GNU Affero General Public License as published by
11  * the Free Software Foundation, either version 3 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU Affero General Public License for more details.
18  *
19  * You should have received a copy of the GNU Affero General Public License
20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
21  *
22  * @category  Action
23  * @package   StatusNet
24  * @author    Evan Prodromou <evan@status.net>
25  * @copyright 2009 StatusNet Inc.
26  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
27  * @link      http://status.net/
28  */
29
30 if (!defined('STATUSNET')) {
31     exit(1);
32 }
33
34 /**
35  * Plugin to convert string locations to Geonames IDs and vice versa
36  *
37  * This handles most of the events that Location class emits. It uses
38  * the geonames.org Web service to convert names like 'Montreal, Quebec, Canada'
39  * into IDs and lat/lon pairs.
40  *
41  * @category Plugin
42  * @package  StatusNet
43  * @author   Evan Prodromou <evan@status.net>
44  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
45  * @link     http://status.net/
46  *
47  * @seeAlso  Location
48  */
49
50 class GeonamesPlugin extends Plugin
51 {
52     const LOCATION_NS = 1;
53
54     public $host     = 'ws.geonames.org';
55     public $username = null;
56     public $token    = null;
57     public $expiry   = 7776000; // 90-day expiry
58     public $timeout  = 2;       // Web service timeout in seconds.
59     public $timeoutWindow = 60; // Further lookups in this process will be disabled for N seconds after a timeout.
60     public $cachePrefix = null; // Optional shared memcache prefix override
61                                 // to share lookups between local instances.
62
63     protected $lastTimeout = null; // timestamp of last web service timeout
64
65     /**
66      * convert a name into a Location object
67      *
68      * @param string   $name      Name to convert
69      * @param string   $language  ISO code for anguage the name is in
70      * @param Location &$location Location object (may be null)
71      *
72      * @return boolean whether to continue (results in $location)
73      */
74
75     function onLocationFromName($name, $language, &$location)
76     {
77         $loc = $this->getCache(array('name' => $name,
78                                      'language' => $language));
79
80         if ($loc !== false) {
81             $location = $loc;
82             return false;
83         }
84
85         try {
86             $geonames = $this->getGeonames('search',
87                                            array('maxRows' => 1,
88                                                  'q' => $name,
89                                                  'lang' => $language,
90                                                  'type' => 'xml'));
91         } catch (Exception $e) {
92             $this->log(LOG_WARNING, "Error for $name: " . $e->getMessage());
93             return true;
94         }
95
96         if (count($geonames) == 0) {
97             // no results
98             $this->setCache(array('name' => $name,
99                                   'language' => $language),
100                             null);
101             return true;
102         }
103
104         $n = $geonames[0];
105
106         $location = new Location();
107
108         $location->lat              = $this->canonical($n->lat);
109         $location->lon              = $this->canonical($n->lng);
110         $location->names[$language] = (string)$n->name;
111         $location->location_id      = (string)$n->geonameId;
112         $location->location_ns      = self::LOCATION_NS;
113
114         $this->setCache(array('name' => $name,
115                               'language' => $language),
116                         $location);
117
118         // handled, don't continue processing!
119         return false;
120     }
121
122     /**
123      * convert an id into a Location object
124      *
125      * @param string   $id        Name to convert
126      * @param string   $ns        Name to convert
127      * @param string   $language  ISO code for language for results
128      * @param Location &$location Location object (may be null)
129      *
130      * @return boolean whether to continue (results in $location)
131      */
132
133     function onLocationFromId($id, $ns, $language, &$location)
134     {
135         if ($ns != self::LOCATION_NS) {
136             // It's not one of our IDs... keep processing
137             return true;
138         }
139
140         $loc = $this->getCache(array('id' => $id));
141
142         if ($loc !== false) {
143             $location = $loc;
144             return false;
145         }
146
147         try {
148             $geonames = $this->getGeonames('hierarchy',
149                                            array('geonameId' => $id,
150                                                  'lang' => $language));
151         } catch (Exception $e) {
152             $this->log(LOG_WARNING, "Error for ID $id: " . $e->getMessage());
153             return false;
154         }
155
156         $parts = array();
157
158         foreach ($geonames as $level) {
159             if (in_array($level->fcode, array('PCLI', 'ADM1', 'PPL'))) {
160                 $parts[] = (string)$level->name;
161             }
162         }
163
164         $last = $geonames[count($geonames)-1];
165
166         if (!in_array($level->fcode, array('PCLI', 'ADM1', 'PPL'))) {
167             $parts[] = (string)$last->name;
168         }
169
170         $location = new Location();
171
172         $location->location_id      = (string)$last->geonameId;
173         $location->location_ns      = self::LOCATION_NS;
174         $location->lat              = $this->canonical($last->lat);
175         $location->lon              = $this->canonical($last->lng);
176
177         $location->names[$language] = implode(', ', array_reverse($parts));
178
179         $this->setCache(array('id' => (string)$last->geonameId),
180                         $location);
181
182         // We're responsible for this namespace; nobody else
183         // can resolve it
184
185         return false;
186     }
187
188     /**
189      * convert a lat/lon pair into a Location object
190      *
191      * Given a lat/lon, we try to find a Location that's around
192      * it or nearby. We prefer populated places (cities, towns, villages).
193      *
194      * @param string   $lat       Latitude
195      * @param string   $lon       Longitude
196      * @param string   $language  ISO code for language for results
197      * @param Location &$location Location object (may be null)
198      *
199      * @return boolean whether to continue (results in $location)
200      */
201
202     function onLocationFromLatLon($lat, $lon, $language, &$location)
203     {
204         // Make sure they're canonical
205
206         $lat = $this->canonical($lat);
207         $lon = $this->canonical($lon);
208
209         $loc = $this->getCache(array('lat' => $lat,
210                                      'lon' => $lon));
211
212         if ($loc !== false) {
213             $location = $loc;
214             return false;
215         }
216
217         try {
218           $geonames = $this->getGeonames('findNearbyPlaceName',
219                                          array('lat' => $lat,
220                                                'lng' => $lon,
221                                                'lang' => $language));
222         } catch (Exception $e) {
223             $this->log(LOG_WARNING, "Error for coords $lat, $lon: " . $e->getMessage());
224             return true;
225         }
226
227         if (count($geonames) == 0) {
228             // no results
229             $this->setCache(array('lat' => $lat,
230                                   'lon' => $lon),
231                             null);
232             return true;
233         }
234
235         $n = $geonames[0];
236
237         $parts = array();
238
239         $location = new Location();
240
241         $parts[] = (string)$n->name;
242
243         if (!empty($n->adminName1)) {
244             $parts[] = (string)$n->adminName1;
245         }
246
247         if (!empty($n->countryName)) {
248             $parts[] = (string)$n->countryName;
249         }
250
251         $location->location_id = (string)$n->geonameId;
252         $location->location_ns = self::LOCATION_NS;
253         $location->lat         = $this->canonical($n->lat);
254         $location->lon         = $this->canonical($n->lng);
255
256         $location->names[$language] = implode(', ', $parts);
257
258         $this->setCache(array('lat' => $lat,
259                               'lon' => $lon),
260                         $location);
261
262         // Success! We handled it, so no further processing
263
264         return false;
265     }
266
267     /**
268      * Human-readable name for a location
269      *
270      * Given a location, we try to retrieve a human-readable name
271      * in the target language.
272      *
273      * @param Location $location Location to get the name for
274      * @param string   $language ISO code for language to find name in
275      * @param string   &$name    Place to put the name
276      *
277      * @return boolean whether to continue
278      */
279
280     function onLocationNameLanguage($location, $language, &$name)
281     {
282         if ($location->location_ns != self::LOCATION_NS) {
283             // It's not one of our IDs... keep processing
284             return true;
285         }
286
287         $id = $location->location_id;
288
289         $n = $this->getCache(array('id' => $id,
290                                    'language' => $language));
291
292         if ($n !== false) {
293             $name = $n;
294             return false;
295         }
296
297         try {
298             $geonames = $this->getGeonames('hierarchy',
299                                            array('geonameId' => $id,
300                                                  'lang' => $language));
301         } catch (Exception $e) {
302             $this->log(LOG_WARNING, "Error for ID $id: " . $e->getMessage());
303             return false;
304         }
305
306         if (count($geonames) == 0) {
307             $this->setCache(array('id' => $id,
308                                   'language' => $language),
309                             null);
310             return false;
311         }
312
313         $parts = array();
314
315         foreach ($geonames as $level) {
316             if (in_array($level->fcode, array('PCLI', 'ADM1', 'PPL'))) {
317                 $parts[] = (string)$level->name;
318             }
319         }
320
321         $last = $geonames[count($geonames)-1];
322
323         if (!in_array($level->fcode, array('PCLI', 'ADM1', 'PPL'))) {
324             $parts[] = (string)$last->name;
325         }
326
327         if (count($parts)) {
328             $name = implode(', ', array_reverse($parts));
329             $this->setCache(array('id' => $id,
330                                   'language' => $language),
331                             $name);
332         }
333
334         return false;
335     }
336
337     /**
338      * Human-readable URL for a location
339      *
340      * Given a location, we try to retrieve a geonames.org URL.
341      *
342      * @param Location $location Location to get the url for
343      * @param string   &$url     Place to put the url
344      *
345      * @return boolean whether to continue
346      */
347
348     function onLocationUrl($location, &$url)
349     {
350         if ($location->location_ns != self::LOCATION_NS) {
351             // It's not one of our IDs... keep processing
352             return true;
353         }
354
355         $url = 'http://www.geonames.org/' . $location->location_id;
356
357         // it's been filled, so don't process further.
358         return false;
359     }
360
361     /**
362      * Machine-readable name for a location
363      *
364      * Given a location, we try to retrieve a geonames.org URL.
365      *
366      * @param Location $location Location to get the url for
367      * @param string   &$url     Place to put the url
368      *
369      * @return boolean whether to continue
370      */
371
372     function onLocationRdfUrl($location, &$url)
373     {
374         if ($location->location_ns != self::LOCATION_NS) {
375             // It's not one of our IDs... keep processing
376             return true;
377         }
378
379         $url = 'http://sws.geonames.org/' . $location->location_id . '/';
380
381         // it's been filled, so don't process further.
382         return false;
383     }
384
385     function getCache($attrs)
386     {
387         $c = Cache::instance();
388
389         if (empty($c)) {
390             return null;
391         }
392
393         $key = $this->cacheKey($attrs);
394
395         $value = $c->get($key);
396
397         return $value;
398     }
399
400     function setCache($attrs, $loc)
401     {
402         $c = Cache::instance();
403
404         if (empty($c)) {
405             return null;
406         }
407
408         $key = $this->cacheKey($attrs);
409
410         $result = $c->set($key, $loc, 0, time() + $this->expiry);
411
412         return $result;
413     }
414
415     function cacheKey($attrs)
416     {
417         $key = 'geonames:' .
418                implode(',', array_keys($attrs)) . ':'.
419                common_keyize(implode(',', array_values($attrs)));
420         if ($this->cachePrefix) {
421             return $this->cachePrefix . ':' . $key;
422         } else {
423             return common_cache_key($key);
424         }
425     }
426
427     function wsUrl($method, $params)
428     {
429         if (!empty($this->username)) {
430             $params['username'] = $this->username;
431         }
432
433         if (!empty($this->token)) {
434             $params['token'] = $this->token;
435         }
436
437         $str = http_build_query($params, null, '&');
438
439         return 'http://'.$this->host.'/'.$method.'?'.$str;
440     }
441
442     function getGeonames($method, $params)
443     {
444         if ($this->lastTimeout && (time() - $this->lastTimeout < $this->timeoutWindow)) {
445             throw new Exception("skipping due to recent web service timeout");
446         }
447
448         $client = HTTPClient::start();
449         $client->setConfig('connect_timeout', $this->timeout);
450         $client->setConfig('timeout', $this->timeout);
451
452         try {
453             $result = $client->get($this->wsUrl($method, $params));
454         } catch (Exception $e) {
455             common_log(LOG_ERR, __METHOD__ . ": " . $e->getMessage());
456             $this->lastTimeout = time();
457             throw $e;
458         }
459
460         if (!$result->isOk()) {
461             throw new Exception("HTTP error code " . $result->getStatus());
462         }
463
464         $body = $result->getBody();
465
466         if (empty($body)) {
467             throw new Exception("Empty HTTP body in response");
468         }
469
470         // This will throw an exception if the XML is mal-formed
471
472         $document = new SimpleXMLElement($body);
473
474         // No children, usually no results
475
476         $children = $document->children();
477
478         if (count($children) == 0) {
479             return array();
480         }
481
482         if (isset($document->status)) {
483             throw new Exception("Error #".$document->status['value']." ('".$document->status['message']."')");
484         }
485
486         // Array of elements, >0 elements
487
488         return $document->geoname;
489     }
490
491     function onPluginVersion(&$versions)
492     {
493         $versions[] = array('name' => 'Geonames',
494                             'version' => STATUSNET_VERSION,
495                             'author' => 'Evan Prodromou',
496                             'homepage' => 'http://status.net/wiki/Plugin:Geonames',
497                             'rawdescription' =>
498                             _m('Uses <a href="http://geonames.org/">Geonames</a> service to get human-readable '.
499                                'names for locations based on user-provided lat/long pairs.'));
500         return true;
501     }
502
503     function canonical($coord)
504     {
505         $coord = rtrim($coord, "0");
506         $coord = rtrim($coord, ".");
507
508         return $coord;
509     }
510 }