Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Adding SDK

  • Loading branch information...
commit 0300f50c5bd96d77c3982e016d90ec4078c73f8f 1 parent ce7e01c
Ben Lobaugh authored
2  Pinnion-API-client-for-PHP/.gitignore
View
@@ -0,0 +1,2 @@
+tst.php
+.DS_Store
20 Pinnion-API-client-for-PHP/Pinnion.php
View
@@ -0,0 +1,20 @@
+<?php
+
+define( 'PINNION_API_USER', 'asdf' );
+define( 'PINNION_API_PASS', 'asdf' );
+define( 'PINNION_API_URL', 'http://dev.pinnion.com' );
+
+
+
+
+// API Endpoints
+define('PINNION_ENDPOINT_PINNION', '/ws/v1/pinnion');
+define('PINNION_ENDPOINT_CHANNEL', '/ws/v1/channel');
+define('PINNION_ENDPOINT_AUTH', '/ws/v1/auth');
+
+// Setup includes - this should be an autoloader soon
+require_once('PinnionExceptions.class.php');
+require_once('PinnionApiResponse.class.php');
+require_once('PinnionApiRequest.class.php');
+
+require_once('PinnionPinnions.class.php');
103 Pinnion-API-client-for-PHP/PinnionApiRequest.class.php
View
@@ -0,0 +1,103 @@
+<?php
+/**
+ * This object talkes to the Pinnion API. Results are all JSON
+ *
+ * @author Ben Lobaugh <ben@lobaugh.net>
+ * @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
120 Pinnion-API-client-for-PHP/PinnionApiResponse.class.php
View
@@ -0,0 +1,120 @@
+<?php
+/**
+ * This object manages the results from the Pinnion API calls inside the
+ * PinnionApiRequest object. Multiple PinnionApiResponses can be available at one
+ * time with responses.
+ *
+ * @author Ben Lobaugh <ben@lobaugh.net>
+ * @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
75 Pinnion-API-client-for-PHP/PinnionExceptions.class.php
View
@@ -0,0 +1,75 @@
+<?php
+/**
+ * Contains all of the exceptions for the Pinnion API Client
+ */
+
+
+
+/**
+ * Used when invalid parameters are passed to the API
+ */
+class PinnionInvalidParametersException extends Exception {
+ // Redefine the exception so message isn't optional
+ public function __construct( $RequiredParameters ) {
+ // some code
+ $message = "<p><b>A required parameter was not found.</b> Please view the list of parameters: " . implode(", ", $RequiredParameters) . "</p>";
+ // 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 = "<p><b>400 HTTP Error:</b> Error bad request to $Url<br/>Details: {$Response['details']}<br/>Problem: {$Response['problem']}</p>";
+
+ // 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 = "<p><b>401 HTTP Error:</b> Error not authorized. Please check your Pinnion API credentials</p>";
+
+ // 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 = "<p><b>500 HTTP Error:</b> Internal server error. The Pinnion servers are currently experiencing difficulty</p>";
+
+ // 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";
+ }
+}
21 Pinnion-API-client-for-PHP/PinnionPinnions.class.php
View
@@ -0,0 +1,21 @@
+<?php
+
+/**
+ * Client for the 'pinnions' grouping of the Pinnion API
+ *
+ * @link eventually this will link to docs
+ */
+class PinnionPinnions extends PinnionApiRequest {
+
+
+ /**
+ * Retrieves a listing of all pinnions belonging to a user
+ *
+ * @todo Implement filter as a parameter
+ * @return Array
+ */
+ public function listPinnions() {
+ $response = $this->get( PINNION_API_URL . PINNION_ENDPOINT_PINNION);
+ return $response->getResponse();
+ }
+} // end class
67 Pinnion-API-client-for-PHP/README.md
View
@@ -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.
+
Please sign in to comment.
Something went wrong with that request. Please try again.