open311-helper-classes.php

<?php

/**
 * 
 * Copyright 2009 Mark J. Headd
 * http://www.voiceingov.org
 * 
 * A set of PHP classes for working with the Open311 API (http://open311.org/)
 *
 */

// The base class for Open311 API calls.
class APIBaseClass {
 
	// API base URL
	protected $base_url;
	 
	// CURL handle
	protected $ch;
	 
	// API return info
	public $output;
	public $info;
	 
	protected function __construct($base_url) {
		$this->base_url = $base_url;
		$this->ch = curl_init();
	}
	 
	public function logResults($logFile, $message) {
		$loghandle = fopen($logFile, 'a');
		fwrite($loghandle, date("F j, Y, g:i a").": API response from ".$this->base_url." = ".$message."\n");
		fclose($loghandle);
	}
	 
	protected function __destruct() {
		curl_close($this->ch);
	}
}

// The main Open311 class.
class Open311 extends APIBaseClass {

	private $api_url;
	private $method_name;
	private $api_key;
	private $city_id;
	private $service_code;
	private $lat;
	private $lon;
	private $address_string;
	private $customer_email;
	private $device_id;
	private $account_id;
	private $first_name;
	private $last_name;
	private $phone_number;
	private $description;
	private $media_url;
	private $service_request_id;
	
	/**
	 * Open311 Class Constructor.
	 * @param $base_url
	 * @param $api_key
	 * @param $city_id
	 */
	public function __construct($base_url, $api_key, $city_id) {
		$this->api_key = $api_key;
		$this->city_id = $city_id;
		parent::__construct($base_url);
	}
	
	/**
	 * Get a list of 311 Service Types.
	 * @return unknown_type
	 */
	public function selectService(){
		
		// Set URL for API method.
		$this->method_name = 'selectService';
		
		// Make the HTTP request to the API.
		$this->makeAPIRequest();
		
	}
	
	/**
	 * Create a new 311 Service Request.
	 * @param $service_code
	 * @param $lat
	 * @param $lon
	 * @param $address_string
	 * @param $customer_email
	 * @param $device_id
	 * @param $account_id
	 * @param $first_name
	 * @param $last_name
	 * @param $phone_number
	 * @param $description
	 * @param $media_url
	 */
	public function createRequest($service_code, $lat=NULL, $lon=NULL, $address_string=NULL, $customer_email=NULL, $device_id=NULL, 
				      $account_id=NULL, $first_name=NULL, $last_name=NULL, $phone_number=NULL, $description=NULL, 
                                      $media_url=NULL) {
		
		$this->service_code = $service_code;
		$this->lat = $lat;
		$this->lon = $lon;
		$this->address_string = $address_string;
		$this->customer_email = $customer_email;
		$this->device_id = $device_id;
		$this->account_id = $account_id;
		$this->first_name = $first_name;
		$this->last_name = $last_name;
		$this->phone_number = $phone_number;
		$this->description = $description;
		$this->media_url = $media_url;
		
		if((!isset($lat) && !isset($lon)) && strlen($address_string) == 0) {
			throw new CreateRequestException('Must submit lat/lon or address string with create service request.');
		}
		
		// Set URL for API method.
		$this->method_name = 'createRequest';
		
		// Make the HTTP request to the API.
		$this->makeAPIRequest();
	}
	
	/**
	 * Get the status of a specific 311 Service Request.
	 * @param $service_request_id
	 */
	public function statusUpdate($service_request_id) {
		
		$this->service_request_id = $service_request_id;
		
		// Set URL for API method.
		$this->method_name = 'statusUpdate';
		
		// Make the HTTP request to the API.
		$this->makeAPIRequest();
	}
	
