From 0300f50c5bd96d77c3982e016d90ec4078c73f8f Mon Sep 17 00:00:00 2001 From: Ben Lobaugh Date: Mon, 5 Mar 2012 12:07:31 -0800 Subject: [PATCH] Adding SDK --- Pinnion-API-client-for-PHP/.gitignore | 2 + Pinnion-API-client-for-PHP/Pinnion.php | 20 +++ .../PinnionApiRequest.class.php | 103 +++++++++++++++ .../PinnionApiResponse.class.php | 120 ++++++++++++++++++ .../PinnionExceptions.class.php | 75 +++++++++++ .../PinnionPinnions.class.php | 21 +++ Pinnion-API-client-for-PHP/README.md | 67 ++++++++++ 7 files changed, 408 insertions(+) create mode 100755 Pinnion-API-client-for-PHP/.gitignore create mode 100755 Pinnion-API-client-for-PHP/Pinnion.php create mode 100755 Pinnion-API-client-for-PHP/PinnionApiRequest.class.php create mode 100755 Pinnion-API-client-for-PHP/PinnionApiResponse.class.php create mode 100755 Pinnion-API-client-for-PHP/PinnionExceptions.class.php create mode 100755 Pinnion-API-client-for-PHP/PinnionPinnions.class.php create mode 100755 Pinnion-API-client-for-PHP/README.md diff --git a/Pinnion-API-client-for-PHP/.gitignore b/Pinnion-API-client-for-PHP/.gitignore new file mode 100755 index 0000000..4e75313 --- /dev/null +++ b/Pinnion-API-client-for-PHP/.gitignore @@ -0,0 +1,2 @@ +tst.php +.DS_Store diff --git a/Pinnion-API-client-for-PHP/Pinnion.php b/Pinnion-API-client-for-PHP/Pinnion.php new file mode 100755 index 0000000..477cd2d --- /dev/null +++ b/Pinnion-API-client-for-PHP/Pinnion.php @@ -0,0 +1,20 @@ + + * @license Nothing yet + * @uses PinnionApiResponse + */ +class PinnionApiRequest { + + /** + * Username for HTTP Basic auth for API + * @var String + */ + private $mApiUser; + + /** + * Password for HTTP Basic auth for API + * @var type + */ + private $mApiPass; + + /** + * Sets up the Pinnion API Request object authentication parameters + * + * @param String $ApiUser + * @param String $ApiPass + */ + public function __construct($ApiUser, $ApiPass) { + $this->mApiUser = $ApiUser; + $this->mApiPass = $ApiPass; + } + + /** + * Performs the GET query against the specified endpoint + * + * @throws PinnionBadRequestException + * @throws PinnionUnauthorizedRequestException + * @throws PinnionInternalServerErrorException + * @param String $Url - Endpoint with URL paramters (for now) + * @return PinnionApiResponse + */ + public function get( $Url ) { + $options = array( + CURLOPT_RETURNTRANSFER => true, // return web page + // CURLOPT_HEADER => true, // don't return headers + CURLOPT_ENCODING => "", // handle all encodings + CURLOPT_USERAGENT => "Pinnion API client for PHP", // who am i + CURLOPT_AUTOREFERER => true, // set referer on redirect + CURLOPT_CONNECTTIMEOUT => 120, // timeout on connect + CURLOPT_TIMEOUT => 120, // timeout on response + CURLOPT_MAXREDIRS => 10, // stop after 10 redirects + CURLOPT_SSL_VERIFYHOST => '0', + CURLOPT_SSL_VERIFYHOST => '0', + ); + + $ch = curl_init( $Url ); + curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); + curl_setopt($ch, CURLOPT_USERPWD, $this->mApiUser . ":" . $this->mApiPass); + curl_setopt_array( $ch, $options ); + $content = curl_exec( $ch ); + $err = curl_errno( $ch ); + $errmsg = curl_error( $ch ); + $header = array(); + $header['http_code'] = curl_getinfo( $ch, CURLINFO_HTTP_CODE ); + curl_close( $ch ); + + $header['errno'] = $err; + $header['errmsg'] = $errmsg; + $header['content'] = $content; + //die(print_r($header)); + + $response = new PinnionApiResponse(); + $response->setHttpCode( $header['http_code'] ); + $response->setResponse( $header['content'] ); + + if( $response->getHttpCode() == '400' ) { + // 400 Bad request when there was a problem with the request + throw new PinnionBadRequestException($Url, $response); + } else if ( $response->getHttpCode() == '401' ) { + // 401 Unauthorized when you don't provide a valid key + throw new PinnionUnauthorizedRequestException(); + } else if ( $response->getHttpCode() == '500' ) { + // 500 Internal Server Error + throw new PinnionInternalServerErrorException(); + } + return $response; + } + + public function post() { + throw new Exception( 'POST method not yet implemented' ); + } + public function put() { + throw new Exception( 'PUT method not yet implemented' ); + } + public function head() { + throw new Exception( 'HEAD method not yet implemented' ); + } + public function delete() { + throw new Exception( 'DELETE method not yet implemented' ); + } + +} // end class diff --git a/Pinnion-API-client-for-PHP/PinnionApiResponse.class.php b/Pinnion-API-client-for-PHP/PinnionApiResponse.class.php new file mode 100755 index 0000000..5073c11 --- /dev/null +++ b/Pinnion-API-client-for-PHP/PinnionApiResponse.class.php @@ -0,0 +1,120 @@ + + * @license Nothing yet + */ +class PinnionApiResponse implements ArrayAccess, Iterator{ + + private $mHttpCode; + + private $mResponse; + + private $mError = false; + + + + /** + * Sets the HTTP response code from the API call + * @param Integer $Code + */ + public function setHttpCode( $Code ) { + $this->mHttpCode = $Code; + + // If the response was not a 200 there was an error. Set the error code + if( '200' != $Code ) { + $this->mError = true; + } + } + + /** + * Returns the HTTP response code from the API query + * @return Integer + */ + public function getHttpCode() { + return $this->mHttpCode; + } + + /** + * Brings in the response from the API call and converts it to a stdClass + * + * @param JSON $Response + */ + public function setResponse($Response) { + $this->mResponse = json_decode($Response, true); + //dBug($this->mResponse); + } + + public function getResponse() { + return $this->mResponse; + } + + /** + * Check if there was an error with the API query + * + * @return Boolean + */ + public function isError() { + return $this->mError; + } + + + /* + * ************************************************************************ + * Below this point are overloaded PHP functions to enable arraylike access + * You should not need to change anything beyond this line + * ************************************************************************ + */ + + /* + * Array Access methods + * Used directly from PHP docs + * http://php.net/manual/en/class.arrayaccess.php + */ + public function offsetSet($offset, $value) { + if (is_null($offset)) { + $this->mResponse[] = $value; + } else { + $this->mResponse[$offset] = $value; + } + } + public function offsetExists($offset) { + return isset($this->mResponse[$offset]); + } + public function offsetUnset($offset) { + unset($this->mResponse[$offset]); + } + public function offsetGet($offset) { + return isset($this->mResponse[$offset]) ? $this->mResponse[$offset] : null; + } + + /* + * Iterator methods + * Used directly from PHP docs + * http://php.net/manual/en/language.oop5.iterations.php + */ + public function rewind() { + reset($this->mResponse); + } + + public function current() { + return current($this->mResponse); + } + + public function key() { + return key($this->mResponse); + } + + public function next() { + return next($this->mResponse); + } + + public function valid() { + $key = key($this->mResponse); + return ($key !== NULL && $key !== FALSE); + } + +} // end class \ No newline at end of file diff --git a/Pinnion-API-client-for-PHP/PinnionExceptions.class.php b/Pinnion-API-client-for-PHP/PinnionExceptions.class.php new file mode 100755 index 0000000..c0a7dc3 --- /dev/null +++ b/Pinnion-API-client-for-PHP/PinnionExceptions.class.php @@ -0,0 +1,75 @@ +A required parameter was not found. Please view the list of parameters: " . implode(", ", $RequiredParameters) . "

"; + // make sure everything is assigned properly + parent::__construct( $message, E_USER_ERROR, null ); + } + + // custom string representation of object + public function __toString() { + return __CLASS__ . ": {$this->message}\n"; + } +} + +// 400 Bad request when there was a problem with the request +class PinnionBadRequestException extends Exception { + // Redefine the exception so message isn't optional + public function __construct($Url, $Response) { + // some code + $message = "

400 HTTP Error: Error bad request to $Url
Details: {$Response['details']}
Problem: {$Response['problem']}

"; + + // make sure everything is assigned properly + parent::__construct($message, E_USER_ERROR, null); + } + + // custom string representation of object + public function __toString() { + return __CLASS__ . ": {$this->message}\n"; + } +} + +// 401 +class PinnionUnauthorizedRequestException extends Exception { + // Redefine the exception so message isn't optional + public function __construct() { + // some code + $message = "

401 HTTP Error: Error not authorized. Please check your Pinnion API credentials

"; + + // make sure everything is assigned properly + parent::__construct($message, E_USER_ERROR, null); + } + + // custom string representation of object + public function __toString() { + return __CLASS__ . ": {$this->message}\n"; + } +} + +// 500 +class PinnionInternalServerErrorException extends Exception { + // Redefine the exception so message isn't optional + public function __construct() { + // some code + $message = "

500 HTTP Error: Internal server error. The Pinnion servers are currently experiencing difficulty

"; + + // make sure everything is assigned properly + parent::__construct($message, E_USER_ERROR, null); + } + + // custom string representation of object + public function __toString() { + return __CLASS__ . ": {$this->message}\n"; + } +} \ No newline at end of file diff --git a/Pinnion-API-client-for-PHP/PinnionPinnions.class.php b/Pinnion-API-client-for-PHP/PinnionPinnions.class.php new file mode 100755 index 0000000..beff6df --- /dev/null +++ b/Pinnion-API-client-for-PHP/PinnionPinnions.class.php @@ -0,0 +1,21 @@ +get( PINNION_API_URL . PINNION_ENDPOINT_PINNION); + return $response->getResponse(); + } +} // end class \ No newline at end of file diff --git a/Pinnion-API-client-for-PHP/README.md b/Pinnion-API-client-for-PHP/README.md new file mode 100755 index 0000000..198a7f8 --- /dev/null +++ b/Pinnion-API-client-for-PHP/README.md @@ -0,0 +1,67 @@ +# Pinnion API client for PHP +"Pinnion (http://pinnion.com) is a secure way to interact with your audience through Q&A-based communication featuring the most free questions and responses for your surveys, quizzes, and polls. You can send Pinnions out through email or Twitter and we’re the only provider that offers apps for iPhone/iPad, Android, and Windows Phone 7, along with a WordPress plug‐in. + +Simply put, Pinnion is the only online provider that offers free surveys, free online polls, and audience response capabilities for WordPress, iPhone/iPad, and Android." +- From http://www.pinnion.com/what-is-pinnion/ + +This set of libraries allows developers to quickly and easily tap into the Pinnion API resources. + + + +*NOTE:* This project currently only supports GET requests to the Pinnion API + +## Supported endpoints + + +# Documentation +Full documentation can be found on the Github project wiki at https://github.com/blobaugh/Pinnion-API-client-for-PHP/wiki + +# How to setup the library +- Download the files from Github and place them in the PHP application directory +- * I.E. /var/www/myapp/Pinnion-API-client-for-PHP +- Include the Pinnion.php file in your application +- * I.E. In /var/www/myapp/index.php +- * Use require_once('Pinnion-API-client-for-PHP/Pinnion.php'); +- Edit Pinnion.php and set your Pinnion API credentials +- Begin using the new Pinnion functionality in your application! + +# Using the pre-built endpoint classes +The Pinnion API client for PHP allows developers to make direct calls to the Pinnion API, however for convenience several helper classes have been created. +Each class corresponds directly to a grouping of endpoints from the Pinnion API documentation. + +Example: Listing all Pinnions + +$p = new PinnionPinnions( 'username', 'password' ); +$pinnions = $p->listPinnions(); + +$pinnions will be in the form of an associative array + + +# Direct queries to the Pinnion API +The Pinnion API client for PHP supports direct API queries if a helper class is not available. +Queries are sent to the PinnionApiRequest class and data recieved from the Pinnion API will be returned in the PinnionApiResponse class. +The PinnionApiResponse object will contain the HTTP code and API response. To use the PinnionApiReponse class a developer simply calls the query method with an endpoint and parameters. + +Example: Accessing all Pinnions + +$p = new PinnionApiRequest(); +$pinnions = $p->get( PINNION_API_URL . PINNION_ENDPOINT_PINNION ); + +$pinnions will be a PinnionApiResponse object that can be access like an array (E.G. $pinnions['results']) or used in a loop to view each event entry (E.G. foreach( $pinnions AS $pinnion ) ) +The HTTP response code can be checked with $pinnions->getHttpCode() + +# Exceptions +Exceptions will usually occur when an invalid API request is recieved. The following is a list of all the Pinnion API client for PHP specific exceptions + +- PinnionInvalidParametersException - Invalid or missing parameters passed to the API endpoint +- PinnionBadRequestException - Problem with the request +- PinnionUnauthorizedRequestException - Invalid API authorization +- PinnionInternalServerErrorException - Problem exists with the Pinnion API server + +# Development Roadmap + +- POST support +- support for more endpoints + +If you would like to see specific new developments please feel free to contribute through code or financial incentives. +