Merge pull request #91 from CPIGroup/master

Version 1.3 Release Candidate

.travis.yml

@@ -0,0 +1,7 @@
+language: php
+php:
+    - '5.4'
+    - '5.5'
+    - '5.6'
+    - '7'
+script: cd test-cases && phpunit --bootstrap bootstrap.php

CHANGELOG.md

@@ -0,0 +1,102 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## 1.3.0 - 2016-08-03
+### Added
+- Travis support
+- PHPUnit XML configuration file
+- Change log file
+- Contribution guidelines file
+- Credits file
+- Added support for MWS Auth Token, which can be set for each store in the config file.
+- Added methods for getting the last response code, error message, and error response.
+- Added support for the Merchant Fulfillment API with three new classes.
+- Added support for the Recommendations API with one new class.
+- Added support for the Subscriptions API with three new classes.
+- Added support for the Finance API two new classes.
+- Added four new Inbound classes relating to preorders, transport, and item prep instructions.
+- The marketplace can now be specified in the Order List class, Fulfillment Order class, and all Product classes.
+- New response fields in the Feed class: `StartedProcessingDate` and `CompletedProcessingDate`
+- New response fields in the Order class: `IsBusinessOrder`, `PurchaseOrderNumber`, `IsPrime`, and `IsPremiumOrder`
+- New response fields in the Order Item List class: `BuyerCustomizedInfo`, `PointsGranted`, and `PriceDesignation`
+- Added a method for getting the order ID from the Order Item List class.
+- New parameter in the Order List class: `TFMShipmentStatus`
+- Added a method for getting the raw report data from the Report class.
+- New response field in the Report List class: `AcknowledgedDate`
+- New response fields in the Fulfillment Order class: `MarketplaceId`, `DeliveryWindow`, `FulfillmentAction`, `CODSettings`, `PerUnitPrice`, and `PerUnitTax`.
+- New parameters in the Fulfillment Order Creator class: `MarketplaceId`, `FulfillmentAction`, `CODSettings`, and `DeliveryWindow`. The method for setting items now also has `PerUnitPrice` and `PerUnitTax`.
+- New method in the Fulfillment Order Creator class for updating orders.
+- New response fields in the Fulfillment Order List class: `MarketplaceId`, `DeliveryWindow`, `FulfillmentAction`, and `CODSettings`.
+- New options in the Fulfillment Preview class: `IncludeCODFulfillmentPreview` and `IncludeDeliveryWindows`.
+- New response fields in the Fulfillment Preview class: `ShippingSpeedCategory`, `IsFulfillable`, `IsCODCapable`, `MarketplaceId`, and `ScheduledDeliveryInfo`.
+- New method in the Product Info class for getting lowest-priced offers.
+- The Product class now keeps the identifier used to search for an item under the key `Request`.
+- New methods in the Shipment class for setting parameters previously restricted to use of `usePlan`.
+- New parameter in the Shipment class: `ShipmentName`. The method for setting items now also supports `PrepDetailsList` and `ReleaseDate` for each item.
+- New response fields in the Shipment Item List class: `PrepDetailsList` and `ReleaseDate`
+- New response field in the Shipment List class: `ConfirmedNeedByDate`
+- New parameters in the Shipment Planner class: `ShipToCountryCode` and `ShipToCountrySubdivisionCode`. The method for setting items now also supports `ASIN` and `PrepDetailsList` for each item.
+- New response field in the Shipment Planner class: `PrepDetailsList`
+- Added support for new styles of token responses used by some classes.
+
+### Changed
+- Some tests that tried to load the normal configuration file now properly load test configuration.
+- Corrected many small mistakes in documentation.
+- The `setShowSalesChannel` method in the Report class now properly sets the parameter.
+- The Service URL setting now works with or without a slash at the end.
+- Changed all private methods and properties to protected.
+- Updated the Composer file to allow for newer PHP versions.
+- Fixed the spelling of `StateOrProvinceCode` throughout the Outbound and Inbound classes.
+- The `genTime` method now supports Unix timestamps, though some methods that use `genTime` still do not.
+- Updated the name of the `CompletedProcessingDate` field in the Report Request List class to `CompletedDate`.
+- Deprecated `getDateProcessingCompleted` in favor of `getDateCompleted`.
+- Updated the name of the `ShipServiceLevelCategory` field in the Order class to `ShipmentServiceLevelCategory`.
+- Deprecated `getShipServiceLevelCategory` in favor of `getShipmentServiceLevelCategory`.
+- Deprecated `setFulfillmentMethod` in the Fulfillment Order Creator class.
+- Deprecated `setMethodFilter` in the Fulfillment Order List class.
+- The Product Info class now properly gets all relationships.
+- The Shipment class no longer sets the address when using `usePlan` and correctly sets other parameters.
+- Fixed a loop caused by an empty response to actions that use tokens.
+
+### Removed
+- Removed all of the old leftover test XML files from the mock folder
+- Removed old environment config lines from the test config file
+
+## 1.2.0 - 2016-03-10
+### Added
+- The store name can now be omitted when initiating objects if there is only one store is set in the config file.
+- Added support for four relatively-new fields returned for Orders: `CbaDisplayableShippingLabel`, `ShippedByAmazonTFM`, `TFMShipmentStatus`, and `OrderType`.
+- Each store in the config file can have its own `serviceUrl`, which will override the normal service URL.
+
+### Changed
+- Log messages now display time using the 24 hour format, rather than 12 hour.
+
+### Fixed
+- Inventory lists no longer cause an error if detailed information is not given.
+- Logging function no longer gives an error when PHP is in strict mode.
+- Removed bad include paths from NetBeans project settings.
+- Product class no longer gives an error when PHP is in strict mode.
+- Product Info class now uses the correct identifier parameters when fetching categories.
+- Product Info class now correctly gets child relationship data.
+
+### Removed
+- Removed the obsolete `checkResponse` method from the Feed class.
+
+## 1.1.0 - 2014-05-06
+### Added
+- Raw responses are stored for debugging purposes and can be accessed with getLastResponse() or getRawResponses()
+- Created a folder for example scripts and added some examples to the readme
+- Updated the Orders API to the 2013-09-01 version, which adds Earliest/Latest Ship Date and Delivery Date to returned order data
+
+### Changed
+- Feeds now allow for direct string input rather than relying entirely on files
+- Amazon-defined constants, such as API version numbers and throttle times, have been moved to a separate file since users shouldn't have to worry about them. Users who already have a config file should redo them.
+
+### Fixed
+- HTTP 100 Continue responses are properly handled
+
+## 1.0.0 - 2014-02-12
+### Added
+- Core class
+- Classes for eight APIs: Feeds, Fulfillment Inbound, Fulfillment Inventory, Fulfillment Outbound, Orders, Products, Reports, and Sellers

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+##General
+All pull requests should target the master branch. Commits should not have different code changes mixed together and should have descriptive messages.
+
+##Project Scope
+The goal of this project is to provide a library with which the average merchant can communicate with Amazon's MWS services without needing to learn the complex language of the API. When contributing, think about whether or not the contribution is something that the average Amazon merchant would need to intract with Amazon.
+
+Code for handling the merchant's data, such as for generating feeds or data crunching, falls outside of the library's intended scope and, while useful, is best left to separate projects.
+
+##Code Guidelines
+The library is written using a custom style and does not follow any particular standard. For the sake of cohesion, changes to the code should be written in this same style. Please do not make changes to the style of the code.
+
+Any new changes should fit within the previously-mentioned goal of the project. New public methods and classes should have names that are easy to understand and use without needing to consult the API's documentation. Try to follow the trend of similar existing functions, such as how methods that send requests to get information from Amazon usually have names that start with "fetch."
+
+New methods should have phpdocs explaining how to use them and how they will affect the options sent in the next request. New classes should have phpdocs explaining their purpose and the workflow for using them. If the class is one that sends requests to Amazon, the documentation should indicate which Amazon actions it can perform and which of its methods are required before a request can be sent. Check the phpdocs on existing classes for examples.

