'v5'); //versions for endpoint
protected $debug = false; //debug flag
protected $token; //access token
protected $curlTimeout = 0; //maximum number of seconds for the network function to execute (0 = no timeout)
protected $connectTimeout = 0; //maximum number of seconds to connect to the server (0 = no timeout)
protected $placeTypes = array('country','region','postcode','place','neighborhood','address','poi');
protected $permanentGeocodes = false; //changes geocding endpoint when flipped
/**
* Constructor. Creates authenticated access to Mapbox.
* @param string token your Mapbox token.
*/
public function __construct($token) {
//register autoloader
spl_autoload_register(array (
get_class(),
'MapboxAutoload'
));
$this->token = $token;
}
/** Gets token **/
public function getToken(){
return $this->token;
}
/**
* Sets version for endpoint
* @param string endpoint endpoint name e.g. 'geocoder'
* @param string endpoint version e.g. 'v4'
**/
public function setEndpointVersion($endpoint,$version) {
$this->versions[$endpoint] = $version;
}
/**
* Turns on debugging for output to stderr
*/
public function debug() {
$this->debug = true;
}
/**
* Change the base URL at which to contact Mapbox's API. This
* may be useful if you want to talk to a test or staging
* server withou changing config
* Example value: http://staging.api.v3.Mapbox.com/t/
* @param urlBase the base URL at which to contact Mapbox's API.
* @return void
*/
public function setHome($urlBase) {
$this->home = $urlBase;
}
protected function getGeocoderDataSet(){
if ($this->permanentGeocodes == true){
$dataSet = "mapbox.places-permanent";
} else {
$dataSet = "mapbox.places";
}
return $dataSet;
}
protected function urlForGeocode($query) {
return $this->home ."/geocoding/".$this->versions['geocoder']."/".$this->getGeocoderDataSet()."/" . urlencode($query).".json";
}
protected function urlForReverseGeocode($longitude, $latitude) {
return $this->home ."/geocoding/".$this->versions['geocoder']."/".$this->getGeocoderDataSet()."/" .$longitude.",".$latitude.".json";
}
/**
* Geocodes by returning a response containing the address nearest a given point.
* @param string query The unstructured address or place-name
* @param array types containing n of country, region, postcode, place, neighborhood, address, or poi
* @param array proximity with keys 'longitude' , 'latitude'
* @return the response of a geocode query against Mapbox.
*/
public function geocode($query, $types=array(), $proximity=array()) {
$params = array();
if (empty($query)){return null;}
$url = $this->urlForGeocode($query);
if (!empty($types)){
$params['types'] = $types;
}
if (!empty($proximity)){
$params['proximity'] = $proximity['longitude'].",".$proximity['latitude'];
}
$this->permanentGeocodes = false; //set by default to off
return new GeocodeResponse($this->request($url,"GET",$params));
}
/** Different endpoint for permanent geocodes **/
public function geocodePermanent($query, $types=array(), $proximity=array()) {
$this->permanentGeocodes = true;
return $this->geocode($query, $types=array(), $proximity=array());
}
/**
* Reverse geocodes by returning a response containing the resolved entities.
* @param obj point The point for which the nearest address is returned
* @param string tableName Optional. The tablenae to geocode against. Currently only 'places' is supported.
* @return the response of running a reverse geocode query for point against Mapbox.
*/
public function reverseGeocode($longitude, $latitude, $types=array()) {
$params = array();
$url = $this->urlForReverseGeocode($longitude, $latitude);
if (!empty($types)){
$params['types'] = $types;
}
return new GeocodeResponse($this->request($url,"GET",$params));
}
/**
* Sign the request, perform a curl request and return the results
*
* @param string $urlStr unsigned URL request
* @param string $requestMethod
* @param null $params
* @return array ex: array ('headers'=>array(), 'body'=>string)
* @throws MapboxApiException
*/
protected function request($urlStr, $requestMethod="GET", $params = null) {
//custom input headers
$curlOptions[CURLOPT_HTTPHEADER] = array ();
$curlOptions[CURLOPT_HTTPHEADER][] = "X-Mapbox-Lib: " . $this->driverVersion;
if ($requestMethod == "POST") {
$curlOptions[CURLOPT_HTTPHEADER][] = "Content-Type: " . "application/x-www-form-urlencoded";
}
//request curl returns server headers
$curlOptions[CURLOPT_RETURNTRANSFER] = 1;
$curlOptions[CURLOPT_HEADER] = 1;
//other curl options
$curlOptions[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout; //connection timeout
$curlOptions[CURLOPT_TIMEOUT] = $this->curlTimeout; //execution timeout
$curlOptions[CURLOPT_RETURNTRANSFER] = 1; //return contents on success
//format query parameters and append
$formattedParams = null;
if (count($params)>0){
foreach ($params as $key=>$value){
if (is_array($value)){
$keyVal[] = $key."=".implode(",",$value);
} else {
$keyVal[] = $key."=".$value;
}
}
$formattedParams .= implode("&",$keyVal);
}
//url formatting
if ($formattedParams){
$urlStr .= "?".$formattedParams;
$url = $urlStr."&access_token=".$this->token;
} else {
$url = $urlStr."?access_token=".$this->token;
}
//format cURL
$ch = curl_init($url);
foreach ($curlOptions as $key=>$value){
curl_setopt ($ch , $key, $value);
}
//init metadata
$info = array();
$info['request']['encoded'] = $urlStr;
$info['request']['unencoded'] = urldecode($urlStr);
$info['driver'] = $this->driverVersion;
$info['request']['method'] = $requestMethod;
//make request
try {
$callStart = microtime(true);
$result = curl_exec($ch);
$callEnd = microtime(true);
} catch (Exception $e) {
//catch client exception
$info['message'] = "Service exception. Client did not connect and returned '" . $e->getMessage() . "'";
$MapboxE = new MapboxApiException($info);
throw $MapboxE;
}
//add execution time
$info['request']['time'] = $callEnd - $callStart;
//extract Mapbox headers
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($result, 0, $headerSize);
$result = substr($result, $headerSize);
$headers = explode(PHP_EOL, $header);
$headers = array_filter($headers,"trim");
//extract curl info
$info['code'] = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($params) {
$info['request']['parameters'] = $params;
}
//catch server exception & load up on debug data
if ($info['code'] >= 400 | $this->debug) {
//get a boatload of debug data
$info['headers'] = $headers;
$info['curl'] = curl_getinfo($ch);
//write debug info to stderr if debug mode on
if ($this->debug) {
$info = array_filter($info); //remove empty elements for readability
file_put_contents('php://stderr', "Debug " . print_r($info, true));
}
//chuck exception with some helpful errors for the most common codes
if ($info['code'] >= 400){
switch ($info['code']) {
case 401:
$info['message'] = "401 Unauthorized; check your access token";
break;
case 403:
$info['message'] = "403 Verboten; you do not have access to this resource -- some endpoints require authorization from Mapbox";
break;
case 429:
$info['message'] = "429 Enhance your calm. Exceeding rate limits -- use this::debug to see server response headers";
break;
case 422:
$info['message'] = "422 Unprocessable Entity; check your parameter values, esp swapped lat/lons, because we all do this";
break;
default:
$info['message'] = "HTTP code ".$info['code'].": use this::debug to see server response headers";
break;
}
$MapboxE = new MapboxApiException($info);
throw $MapboxE;
}
}
//close curl
curl_close($ch);
//format
$res['info'] = $info;
$res['headers'] = $headers;
$res['body'] = $result;
return $res;
}
/**
* Autoloader for file dependencies
* Called by spl_autoload_register() to avoid conflicts with autoload() methods from other libs
*/
public static function mapboxAutoload($className) {
$filename = dirname(__FILE__) . "/" . $className . ".php";
// don't interfere with other classloaders
if (!file_exists($filename)) {
return;
}
include $filename;
}
/**
* Sets maximum number of seconds to connect to the server before bailing
* @param int secs timeout in seconds
*/
public function setConnectTimeout($secs){
$this->connectTimeout = $secs;
return $this;
}
/**
* Sets maximum number of seconds to the network function to execute
* @param int secs timeout in seconds
*/
public function setCurlTimeout($secs){
$this->curlTimeout = $secs;
return $this;
}
}
?>