Merge pull request #25 from CPIGroup/master

Ready for next update version

Author: carl689

INSTALL.md

@@ -2,22 +2,52 @@
 To install, simply add the library to your project. Composer is the default installation tool for this library.
 If you do not use Composer for your project, you can still auto-load classes by  including the file **includes/classes.php** in the page or function.
 
-Before you use any commands,  you need to create a **amazon-config.php** file with your account credentials. Start by copying the template provided (*amazon-config.default.php*) and renaming the file.
+Before you use any commands,  you need to create an **amazon-config.php** file with your account credentials. Start by copying the template provided (*amazon-config.default.php*) and renaming the file.
 
-Only the first section of the config file needs to be filled out. If you are operating outside of the United States, be sure to change the Amazon Service URL as well. Everything after that point is pertaining to Amazon's API. Be sure to keep these values up to date, as Amazon could change them in a new API version release.
+If you are operating outside of the United States, be sure to change the Amazon Service URL to the one matching your region.
 
-You can also link the built-in logging system to your own logging system by putting the function name in the *$logfunction* parameter.
+You can also link the built-in logging system to your own system by putting the logging function's name in the *$logfunction* parameter.
 
-In the event that PHP does not have the correct permissions to create a file in the library's main directory, you will have to create the log file as "log.txt" and give all users permission to edit it.
+The default location for the built-in log file is in the library's main directory. In the event that PHP does not have the correct permissions to create a file in there, you will have to create the log file as "log.txt" and give PHP permission to edit it.
 
-## Example Usage
+## Usage
+All of the technical details required by the API are handled behind the scenes,
+so users can easily build code for sending requests to Amazon
+without having to jump hurdles such as parameter URL formatting and token management. 
 The general work flow for using one of the objects is this:
+
 1. Create an object for the task you need to perform.
 2. Load it up with parameters, depending on the object, using *set____* methods.
 3. Submit the request to Amazon. The methods to do this are usually named *fetch____* or *submit____* and have no parameters.
 4. Reference the returned data, whether as single values or in bulk, using *get____* methods.
-5. Monitor the performance of the library using built-in logging system.
+5. Monitor the performance of the library using the built-in logging system.
 
 Note that if you want to act on more than one Amazon store, you will need a separate object for each store.
 
 Also note that the objects perform best when they are not treated as reusable. Otherwise, you may end up grabbing old response data if a new request fails.
+
+## Examples
+Here is an example of a function used to get all warehouse-fulfilled orders from Amazon updated in the past 24 hours:
+```php
+function getAmazonOrders() {
+    $amz = new AmazonOrderList("myStore"); //store name matches the array key in the config file
+    $amz->setLimits('Modified', "- 24 hours");
+    $amz->setFulfillmentChannelFilter("MFN"); //no Amazon-fulfilled orders
+    $amz->setOrderStatusFilter(
+        array("Unshipped", "PartiallyShipped", "Canceled", "Unfulfillable")
+        ); //no shipped or pending
+    $amz->setUseToken(); //Amazon sends orders 100 at a time, but we want them all
+    $amz->fetchOrders();
+    return $amz->getList();
+}
+```
+This example shows a function used to send a previously-created XML feed to Amazon to update Inventory numbers:
+```php
+function sendInventoryFeed($feed) {
+    $amz=new AmazonFeed("myStore"); //store name matches the array key in the config file
+    $amz->setFeedType("_POST_INVENTORY_AVAILABILITY_DATA_"); //feed types listed in documentation
+    $amz->setFeedContent($feed);
+    $amz->submitFeed();
+    return $amz->getResponse();
+}
+```

README.md

@@ -1,4 +1,38 @@
 phpAmazonMWS
 ============
 
-A library to connect to Amazon's MWS web services in an object-oriented manner, with a focus on intuitive usage.
+A library to connect to Amazon's Merchant Web Services (MWS) in an object-oriented manner, with a focus on intuitive usage.  
+
+This is __NOT__ for Amazon Web Services (AWS) - Cloud Computing Services.
+
+
+## Example Usage
+Here are a couple of examples of the library in use.
+All of the technical details required by the API are handled behind the scenes,
+so users can easily build code for sending requests to Amazon
+without having to jump hurdles such as parameter URL formatting and token management. 
+
+Here is an example of a function used to get all warehouse-fulfilled orders from Amazon updated in the past 24 hours:
+```php
+function getAmazonOrders() {
+    $amz = new AmazonOrderList("myStore"); //store name matches the array key in the config file
+    $amz->setLimits('Modified', "- 24 hours");
+    $amz->setFulfillmentChannelFilter("MFN"); //no Amazon-fulfilled orders
+    $amz->setOrderStatusFilter(
+        array("Unshipped", "PartiallyShipped", "Canceled", "Unfulfillable")
+        ); //no shipped or pending
+    $amz->setUseToken(); //Amazon sends orders 100 at a time, but we want them all
+    $amz->fetchOrders();
+    return $amz->getList();
+}
+```
+This example shows a function used to send a previously-created XML feed to Amazon to update Inventory numbers:
+```php
+function sendInventoryFeed($feed) {
+    $amz=new AmazonFeed("myStore"); //store name matches the array key in the config file
+    $amz->setFeedType("_POST_INVENTORY_AVAILABILITY_DATA_"); //feed types listed in documentation
+    $amz->setFeedContent($feed);
+    $amz->submitFeed();
+    return $amz->getResponse();
+}
+```