CREDITS

@@ -0,0 +1 @@
+The phpAmazonMWS library was designed and written by Thomas Hernandez (peardian at gmail) for the CPI Group.

README.md

@@ -1,6 +1,8 @@
 phpAmazonMWS
 ============
 
+[![Build Status](https://travis-ci.org/CPIGroup/phpAmazonMWS.svg?branch=stable)](https://travis-ci.org/CPIGroup/phpAmazonMWS)
+
 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.

amazon-config.default.php

@@ -22,6 +22,7 @@
 $store['YourAmazonStore']['keyId'] = ''; //Access Key ID
 $store['YourAmazonStore']['secretKey'] = ''; //Secret Access Key for this store
 $store['YourAmazonStore']['serviceUrl'] = ''; //optional override for Service URL
+$store['YourAmazonStore']['MWSAuthToken'] = ''; //token needed for web apps and third-party developers
 
 //Service URL Base
 //Current setting is United States

composer.json

@@ -5,7 +5,7 @@
     "license": "Apache-2.0",
     "keywords": ["API", "Amazon", "PHP"],
     "require":{
-                "php": "~5.4",
+                "php": ">=5.4",
                 "ext-curl": "*"
     },
     "require-dev": {

environment.php

@@ -28,13 +28,17 @@
 
 //Version numbers for cores
 $AMAZON_VERSION_FEEDS       = '2009-01-01';
+$AMAZON_VERSION_FINANCE     = '2015-05-01';
 $AMAZON_VERSION_INBOUND     = '2010-10-01';
 $AMAZON_VERSION_INVENTORY   = '2010-10-01';
+$AMAZON_VERSION_MERCHANT    = '2015-06-01';
 $AMAZON_VERSION_ORDERS      = '2013-09-01';
 $AMAZON_VERSION_OUTBOUND    = '2010-10-01';
 $AMAZON_VERSION_PRODUCTS    = '2011-10-01';
+$AMAZON_VERSION_RECOMMEND   = '2013-04-01';
 $AMAZON_VERSION_REPORTS     = '2009-01-01';
 $AMAZON_VERSION_SELLERS     = '2011-07-01';
+$AMAZON_VERSION_SUBSCRIBE   = '2013-07-01';
 
 //Amazon Throttle Values in seconds
 //Fetching Orders
@@ -82,11 +86,23 @@
 //Submitting a Feed
 $THROTTLE_LIMIT_FEEDSUBMIT = 15;
 $THROTTLE_TIME_FEEDSUBMIT = 120;
-//Getting a Feed
+//Fetching a Feed List
 $THROTTLE_LIMIT_FEEDLIST = 10;
 $THROTTLE_TIME_FEEDLIST = 45;
 //Getting a Feed
 $THROTTLE_LIMIT_FEEDRESULT = 15;
 $THROTTLE_TIME_FEEDRESULT = 60;
+//Merchant Fulfillments
+$THROTTLE_LIMIT_MERCHANT = 10;
+$THROTTLE_TIME_MERCHANT = 1;
+//Subscriptions
+$THROTTLE_LIMIT_SUBSCRIBE = 25;
+$THROTTLE_TIME_SUBSCRIBE = 1;
+//Recommendations
+$THROTTLE_LIMIT_RECOMMEND = 8;
+$THROTTLE_TIME_RECOMMEND = 2;
+//Recommendations
+$THROTTLE_LIMIT_FINANCE = 30;
+$THROTTLE_TIME_FINANCE = 2;
 
 ?>

includes/classes/AmazonCore.php

@@ -190,10 +190,10 @@ public function setMock($b = true,$files = null){
      * including the name and path of the file involved. For retrieving response
      * codes, see <i>fetchMockResponse</i>.
      * @param boolean $load [optional] <p>Set this to <b>FALSE</b> to prevent the
-     * method from loading the file's contents into a SimpleXMLObject. This is
+     * method from loading the file's contents into a SimpleXMLElement. This is
      * for when the contents of the file are not in XML format, or if you simply
      * want to retrieve the raw string of the file.</p>
-     * @return SimpleXMLObject|string|boolean <p>A SimpleXMLObject holding the
+     * @return SimpleXMLElement|string|boolean <p>A SimpleXMLElement holding the
      * contents of the file, or a string of said contents if <i>$load</i> is set to
      * <b>FALSE</b>. The return will be <b>FALSE</b> if the file cannot be
      * fetched for any reason.</p>
@@ -362,7 +362,7 @@ public function setConfig($path){
             $this->config = $path;
             $this->setLogPath($logpath);
             if (isset($AMAZON_SERVICE_URL)) {
-                $this->urlbase = $AMAZON_SERVICE_URL;
+                $this->urlbase = rtrim($AMAZON_SERVICE_URL, '/') . '/';
             }
         } else {
             throw new Exception("Config file does not exist or cannot be read! ($path)");
@@ -431,6 +431,9 @@ public function setStore($s=null){
             if (!empty($store[$s]['serviceUrl'])) {
                 $this->urlbase = $store[$s]['serviceUrl'];
             }
+            if (!empty($store[$s]['MWSAuthToken'])) {
+                $this->options['MWSAuthToken'] = $store[$s]['MWSAuthToken'];
+            }
 
         } else {
             $this->log("Store $s does not exist!",'Warning');
@@ -543,17 +546,22 @@ public function getOptions(){
      * The string given is passed through <i>strtotime</i> before being used. The
      * value returned is actually two minutes early, to prevent it from tripping up
      * Amazon. If no time is given, the current time is used.
-     * @param string $time [optional] <p>The time to use. Since this value is
+     * @param string|int $time [optional] <p>The time to use. Since any string values are
      * passed through <i>strtotime</i> first, values such as "-1 hour" are fine.
+     * Unix timestamps are also allowed. Purely numeric values are treated as unix timestamps.
      * Defaults to the current time.</p>
      * @return string Unix timestamp of the time, minus 2 minutes.
+     * @throws InvalidArgumentException
      */
     protected function genTime($time=false){
         if (!$time){
             $time = time();
-        } else {
+        } else if (is_numeric($time)) {
+            $time = (int)$time;
+        } else if (is_string($time)) {
             $time = strtotime($time);
-
+        } else {
+            throw new InvalidArgumentException('Invalid time input given');
         }
         return date('Y-m-d\TH:i:sO',$time-120);
 
@@ -646,6 +654,69 @@ public function getRawResponses() {
             return false;
         }
     }
+
+    /**
+     * Gives the response code from the last response.
+     * This data can also be found in the array given by getLastResponse.
+     * @return string|int standard REST response code (200, 404, etc.) or <b>NULL</b> if no response
+     * @see getLastResponse
+     */
+    public function getLastResponseCode() {
+        $last = $this->getLastResponse();
+        if (!empty($last['code'])) {
+            return $last['code'];
+        }
+    }
+
+    /**
+     * Gives the last response with an error code.
+     * This may or may not be the same as the last response if multiple requests were made.
+     * @return array associative array of HTTP response or <b>NULL</b> if no error response yet
+     * @see getLastResponse
+     */
+    public function getLastErrorResponse() {
+        if (!empty($this->rawResponses)) {
+            foreach (array_reverse($this->rawResponses) as $x) {
+                if (isset($x['error'])) {
+                    return $x;
+                }
+            }
+        }
+    }
+
+    /**
+     * Gives the Amazon error code from the last error response.
+     * The error code uses words rather than numbers. (Ex: "InvalidParameterValue")
+     * This data can also be found in the XML body given by getLastErrorResponse.
+     * @return string Amazon error code or <b>NULL</b> if not set yet or no error response yet
+     * @see getLastErrorResponse
+     */
+    public function getLastErrorCode() {
+        $last = $this->getLastErrorResponse();
+        if (!empty($last['body'])) {
+            $xml = simplexml_load_string($last['body']);
+            if (isset($xml->Error->Code)) {
+                return $xml->Error->Code;
+            }
+        }
+    }
+
+    /**
+     * Gives the error message from the last error response.
+     * Not all error responses will have error messages.
+     * This data can also be found in the XML body given by getLastErrorResponse.
+     * @return string Amazon error code or <b>NULL</b> if not set yet or no error response yet
+     * @see getLastErrorResponse
+     */
+    public function getLastErrorMessage() {
+        $last = $this->getLastErrorResponse();
+        if (!empty($last['body'])) {
+            $xml = simplexml_load_string($last['body']);
+            if (isset($xml->Error->Message)) {
+                return $xml->Error->Message;
+            }
+        }
+    }
 
     /**
      * Sleeps for the throttle time and records to the log.
@@ -659,14 +730,11 @@ protected function sleep(){
 
     /**
      * Checks for a token and changes the proper options
-     * @param SimpleXMLObject $xml <p>response data</p>
+     * @param SimpleXMLElement $xml <p>response data</p>
      * @return boolean <b>FALSE</b> if no XML data
      */
     protected function checkToken($xml){
-        if (!$xml){
-            return false;
-        }
-        if ($xml->NextToken){
+        if ($xml && $xml->NextToken && (string)$xml->HasNext != 'false' && (string)$xml->MoreResultsAvailable != 'false'){
             $this->tokenFlag = true;
             $this->options['NextToken'] = (string)$xml->NextToken;
         } else {
@@ -768,7 +836,8 @@ function fetchURL ($url, $param) {
      */
     protected function _urlencode($value) {
         return rawurlencode($value);
-		return str_replace('%7E', '~', rawurlencode($value));
+        //Amazon suggests doing this, but it seems to break things rather than fix them:
+        //return str_replace('%7E', '~', rawurlencode($value));
     }
 
     /**