	/**
	 * Helper method to make the cURL request to the Open 311 API.
	 */
	private function makeAPIRequest() {
		
		$request_url = $this->base_url.'?method='.$this->method_name.'&api_key='.$this->api_key.'&city_id='.$this->city_id;
		
		switch($this->method_name) {
			
			case 'selectService':				
				curl_setopt($this->ch, CURLOPT_URL, $request_url);
				curl_setopt($this->ch, CURLOPT_RETURNTRANSFER, true);
				break;

			case 'createRequest':
				$post_data = array('service_code' => $this->service_code, 'lat' => $this->lat, 'lon' => $this->lon, 
						   'address_string' => $this->address_string, 'customer_email' => $this->customer_email, 
						   'device_id' => $this->device_id, 'account_id' => $this->account_id, 
						   'first_name' => $this->first_name, 'last_name' => $this->last_name, 
						   'phone_number' => $this->phone_number, 'description' => $this->description, 
						   'media_url' => $this->media_url);
				
				curl_setopt($this->ch, CURLOPT_URL, $request_url);
				curl_setopt($this->ch, CURLOPT_POST, 1);
				curl_setopt($this->ch, CURLOPT_POSTFIELDS, $post_data);
				curl_setopt($this->ch, CURLOPT_RETURNTRANSFER, true);
				break;
				
			case 'statusUpdate':
				$request_url .= '&service_request_id='.$this->service_request_id;
				curl_setopt($this->ch, CURLOPT_URL, $request_url);
				curl_setopt($this->ch, CURLOPT_RETURNTRANSFER, true);
				break;
		}
		
			$this->output = curl_exec($this->ch);
			$this->info = curl_getinfo($this->ch);		
	}

	/**
	 * Open311 Class Destructor.
	 */
	public function __destruct() {
		parent::__destruct();
	}
}

/**
 * A class for 311 Service Types.
 *
 */
class ServiceType {
	
	private $service_code;
	private $service_name;
	private $service_description;
	
	public function __construct($service_code, $service_name, $service_description) {
		$this->service_code = $service_code;
		$this->service_name = $service_name;
		$this->service_description = $service_description;
	}
}

/**
 * A class for Service List Exceptions.
 *
 */
class ServiceListException extends Exception {}

/**
 * A class for Service Creation Exceptions.
 *
 */
class CreateRequestException extends Exception {}

/**
 * A class for Status Update Exceptions.
 *
 */
class StatusUpdateException extends Exception {}

?>

open311-sample-tests.php

<?php

/**
 * A set of simple tests for the Open311 API classes
 */

// Include the Open 311 helper classes.
include('open311-helper-classes.php');

// Variables used in method calls.
$base_url = ''; // Set this to the URL of the testHarness.php file.
$api_key = 'asdgt235-Xcsfw3-xsgSG125-nmk990';
$city_id = 'sfgov.org';
$service_code = '021';
$lat;
$lon;
$address_string = '123 Main Street, San Francisco, CA 12345';
$address_string;
$customer_email;
$device_id;
$account_id;
$first_name;
$last_name;
$phone_number;
$description;
$media_url;
$service_request_id = '293735';

// Uncomment different sections to test Open 311 method calls.
try {

	// Create a new instance of the Open 311 class.
	$open311 = new Open311($base_url, $api_key, $city_id);
	
	/*
	 * Select a list of service types and descriptions.
	 */	
//	$open311->selectService();
//	$serviceTypesXML = new SimpleXMLElement($open311->output);
//	foreach ($serviceTypesXML->Open311ServiceList->service as $service) {
//		echo $service['service_code'].": ".$service['service_name'].": ".$service['service_description']."<br />";
//	}
	
	
	/*
	 * Create a service request and get the service request ID.
	 */	
//	$open311->createRequest($service_code, $address_string);
//	$serviceRequestXML = new SimpleXMLElement($open311->output);
//	echo $serviceRequestXML->Open311Create->service_request_id;
	
	
	/*
	 * Check the status of a service request.
	 */	
	$open311->statusUpdate($service_request_id);
	$statusUpdateXML = new SimpleXMLElement($open311->output);
	echo "Status: ".$statusUpdateXML->Open311Status->status;
}

catch (CreateRequestException $ex) {
	die("ERROR: ".$ex->getMessage());
}

catch (Exception $ex) {
	die("Sorry, a problem occured: ".$ex->getMessage());
}


?>

open311-test-harness.php

<?php

/**
 * A simple test harness to excersize the Open 311 helper classes.
 * This file simple writes out the XML response structures provided
 *  on the Open 311 API Wiki page: http://wiki.open311.org/San_Francisco#SF_Open_311_API
 */

error_reporting(0);

$methodName = $_REQUEST['method'];

switch($methodName) {
	
	case 'selectService':
		$xml = simplexml_load_file('ServiceResponse.xml');
		break;
		
	case 'createRequest':
		$xml = simplexml_load_file('CreateResponse.xml');
		break;
		
	case 'statusUpdate':
		$xml = simplexml_load_file('StatusResponse.xml');
		break;

	default:
		die("You must supply a valid methodName parameter.");
}

header('Content-type: application/xml');
echo $xml->asXML(); 

?>