Merge pull request #58 from Petschko/dev

Added updateShipment DHL-Method plus a helper method

examples/getting-started.md

@@ -345,6 +345,15 @@ if($response === false) {
 You can get several Information from the `\Petschko\DHL\Response` Object. Please have a look down where I describe the `\Petschko\DHL\Response` Class.
 
 
+### Update a Shipment
+
+It works the same like creating a Shipment, but you need to specify the Shipment number, you want to update! You call this 
+request via `$dhl->updateShipmentOrder($shipmentNumber)`.
+```php
+	$dhl->updateShipmentOrder((string) $shipmentNumber)
+```
+
+
 ### Delete one or multiple Shipment(s)
 
 _Please note, that you need the `\Petschko\DHL\Credentials` Object with Valid Login-Information for that._
@@ -554,4 +563,28 @@ const \Petschko\DHL\Response::ERROR_HARD_VAL_ERROR = 1101;
 const \Petschko\DHL\Response::ERROR_UNKNOWN_SHIPMENT_NUMBER = 2000;
 ```
 
+## Important helper functions
+
+It can happen that you want to see the XML-Code, which was created from your request, there is a function, which can show this to you! Sometimes you need this to debug or send this code to the DHL-Support, when you have issues.
+
+```php
+$dhl = new \Petschko\DHL\BusinessShipment($credentials);
+
+// (...) Code to call an DHL-Action
+
+$dhl->getLastXML(); // You get a string with the XML-Code from this function, you can save it to a file or display it
+```
+
+There is also a function, which shows you the Response-XML from DHL. Can be helpful for debug or when the DHL-Support ask for it.
+
+```php
+$dhl = new \Petschko\DHL\BusinessShipment($credentials);
+
+// (...) Code to call an DHL-Action
+
+$dhl->getLastDhlXMLResponse(); // You get a string with the XML-Code from this function, you can save it to a file or display it
+```
+
+You get `null` as response, when you didn't called any DHL Action
+
 That's all so far

includes/BusinessShipment.php

@@ -8,7 +8,7 @@
  * Date: 26.01.2017
  * Time: 15:37
  * Update: 05.09.2018
- * Version: 1.6.2
+ * Version: 1.7.0
  *
  * Notes: Contains all Functions/Values for DHL-Business-Shipment
  */
@@ -337,6 +337,18 @@ public function getLastXML() {
 		return $this->getSoapClient()->__getLastRequest();
 	}
 
+	/**
+	 * Returns the last XML-Response from DHL or null
+	 *
+	 * @return null|string - Last XML-Response from DHL or null if none
+	 */
+	public function getLastDhlXMLResponse() {
+		if($this->soapClient === null)
+			return null;
+
+		return $this->getSoapClient()->__getLastResponse();
+	}
+
 	/**
 	 * Set the Soap-Client
 	 *
@@ -1262,16 +1274,20 @@ private function createShipmentClass_v1() {
 	/**
 	 * Creates the Data-Object for the Request
 	 *
+	 * @param null|string $shipmentNumber - Shipment Number which should be included or null for none
 	 * @return StdClass - Data-Object
 	 */
-	private function createShipmentClass_v2() {
+	private function createShipmentClass_v2($shipmentNumber = null) {
 		$shipmentOrders = $this->getShipmentOrders();
 
 		$this->checkRequestCount($shipmentOrders, 'createShipmentClass');
 
 		$data = new StdClass;
 		$data->Version = $this->getVersionClass();
 
+		if($shipmentNumber !== null)
+			$data->shipmentNumber = (string) $shipmentNumber;
+
 		foreach($shipmentOrders as $key => &$shipmentOrder) {
 			/**
 			 * @var ShipmentOrder $shipmentOrder
@@ -1280,7 +1296,7 @@ private function createShipmentClass_v2() {
 			if($shipmentOrder->getLabelResponseType() === null && $this->getLabelResponseType() !== null)
 				$shipmentOrder->setLabelResponseType($this->getLabelResponseType());
 
-			$data->ShipmentOrder[$key] = $shipmentOrder->getShipmentOrderClass_v2(); // todo test
+			$data->ShipmentOrder[$key] = $shipmentOrder->getShipmentOrderClass_v2();
 		}
 
 		return $data;
@@ -1289,11 +1305,12 @@ private function createShipmentClass_v2() {
 	/**
 	 * Creates the Data-Object for the Request
 	 *
+	 * @param null|string $shipmentNumber - Shipment Number which should be included or null for none
 	 * @return StdClass - Data-Object
 	 *
 	 * @deprecated - Old Shipment creation class (Supports only 1 Shipment)
 	 */
-	private function createShipmentClass_v2_legacy() {
+	private function createShipmentClass_v2_legacy($shipmentNumber = null) {
 		trigger_error(
 			'[DHL-PHP-SDK]: ' . __CLASS__ . '->' . __METHOD__ .
 			' This method was called for Backward-Compatibility, please create `ShipmentOrder` Objects' .
@@ -1308,6 +1325,10 @@ private function createShipmentClass_v2_legacy() {
 		// Create class
 		$data = new StdClass;
 		$data->Version = $this->getVersionClass();
+
+		if($shipmentNumber !== null)
+			$data->shipmentNumber = (string) $shipmentNumber;
+
 		$data->ShipmentOrder = new StdClass;
 		$data->ShipmentOrder->sequenceNumber = $this->getSequenceNumber();
 
@@ -1693,4 +1714,65 @@ private function sendValidateShipmentRequest($data) {
 				return $this->getSoapClient()->validateShipment($data);
 		}
 	}
+
+	/**
+	 * Updates the Shipment-Request
+	 *
+	 * @param string $shipmentNumber - Number of the Shipment, which should be updated
+	 * @return bool|Response - false on error or DHL-Response Object
+	 */
+	public function updateShipmentOrder($shipmentNumber) {
+		if(is_array($shipmentNumber) || $this->countShipmentOrders() > 1) {
+			$this->addError(__FUNCTION__ . ': Updating Shipments is a Single-Operation only!');
+
+			return false;
+		}
+
+		switch($this->getMayor()) {
+			case 1:
+				$data = null;
+				break;
+			case 2:
+			default:
+				if($this->countShipmentOrders() < 1)
+					$data = $this->createShipmentClass_v2_legacy($shipmentNumber);
+				else
+					$data = $this->createShipmentClass_v2($shipmentNumber);
+		}
+
+		$response = null;
+
+		// Create Shipment
+		try {
+			$response = $this->sendUpdateRequest($data);
+		} catch(Exception $e) {
+			$this->addError($e->getMessage());
+
+			return false;
+		}
+
+		if(is_soap_fault($response)) {
+			$this->addError($response->faultstring);
+
+			return false;
+		} else
+			return new Response($this->getVersion(), $response);
+	}
+
+	/**
+	 * Requests the Update of a Shipment via SOAP
+	 *
+	 * @param Object|array $data - Shipment-Data
+	 * @return Object - DHL-Response
+	 * @throws Exception - Method doesn't exists for Version
+	 */
+	private function sendUpdateRequest($data) {
+		switch($this->getMayor()) {
+			case 1:
+				throw new Exception(__FUNCTION__ . ': Method doesn\'t exists for Version 1!');
+			case 2:
+			default:
+				return $this->getSoapClient()->updateShipmentOrder($data);
+		}
+	}
 }