environment.php

@@ -30,7 +30,7 @@
 $AMAZON_VERSION_FEEDS       = '2009-01-01';
 $AMAZON_VERSION_INBOUND     = '2010-10-01';
 $AMAZON_VERSION_INVENTORY   = '2010-10-01';
-$AMAZON_VERSION_ORDERS      = '2011-01-01';
+$AMAZON_VERSION_ORDERS      = '2013-09-01';
 $AMAZON_VERSION_OUTBOUND    = '2010-10-01';
 $AMAZON_VERSION_PRODUCTS    = '2011-10-01';
 $AMAZON_VERSION_REPORTS     = '2009-01-01';

examples/feed_examples.php

@@ -0,0 +1,72 @@
+<?php
+die('This is just an example and will not work without proper store credentials.');
+
+/*
+ * This script retrieves a list of active feeds for the store "myStore" and display info on them.
+ */
+$list=getAmazonFeedStatus();
+if ($list) {
+    echo 'Feed Status Report<hr>';
+    foreach ($list as $feed) {
+        //these are arrays
+        echo '<b>Feed ID:</b> '.$feed['FeedSubmissionId'];
+        echo '<br><b>Type:</b> '.$feed['FeedType'];
+        echo '<br><b>Date Sent:</b> '.$feed['SubmittedDate'];
+        echo '<br><b>Status:</b> '.$feed['FeedProcessingStatus'];
+        echo '<br><br>';
+    }
+}
+
+/**
+ * This function will retrieve a list of all items with quantity that was adjusted within the past 24 hours.
+ * The entire list of items is returned, with each item contained in an array.
+ * Note that this does not relay whether or not the feed had any errors.
+ * To get this information, the feed's results must be retrieved.
+ */
+function getAmazonFeedStatus(){
+    require('../includes/classes.php'); //autoload classes, not needed if composer is being used
+    try {
+        $amz=new AmazonFeedList("myStore");
+        $amz->setTimeLimits('- 24 hours'); //limit time frame for feeds to any updated since the given time
+        $amz->setFeedStatuses(array("_SUBMITTED_", "_IN_PROGRESS_", "_DONE_")); //exclude cancelled feeds
+        $amz->fetchFeedSubmissions(); //this is what actually sends the request
+        return $amz->getFeedList();
+    } catch (Exception $ex) {
+        echo 'There was a problem with the Amazon library. Error: '.$ex->getMessage();
+    }
+}
+
+/**
+ * This function will send a provided Inventory feed to Amazon.
+ * Amazon's response to the feed is returned as an array.
+ * This function is not actively used on this example page as a safety precaution.
+ */
+function sendInventoryFeed($feed) {
+    try {
+        $amz=new AmazonFeed("myStore"); //store name matches the array key in the config file
+        $amz->setFeedType("_POST_INVENTORY_AVAILABILITY_DATA_"); //feed types listed in documentation
+        $amz->setFeedContent($feed); //can be either XML or CSV data; a file upload method is available as well
+        $amz->submitFeed(); //this is what actually sends the request
+        return $amz->getResponse();
+    } catch (Exception $ex) {
+        echo 'There was a problem with the Amazon library. Error: '.$ex->getMessage();
+    }
+}
+
+/**
+ * This function will get the processing results of a feed previously sent to Amazon and give the data.
+ * In order to do this, a feed ID is required. The response is in XML.
+ */
+function getFeedResult($feedId) {
+    try {
+        $amz=new AmazonFeedResult("myStore", $feedId); //feed ID can be quickly set by passing it to the constructor
+        $amz->setFeedId($feedId); //otherwise, it must be set this way
+        $amz->fetchFeedResult();
+        return $amz->getRawFeed();
+    } catch (Exception $ex) {
+        echo 'There was a problem with the Amazon library. Error: '.$ex->getMessage();
+    }
+}
+
+
+?>

examples/inventory_examples.php

@@ -0,0 +1,37 @@
+<?php
+die('This is just an example and will not work without proper store credentials.');
+
+/*
+ * This script retrieves a list of recently changed item supply info for the store "myStore" and display some of it.
+ */
+$list=getAmazonSupply();
+if ($list) {
+    echo 'Amazon Inventory<hr>';
+    foreach ($list as $item) {
+        //these are arrays
+        echo '<b>Item SKU:</b> '.$item['SellerSKU'];
+        echo '<br><b>Condition:</b> '.$item['Condition'];
+        echo '<br><b>In Stock:</b> '.$item['InStockSupplyQuantity'];
+        echo '<br><br>';
+    }
+}
+
+/**
+ * This function will retrieve a list of all items with quantity that was adjusted within the past 24 hours.
+ * The entire list of items is returned, with each item contained in an array.
+ */
+function getAmazonSupply(){
+    require('../includes/classes.php'); //autoload classes, not needed if composer is being used
+    try {
+        $obj = new AmazonInventoryList("myStore"); //store name matches the array key in the config file
+        $obj->setUseToken(); //tells the object to automatically use tokens right away
+        $obj->setStartTime("- 24 hours");
+        $obj->fetchInventoryList(); //this is what actually sends the request
+        return $obj->getSupply();
+    } catch (Exception $ex) {
+        echo 'There was a problem with the Amazon library. Error: '.$ex->getMessage();
+    }
+}
+
+
+?>

