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     private $_rdfurl;
  56
  57     var $names = array();
  58
  59     /**
  60      * Constructor that makes a Location from Notice::locationOptions(...)
  61      *
  62      * @param array $options    an array for example provided by Notice::locationOptions(...)
  63      *
  64      * @return Location Location with the given options (lat, lon, id, name)
  65      */
  66     static function fromOptions(array $options) {
  67         $location = new Location();
  68         foreach (['lat', 'lon', 'location_id', 'location_ns'] as $opt) {
  69             if (isset($options[$opt])) {
  70                 $location->$opt = $options[$opt];
  71             }
  72         }
  73         return $location;
  74     }
  75
  76     /**
  77      * Constructor that makes a Location from a string name
  78      *
  79      * @param string $name     Human-readable name (any kind)
  80      * @param string $language Language, default = common_language()
  81      *
  82      * @return Location Location with that name (or null if not found)
  83      */
  84
  85     static function fromName($name, $language=null)
  86     {
  87         if (is_null($language)) {
  88             $language = common_language();
  89         }
  90
  91         $location = null;
  92
  93         // Let a third-party handle it
  94
  95         Event::handle('LocationFromName', array($name, $language, &$location));
  96
  97         return $location;
  98     }
  99
 100     /**
 101      * Constructor that makes a Location from an ID
 102      *
 103      * @param integer $id       Identifier ID
 104      * @param integer $ns       Namespace of the identifier
 105      * @param string  $language Language to return name in (default is common)
 106      *
 107      * @return Location The location with this ID (or null if none)
 108      */
 109
 110     static function fromId($id, $ns, $language=null)
 111     {
 112         if (is_null($language)) {
 113             $language = common_language();
 114         }
 115
 116         $location = null;
 117
 118         // Let a third-party handle it
 119
 120         Event::handle('LocationFromId', array($id, $ns, $language, &$location));
 121
 122         return $location;
 123     }
 124
 125     /**
 126      * Constructor that finds the nearest location to a lat/lon pair
 127      *
 128      * @param float  $lat      Latitude
 129      * @param float  $lon      Longitude
 130      * @param string $language Language for results, default = current
 131      *
 132      * @return Location the location found, or null if none found
 133      */
 134
 135     static function fromLatLon($lat, $lon, $language=null)
 136     {
 137         if (is_null($language)) {
 138             $language = common_language();
 139         }
 140
 141         $location = null;
 142
 143         // Let a third-party handle it
 144
 145         if (Event::handle('LocationFromLatLon',
 146                           array($lat, $lon, $language, &$location))) {
 147             // Default is just the lat/lon pair
 148
 149             $location = new Location();
 150
 151             $location->lat = $lat;
 152             $location->lon = $lon;
 153         }
 154
 155         return $location;
 156     }
 157
 158     /**
 159      * Get the name for this location in the given language
 160      *
 161      * @param string $language language to use, default = current
 162      *
 163      * @return string location name or null if not found
 164      */
 165
 166     function getName($language=null)
 167     {
 168         if (is_null($language)) {
 169             $language = common_language();
 170         }
 171
 172         if (array_key_exists($language, $this->names)) {
 173             return $this->names[$language];
 174         } else {
 175             $name = null;
 176             Event::handle('LocationNameLanguage', array($this, $language, &$name));
 177             if (!empty($name)) {
 178                 $this->names[$language] = $name;
 179                 return $name;
 180             }
 181         }
 182     }
 183
 184     /**
 185      * Get an URL suitable for this location
 186      *
 187      * @return string URL for this location or NULL
 188      */
 189
 190     function getURL()
 191     {
 192         // Keep one cached
 193
 194         if (is_string($this->_url)) {
 195             return $this->_url;
 196         }
 197
 198         $url = null;
 199
 200         Event::handle('LocationUrl', array($this, &$url));
 201
 202         $this->_url = $url;
 203
 204         return $url;
 205     }
 206
 207     /**
 208      * Get an URL for this location, suitable for embedding in RDF
 209      *
 210      * @return string URL for this location or NULL
 211      */
 212
 213     function getRdfURL()
 214     {
 215         // Keep one cached
 216
 217         if (is_string($this->_rdfurl)) {
 218             return $this->_rdfurl;
 219         }
 220
 221         $url = null;
 222
 223         Event::handle('LocationRdfUrl', array($this, &$url));
 224
 225         $this->_rdfurl = $url;
 226
 227         return $url;
 228     }
 229 }