lib/location.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Class for locations
   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  Location
  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') && !defined('LACONICA')) {
  31     exit(1);
  32 }
  33
  34 /**
  35  * class for locations
  36  *
  37  * These are stored in the DB as part of notice and profile records,
  38  * but since they're about the same in both, we have a separate class
  39  * for them.
  40  *
  41  * @category Location
  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
  48 class Location
  49 {
  50     public  $lat;
  51     public  $lon;
  52     public  $location_id;
  53     public  $location_ns;
  54     private $_url;
  55
  56     var $names = array();
  57
  58     /**
  59      * Constructor that makes a Location from a string name
  60      *
  61      * @param string $name     Human-readable name (any kind)
  62      * @param string $language Language, default = common_language()
  63      *
  64      * @return Location Location with that name (or null if not found)
  65      */
  66
  67     static function fromName($name, $language=null)
  68     {
  69         if (is_null($language)) {
  70             $language = common_language();
  71         }
  72
  73         $location = null;
  74
  75         // Let a third-party handle it
  76
  77         Event::handle('LocationFromName', array($name, $language, &$location));
  78
  79         return $location;
  80     }
  81
  82     /**
  83      * Constructor that makes a Location from an ID
  84      *
  85      * @param integer $id       Identifier ID
  86      * @param integer $ns       Namespace of the identifier
  87      * @param string  $language Language to return name in (default is common)
  88      *
  89      * @return Location The location with this ID (or null if none)
  90      */
  91
  92     static function fromId($id, $ns, $language=null)
  93     {
  94         $location = null;
  95
  96         // Let a third-party handle it
  97
  98         Event::handle('LocationFromId', array($id, $ns, $language, &$location));
  99
 100         return $location;
 101     }
 102
 103     /**
 104      * Constructor that finds the nearest location to a lat/lon pair
 105      *
 106      * @param float  $lat      Latitude
 107      * @param float  $lon      Longitude
 108      * @param string $language Language for results, default = current
 109      *
 110      * @return Location the location found, or null if none found
 111      */
 112
 113     static function fromLatLon($lat, $lon, $language=null)
 114     {
 115         if (is_null($language)) {
 116             $language = common_language();
 117         }
 118
 119         $location = null;
 120
 121         // Let a third-party handle it
 122
 123         if (Event::handle('LocationFromLatLon',
 124                           array($lat, $lon, $language, &$location))) {
 125             // Default is just the lat/lon pair
 126
 127             $location = new Location();
 128
 129             $location->lat = $lat;
 130             $location->lon = $lon;
 131         }
 132
 133         return $location;
 134     }
 135
 136     /**
 137      * Get the name for this location in the given language
 138      *
 139      * @param string $language language to use, default = current
 140      *
 141      * @return string location name or null if not found
 142      */
 143
 144     function getName($language=null)
 145     {
 146         if (is_null($language)) {
 147             $language = common_language();
 148         }
 149
 150         if (array_key_exists($language, $this->names)) {
 151             return $this->names[$language];
 152         } else {
 153             $name = null;
 154             Event::handle('LocationNameLanguage', array($this, $language, &$name));
 155             if (!empty($name)) {
 156                 $this->names[$language] = $name;
 157                 return $name;
 158             }
 159         }
 160     }
 161
 162     /**
 163      * Get an URL suitable for this location
 164      *
 165      * @return string URL for this location or NULL
 166      */
 167
 168     function getURL()
 169     {
 170         if ($this->_url == false) { // cached failure
 171             return null;
 172         } else if (is_string($this->_url)) { // cached value
 173             return $this->_url;
 174         }
 175
 176         $url = null;
 177
 178         Event::handle('LocationUrl', array($this, &$url));
 179
 180         // Save it for later
 181
 182         if (is_null($url)) {
 183             $this->_url = false;
 184         } else {
 185             $this->_url = $url;
 186         }
 187
 188         return $this->_url;
 189     }
 190 }