#Introduction This is the official PHP driver for the Mapbox API. It is crafted with artisanal skill from native hardwoods.

The PHP driver currently supports geocoding, reverse geocoding, and permanent geocoding APIs. Others follow.

#PHP Specifics ##Dependencies

• PHP >=5.1.2 is required.
• The php5-curl module is required.
• SPL is required for autoloading.
• JSON is required. Some distributions as of PHP 5.5rc2 lack the previously included JSON extension due to a license conflict. Use sudo apt-get install php5-json.

##Autoloading All classes are autoloaded. Just require_once("Mapbox.php") and you're laughing.

The PHP __autoload() method is deprecated; this library uses spl_autoload_register(). The Mapbox Autoload will not mess with other libraries or frameworks.

#Getting Started

Register with Mapbox for free access to most Mapbox services. Go to the API Token page to get or create an API token.

Run test.php on the command line:

'php test.php <yourMapboxToken> [logfile]'

On windows remember to use the -f switch:

'php -f test.php <yourMapboxToken> [logfile]'  

This checks your PHP install environment and performs a number of unit tests. The script takes your token as parameter one, and an optional output file as parameter two. By default the test echoes to stdout.

Require the file 'Mapbox.php, and instantiate a mapbox object with the token as parameter'

	//setup
	require_once('Mapbox.php');
	$mapbox = new Mapbox("<yourMapboxToken>");

The driver creates an authenticated handle to Mapbox and configures class loading on instantiation, so be sure to always instantiate a Mapbox object first.

(Remember, first create a Mapbox object as we've done above.)

    	//geocode
    	$address = "149 9th St, San Francisco, CA 94103";
    	$res = $mapbox->geocode($address);
    	//view results for debugging
	print_r($res->getData());

You can add the types and proximity parameters:

	//types
	$types = array('region','place');
	$res = $mapbox->geocode($address, $types);

or

	//proximity
	$proximity = array('longitude'=>-122,'latitude'=>37);
	$res = $mapbox->geocode($address, "", $proximity);

	//reverse geocode
	$longitude = -122;
	$latitude = 37;
	$res = $mapbox->reverseGeocode($longitude, $latitude);
   	//view results for debugging
	print_r($res->getData());

You can use the types parameter with reverse geocoding too, effectively giving you a form of point-in-polygon of different geography types:

	//types
	$types = array('postcode');
	$res = $mapbox->reverseGeocode($longitude, $latitude, $types);

Pro Tip: longitude always comes before latitude in parameter order, except when it doesn't.

Permanent Geocoding requires specific authentication from Mapbox, so it's a different method:

    	//permanent geocode
    	$address = "149 9th St, San Francisco, CA 94103";
    	$res = $mapbox->geocodePermanent($address);
    	//view results for debugging
	print_r($res->getData());

Unnecessary Reminder: we use print_r() in these examples so you can review the output visually. Obviously, but worth a reminder nonetheless, you do not want to use print_r() in production.

The response object is an iterator, so you can iterate on it directly:

	//iterate
	foreach ($res as $key => $value){
		//do something with each result
		print_r($value);
	}

You can also just get the results as an array:

	$results = $res->getData();
	print_r($results);

A boatload of tools are available in the driver to help you understand your request, and what the server is (or is not) returning. Putting the mapbox object in debug mode will dump a ton of metadata to stdout on each query:

	$mapbox->debug();

and a wealth of other metadata is available via the response object outside debug mode:

	//was the request successful?
	$success = $res->success();
	
	//get result count
	$count = $res->getCount();
	
	//get http status code: 200, 404, etc.
	$code = $res->getCode();
	
	//get server headers (including rate-limit information)
	$headers = $res->getHeaders();
	
	//get request metadata
	$request - $res->getInfo();
	
	//get attribution
	$attribution - $res->getAttribution();