examples/order_examples.php

@@ -0,0 +1,45 @@
+<?php
+die('This is just an example and will not work without proper store credentials.');
+
+/*
+ * This script retrieves a list of orders from the store "myStore" and displays various bits of their info.
+ */
+$list=getAmazonOrders();
+if ($list) {
+    echo 'My Store Orders<hr>';
+    foreach ($list as $order) {
+        //these are AmazonOrder objects
+        echo '<b>Order Number:</b> '.$order->getAmazonOrderId();
+        echo '<br><b>Purchase Date:</b> '.$order->getPurchaseDate();
+        echo '<br><b>Status:</b> '.$order->getOrderStatus();
+        echo '<br><b>Customer:</b> '.$order->getBuyerName();
+        $address=$order->getShippingAddress(); //address is an array
+        echo '<br><b>City:</b> '.$address['City'];
+        echo '<br><br>';
+    }
+}
+
+/**
+ * This function will retrieve a list of all unshipped MFN orders made within the past 24 hours.
+ * The entire list of orders is returned, with each order contained in an AmazonOrder object.
+ * Note that the items in the order are not included in the data.
+ * To get the order's items, the "fetchItems" method must be used by the specific order object.
+ */
+function getAmazonOrders() {
+    require('../includes/classes.php'); //autoload classes, not needed if composer is being used
+    try {
+        $amz = new AmazonOrderList("myStore"); //store name matches the array key in the config file
+        $amz->setLimits('Modified', "- 24 hours"); //accepts either specific timestamps or relative times 
+        $amz->setFulfillmentChannelFilter("MFN"); //no Amazon-fulfilled orders
+        $amz->setOrderStatusFilter(
+            array("Unshipped", "PartiallyShipped", "Canceled", "Unfulfillable")
+            ); //no shipped or pending orders
+        $amz->setUseToken(); //tells the object to automatically use tokens right away
+        $amz->fetchOrders(); //this is what actually sends the request
+        return $amz->getList();
+    } catch (Exception $ex) {
+        echo 'There was a problem with the Amazon library. Error: '.$ex->getMessage();
+    }
+}
+
+?>

includes/classes/AmazonCore.php

@@ -105,6 +105,7 @@ abstract class AmazonCore{
     protected $mockIndex = 0;
     protected $logpath;
     protected $env;
+    protected $rawResponses = array();
 
     /**
      * AmazonCore constructor sets up key information used in all Amazon requests.
@@ -589,9 +590,49 @@ protected function sendRequest($url,$param){
             $response = $this->fetchURL($url,$param);
         }
 
+        $this->rawResponses[]=$response;
         return $response;
     }
 
+    /**
+     * Gives the latest response data received from Amazon.
+     * Response arrays contain the following keys:
+     * <ul>
+     * <li><b>head</b> - The raw HTTP head, including the response code and content length</li>
+     * <li><b>body</b> - The raw HTTP body, which will almost always be in XML format</li>
+     * <li><b>code</b> - The HTTP response code extracted from the head for convenience</li>
+     * <li><b>answer</b> - The HTTP response message extracted from the head for convenience</li>
+     * <li><b>ok</b> - Contains a <b>1</b> if the response was normal, or <b>0</b> if there was a problem</li>
+     * <li><b>headarray</b> - An associative array of the head data, for convenience</li>
+     * </ul>
+     * @param int $i [optional] <p>If set, retrieves the specific response instead of the last one.
+     * If the index for the response is not used, <b>FALSE</b> will be returned.</p>
+     * @return array associative array of HTTP response or <b>FALSE</b> if not set yet
+     */
+    public function getLastResponse($i=NULL) {
+        if (!isset($i)) {
+            $i=count($this->rawResponses)-1;
+        }
+        if ($i >= 0 && isset($this->rawResponses[$i])) {
+            return $this->rawResponses[$i];
+        } else {
+            return false;
+        }
+    }
+    
+    /**
+     * Gives all response code received from Amazon.
+     * @return array list of associative arrays of HTTP response or <b>FALSE</b> if not set yet
+     * @see getLastResponse
+     */
+    public function getRawResponses() {
+        if (!empty($this->rawResponses)) {
+            return $this->rawResponses;
+        } else {
+            return false;
+        }
+    }
+    
     /**
      * Sleeps for the throttle time and records to the log.
      */