[#83] Resolve merge conflicts

readme.md

@@ -2,6 +2,69 @@
 
 This is a SkyVerge library module: a full featured WooCommerce Plugin Framework
 
+## Sample API Implementation
+
+The following is a sample basic REST API implementation using the API classes/interfaces provided by the framework. Comments are largely omitted for brevity:
+
+```php
+class WC_Acme_API extends SV_WC_API_Base {
+
+	/** the base API endpoint */
+	const API_ENDPOINT = 'https://api.acme.com';
+
+	/** @var string Acme API key */
+	private $api_key;
+
+	public function __construct( $api_key ) {
+
+		// set auth creds
+		$this->api_key = $api_key;
+
+		// set up the request defaults
+		$this->request_uri = self::API_ENDPOINT;
+		$this->set_request_content_type_header( 'application/x-www-form-urlencoded' );
+		$this->set_request_accept_header( 'application/json' );
+		$this->set_request_header( 'Authorization', 'Token ' . $this->api_key );
+
+		$this->response_handler = 'SV_WC_API_JSON_Response';
+	}
+
+	// get some API resource by name
+	public function get_product( $name ) {
+		return $this->perform_request( $this->get_new_request( array( 'method' => 'GET', 'path' => '/products', 'params' => array( 'name' => $name ) ) ) );
+	}
+
+	// create some API resource
+	public function create_product( $name, $sku ) {
+		return $this->perform_request( $this->get_new_request( array( 'method' => 'POST', 'path' => '/products', 'params' => array( 'name' => $name, 'sku' => $sku ) ) ) );
+	}
+
+	// handle non-200 responses
+	protected function do_pre_parse_response_validation() {
+		if ( 200 != $this->get_response_code() ) {
+			// need the parsed response, which we don't have access to yet
+			$response = $this->get_parsed_response( $this->get_raw_response_body() );
+			throw new SV_WC_API_Exception( $response->error->message );
+		}
+	}
+
+	protected function get_new_request( $args = array() ) {
+		return new SV_WC_API_REST_Request( $args['method'], $args['path'], $args['params'] );
+	}
+
+	protected function get_plugin() {
+		return wc_acme();
+	}
+
+}
+
+// usage
+$api = new WC_Acme_API( $secret_key );
+$api->create_product( 'widget', '122' );
+$product = $api->get_product( 'widget' );
+echo $product->sku;
+```
+
 ## Known Issues
 
 ### Subscriptions Authorize-only Renewal

woocommerce/api/class-sv-wc-api-base.php

@@ -53,7 +53,7 @@ abstract class SV_WC_API_Base {
 	protected $request_http_version = '1.0';
 
 	/** @var string request duration */
-	private $request_duration;
+	protected $request_duration;
 
 	/** @var object request */
 	protected $request;
@@ -149,7 +149,6 @@ protected function handle_response( $response ) {
 
 		// check for WP HTTP API specific errors (network timeout, etc)
 		if ( is_wp_error( $response ) ) {
-
 			throw new SV_WC_API_Exception( $response->get_error_message(), (int) $response->get_error_code() );
 		}
 
@@ -265,6 +264,7 @@ protected function broadcast_request() {
 	 * @since 1.0.0
 	 */
 	protected function reset_response() {
+
 		$this->response_code     = null;
 		$this->response_message  = null;
 		$this->response_headers  = null;
@@ -284,7 +284,8 @@ protected function reset_response() {
 	 * @return string
 	 */
 	protected function get_request_uri() {
-		return $this->request_uri;
+		// API base request URI + any request-specific path
+		return $this->request_uri . ( $this->get_request() ? $this->get_request()->get_path() : '' );
 	}
 
 
@@ -331,7 +332,8 @@ protected function get_request_args() {
 	 * @return string
 	 */
 	protected function get_request_method() {
-		return $this->request_method;
+		// if the request object specifies the method to use, use that, otherwise use the API default
+		return $this->get_request() && $this->get_request()->get_method() ? $this->get_request()->get_method() : $this->request_method;
 	}
 
 
@@ -522,13 +524,14 @@ protected function get_api_id() {
 	 *
 	 * Child classes must implement this to return an object that implements
 	 * \SV_WC_API_Request which should be used in the child class API methods
-	 * to build the request. This is then passed to self::perform_request()
+	 * to build the request. The returned SV_WC_API_Request should be passed
+	 * to self::perform_request() by your concrete API methods
 	 *
 	 * @since 2.2.0
-	 * @param string $type optional request type
+	 * @param array $args optional request arguments
 	 * @return \SV_WC_API_Request
 	 */
-	abstract protected function get_new_request( $type = null );
+	abstract protected function get_new_request( $args = array() );
 
 
 	/**
@@ -590,7 +593,7 @@ protected function set_request_content_type_header( $content_type ) {
 	 * Set the Accept request header
 	 *
 	 * @since 2.2.0
-	 * @param $type
+	 * @param string $type the request accept type
 	 */
 	protected function set_request_accept_header( $type ) {
 		$this->request_headers['accept'] = $type;

woocommerce/api/class-sv-wc-api-json-response.php

@@ -0,0 +1,104 @@
+<?php
+/**
+ * WooCommerce Plugin Framework
+ *
+ * This source file is subject to the GNU General Public License v3.0
+ * that is bundled with this package in the file license.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://www.gnu.org/licenses/gpl-3.0.html
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to [email protected] so we can send you a copy immediately.
+ *
+ * DISCLAIMER
+ *
+ * Do not edit or add to this file if you wish to upgrade the plugin to newer
+ * versions in the future. If you wish to customize the plugin for your
+ * needs please refer to http://www.skyverge.com
+ *
+ * @package   SkyVerge/WooCommerce/API/Response
+ * @author    SkyVerge
+ * @copyright Copyright (c) 2013-2015, SkyVerge, Inc.
+ * @license   http://www.gnu.org/licenses/gpl-3.0.html GNU General Public License v3.0
+ */
+
+if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly
+
+if ( ! class_exists( 'SV_WC_API_JSON_Response' ) ) :
+
+
+/**
+ * API JSON Base Response Class
+ *
+ * Useful for API's that return application/json responses
+ *
+ * @since 3.1.2-1
+ * @see SV_WC_API_Response
+ */
+class SV_WC_API_JSON_Response implements SV_WC_API_Response {
+
+
+	/** @var string string representation of this response */
+	protected $raw_response_json;
+
+	/** @var mixed decoded response data */
+	public $response_data;
+
+
+	/**
+	 * Build a response object from the raw response JSON
+	 *
+	 * @since 3.1.2-1
+	 * @param string $raw_response_json the raw response JSON
+	 */
+	public function __construct( $raw_response_json ) {
+		$this->raw_response_json = $raw_response_json;
+		$this->response_data     = json_decode( $raw_response_json );
+	}
+
+
+	/**
+	 * Magic accessor for response data attributes
+	 *
+	 * @since 3.1.2-1
+	 * @param string $name the attribute name to get
+	 * @return mixed the attribute value
+	 */
+	public function __get( $name ) {
+
+		// accessing the response_data object indirectly via attribute (useful when it's a class)
+		return isset( $this->response_data->$name ) ? $this->response_data->$name : null;
+	}
+
+
+	/**
+	 * Returns the string representation of this response
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Response::to_string()
+	 * @return string the raw response
+	 */
+	public function to_string() {
+
+		return $this->raw_response_json;
+	}
+
+
+	/**
+	 * Returns the string representation of this response with any and all
+	 * sensitive elements masked or removed
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Response::to_string_safe()
+	 * @return string response safe for logging/displaying
+	 */
+	public function to_string_safe() {
+
+		// no sensitive data to mask
+		return $this->to_string();
+	}
+
+
+}
+
+endif;

woocommerce/api/class-sv-wc-api-rest-request.php

@@ -0,0 +1,133 @@
+<?php
+/**
+ * WooCommerce Plugin Framework
+ *
+ * This source file is subject to the GNU General Public License v3.0
+ * that is bundled with this package in the file license.txt.
+ * It is also available through the world-wide-web at this URL:
+ * http://www.gnu.org/licenses/gpl-3.0.html
+ * If you did not receive a copy of the license and are unable to
+ * obtain it through the world-wide-web, please send an email
+ * to [email protected] so we can send you a copy immediately.
+ *
+ * DISCLAIMER
+ *
+ * Do not edit or add to this file if you wish to upgrade the plugin to newer
+ * versions in the future. If you wish to customize the plugin for your
+ * needs please refer to http://www.skyverge.com
+ *
+ * @package   SkyVerge/WooCommerce/API/Request
+ * @author    SkyVerge
+ * @copyright Copyright (c) 2013-2015, SkyVerge, Inc.
+ * @license   http://www.gnu.org/licenses/gpl-3.0.html GNU General Public License v3.0
+ */
+
+if ( ! defined( 'ABSPATH' ) ) exit; // Exit if accessed directly
+
+if ( ! class_exists( 'SV_WC_API_REST_Request' ) ) :
+
+
+/**
+ * Base REST API Request class
+ *
+ * @since 3.1.2-1
+ */
+class SV_WC_API_REST_Request implements SV_WC_API_Request {
+
+
+	/** @var string the request method, one of HEAD, GET, PUT, PATCH, POST, DELETE */
+	protected $method;
+
+	/** @var string the request path */
+	protected $path;
+
+	/** @var array the request parameters, if any */
+	protected $params;
+
+
+	/**
+	 * Construct REST request object
+	 *
+	 * @since 3.1.2-1
+	 * @param string $method the request method, one of HEAD, GET, PUT, PATCH, POST, DELETE
+	 * @param string $path optional request path
+	 * @param array $params optional associative array of request parameters
+	 */
+	public function __construct( $method, $path = '', $params = array() ) {
+		$this->method = $method;
+		$this->path   = $path;
+		$this->params = $params;
+	}
+
+
+	/** Getter Methods ******************************************************/
+
+
+	/**
+	 * Returns the method for this request: one of HEAD, GET, PUT, PATCH, POST, DELETE
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Request::get_method()
+	 * @return string the request method
+	 */
+	public function get_method() {
+		return $this->method;
+	}
+
+
+	/**
+	 * Returns the request path
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Request::get_path()
+	 * @return string the request path
+	 */
+	public function get_path() {
+		return $this->path;
+	}
+
+
+	/**
+	 * Returns the request params, if any
+	 *
+	 * @since 3.1.2-1
+	 * @return array the request params
+	 */
+	public function get_params() {
+		return $this->params;
+	}
+
+
+	/** API Helper Methods ******************************************************/
+
+
+	/**
+	 * Returns the string representation of this request
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Request::to_string()
+	 * @return string request
+	 */
+	public function to_string() {
+		// URL encode params
+		return build_query( $this->get_params() );
+	}
+
+
+	/**
+	 * Returns the string representation of this request with any and all
+	 * sensitive elements masked or removed
+	 *
+	 * @since 3.1.2-1
+	 * @see SV_WC_API_Request::to_string_safe()
+	 * @return string the request, safe for logging/displaying
+	 */
+	public function to_string_safe() {
+
+		return $this->to_string();
+	}
+
+
+}
+
+endif;