Merge pull request #15 from djvaldez/requests-from-xml

Update readme for NVP and XML support. Update code comments

Author: brianmc

README.md

@@ -23,7 +23,7 @@ If you want to install SDK from Packagist,add the following dependency to your a
 
 ##Installation
 
-You can install the client either via [Composer](https://getcomposer.org/) or manually. Before installing, make sure to configure the merchant ID, transaction key, and the WSDL file URL in ````cybs.ini````. By default, the WSDL file for the client is for API version 1.109 (the latest when this package was created). Available WSDL file URLs can be browsed at the following locations:
+You can install the client either via [Composer](https://getcomposer.org/) or manually. Before installing, make sure to configure the merchant ID, transaction key, and the appropriate WSDL file URL in ````cybs.ini````. By default, the WSDL file for the client is for API version 1.120 (the latest when this package was updated). Available WSDL file URLs can be browsed at the following locations:
 
 - [test](https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/)
 - [live](https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/)
@@ -48,7 +48,10 @@ require_once('/path/to/project/lib/CybsSoapClient.php');
 
 
 ##Getting Started
-The PHP client will generate the request message headers for you, and will contain the methods specified by the WSDL file. The main method you'll use is ````runTransaction()````. To run a transaction, you'll first need to construct a client to generate a request object, which you can populate with the necessary fields (see [documentation](http://www.cybersource.com/developers/integration_methods/simple_order_and_soap_toolkit_api/soap_api/html/wwhelp/wwhimpl/js/html/wwhelp.htm#href=Intro.04.4.html) for sample requests). The object will be converted into XML, so the properties of the object will need to correspond to the correct XML format.
+The PHP client will generate the request message headers for you, and will contain the methods specified by the WSDL file.
+
+###Creating a simple request
+The main method you'll use is ````runTransaction()````. To run a transaction, you'll first need to construct a client to generate a request object, which you can populate with the necessary fields (see [documentation](http://www.cybersource.com/developers/integration_methods/simple_order_and_soap_toolkit_api/soap_api/html/wwhelp/wwhimpl/js/html/wwhelp.htm#href=Intro.04.4.html) for sample requests). The object will be converted into XML, so the properties of the object will need to correspond to the correct XML format.
 
 ```php
 $client = new CybsSoapClient();
@@ -65,6 +68,37 @@ $request->card = $card;
 $reply = $client->runTransaction($request);
 ```
 
+###Creating a request from XML
+You can create a request from XML either in a file or from an XML string. The XML request format is described in the **Using XML** section [here](http://apps.cybersource.com/library/documentation/dev_guides/Simple_Order_API_Clients/Client_SDK_SO_API.pdf). Here's how to run a transaction from an XML file:
+
+```php
+$referenceCode = 'your_merchant_reference_code';
+$client = new CybsSoapClient();
+$reply = $client->runTransactionFromFile('path/to/my.xml', $referenceCode);
+```
+
+Or, you can create your own XML string and use that instead:
+
+```php
+$xml = "";
+// Populate $xml
+$client = new CybsSoapClient();
+$client->runTransactionFromXml($xml);
+```
+
+###Using name-value pairs
+In order to run transactions using name-value pairs, make sure to set the value for the WSDL for the NVP transaction processor in ````cybs.ini````. Then use the ````CybsNameValuePairClient```` as so:
+
+```php
+$client = new CybsNameValuePairClient();
+$request = array();
+$request['ccAuthService_run'] = 'true';
+$request['merchantID'] = 'my_merchant_id';
+$request['merchantReferenceCode'] = $'my_reference_code';
+// Populate $request
+$reply = $client->runTransaction($request);
+```
+
 ##Running the Samples
 After configuring your merchant ID and transaction key in ````cybs.ini````, the samples in the ````samples```` directory can be run from the project root. For example:
 

lib/CybsSoapClient.php

@@ -16,10 +16,17 @@ function __construct($options=array())
         parent::__construct($options, $properties);
     }
 
-    public function simpleXmlToCybsRequest($simpleXml) {
-
+    /**
+     * Returns a properly formatted request object from a SimpleXMLElement. 
+     *
+     * @param SimpleXMLElement $simpleXml Representation of an XML structure
+     * @return stdClass A request with the data from the SimpleXMLElement.
+     */
+    public function simpleXmlToCybsRequest($simpleXml)
+    {
         $vars = get_object_vars($simpleXml);
         $request = new stdClass();
+
         foreach(array_keys($vars) as $key) {
             $element = $vars[$key];
             if ($key == 'comment') {
@@ -83,7 +90,7 @@ public function runTransactionFromXml($xml, $merchantReferenceCode)
     }
 
     /**
-     * Runs a transaction from an XML file
+     * Runs a transaction from an XML file.
      *
      * @param string $filePath The path to the XML file
      * @param string $merchantReferenceCode Desired reference code for the request

lib/conf/cybs.ini

@@ -2,7 +2,7 @@ merchant_id = your_merchant_id
 transaction_key = "your_transaction_key"
 
 ; Modify the URL to point to either a live or test WSDL file with the desired API version.
-wsdl = "https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.109.wsdl"
+wsdl = "https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_1.120.wsdl"
 
 ; Modify the URL to point to either a live or test WSDL file with the desired API version for the name-value pairs transaction API.
-nvp_wsdl = "https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_NVP_1.120.wsdl"
+nvp_wsdl = "https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor/CyberSourceTransaction_NVP_1.120.wsdl"

samples/AuthFromNameValuePairs.php

@@ -15,8 +15,8 @@
 
 $request = array();
 $request['ccAuthService_run'] = 'true';
-$request['merchantID'] = 'dvaldez';
-$request['merchantReferenceCode'] = 'MRC-14344';
+$request['merchantID'] = 'your_merchant_id';
+$request['merchantReferenceCode'] = $referenceCode;
 $request['billTo_firstName'] = 'Jane';
 $request['billTo_lastName'] = 'Smith';
 $request['billTo_street1'] = '1295 Charleston Road';