DHLEX-80: add waybill document flag to request | resolve #11

netresearch · Sep 15, 2020 · 2ae6ea9 · 2ae6ea9
1 parent 0c05fa4
commit 2ae6ea9
Show file tree

Hide file tree

Showing 13 changed files with 366 additions and 115 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## ## 2.1.0 - 2020-09-15
+
+### Added
+
+- Set label option flag to request a waybill document, contributed by D. Fairbrother and [@JustoHermano](https://github.com/JustoHermano) via [PR #11](https://github.com/netresearch/dhl-sdk-api-express/pull/11)
+
 ## 2.0.2 - 2020-09-01
 
 ### Added

diff --git a/README.md b/README.md
@@ -56,7 +56,7 @@ $logger = new \Psr\Log\NullLogger();
 $serviceFactory = new SoapServiceFactory();
 $service = $serviceFactory->createRateService('api-user', 'api-pass', $logger);
 
-$requestBuilder = new RateRequestBuilder()
+$requestBuilder = new RateRequestBuilder();
 $requestBuilder->setIsUnscheduledPickup($isUnscheduledPickup);
 $requestBuilder->setShipperAccount($accountNumber);
 $requestBuilder->setShipperAddress($countryCode, $postalCode, $city, $etc);
@@ -99,7 +99,7 @@ $logger = new \Psr\Log\NullLogger();
 $serviceFactory = new SoapServiceFactory();
 $service = $serviceFactory->createShipmentService('api-user', 'api-pass', $logger);
 
-$requestBuilder = new ShipmentRequestBuilder()
+$requestBuilder = new ShipmentRequestBuilder();
 $requestBuilder->setIsUnscheduledPickup($unscheduledPickup);
 $requestBuilder->setTermsOfTrade($termsOfTrade);
 $requestBuilder->setContentType($contentType);

diff --git a/src/Api/Data/Request/Shipment/LabelOptionsInterface.php b/src/Api/Data/Request/Shipment/LabelOptionsInterface.php
@@ -0,0 +1,38 @@
+<?php
+/**
+ * See LICENSE.md for license details.
+ */
+
+namespace Dhl\Express\Api\Data\Request\Shipment;
+
+/**
+ * LabelOptions Interface.
+ *
+ * DHL Express allows to pass label options with the shipment request:
+ * - CustomerLogo
+ * - CustomerBarcode
+ * - PrinterDPI
+ * - RequestWaybillDocument
+ * - HideAccountInWaybillDocument
+ * - NumberOfWaybillDocumentCopies
+ * - RequestDHLCustomsInvoice
+ * - DHLCustomsInvoiceLanguageCode
+ * - DHLCustomsInvoiceType
+ * - RequestShipmentReceipt
+ * - DetachOptions
+ *
+ * Currently only the waybill document request flag is supported.
+ *
+ * @api
+ * @author Daniel Fairbrother <dfairbrother@datto.com>
+ * @link   https://www.datto.com/
+ */
+interface LabelOptionsInterface
+{
+    /**
+     * Returns whether a waybill document is requested or not.
+     *
+     * @return bool
+     */
+    public function isWaybillDocumentRequested(): bool;
+}
diff --git a/src/Api/Data/ShipmentRequestInterface.php b/src/Api/Data/ShipmentRequestInterface.php
@@ -9,6 +9,7 @@
 use Dhl\Express\Api\Data\Request\PackageInterface;
 use Dhl\Express\Api\Data\Request\RecipientInterface;
 use Dhl\Express\Api\Data\Request\Shipment\DangerousGoods\DryIceInterface;
+use Dhl\Express\Api\Data\Request\Shipment\LabelOptionsInterface;
 use Dhl\Express\Api\Data\Request\Shipment\ShipmentDetailsInterface;
 use Dhl\Express\Api\Data\Request\Shipment\ShipperInterface;
 
@@ -27,40 +28,45 @@ interface ShipmentRequestInterface
     /**
      * @return ShipmentDetailsInterface
      */
-    public function getShipmentDetails();
+    public function getShipmentDetails(): ShipmentDetailsInterface;
 
     /**
      * @return string
      */
-    public function getPayerAccountNumber();
+    public function getPayerAccountNumber(): string;
 
     /**
      * @return string
      */
-    public function getBillingAccountNumber();
+    public function getBillingAccountNumber(): string;
 
     /**
      * @return null|InsuranceInterface
      */
-    public function getInsurance();
+    public function getInsurance(): ?InsuranceInterface;
 
     /**
      * @return ShipperInterface
      */
-    public function getShipper();
+    public function getShipper(): ShipperInterface;
 
     /**
      * @return RecipientInterface
      */
-    public function getRecipient();
+    public function getRecipient(): RecipientInterface;
 
     /**
      * @return PackageInterface[]
      */
-    public function getPackages();
+    public function getPackages(): array;
 
     /**
      * @return null|DryIceInterface
      */
-    public function getDryIce();
+    public function getDryIce(): ?DryIceInterface;
+
+    /**
+     * @return null|LabelOptionsInterface
+     */
+    public function getLabelOptions(): ?LabelOptionsInterface;
 }
diff --git a/src/Api/ShipmentRequestBuilderInterface.php b/src/Api/ShipmentRequestBuilderInterface.php
@@ -16,13 +16,13 @@
 interface ShipmentRequestBuilderInterface
 {
     /**
-     * Returns whether this is a scheduled pickup or not.
+     * Sets whether this is a scheduled pickup or not.
      *
      * @param bool $unscheduledPickup
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setIsUnscheduledPickup($unscheduledPickup);
+    public function setIsUnscheduledPickup(bool $unscheduledPickup): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the terms of trade.
@@ -31,7 +31,7 @@ public function setIsUnscheduledPickup($unscheduledPickup);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setTermsOfTrade($termsOfTrade);
+    public function setTermsOfTrade(string $termsOfTrade): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the terms of trade.
@@ -40,7 +40,7 @@ public function setTermsOfTrade($termsOfTrade);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setContentType($contentType);
+    public function setContentType(string $contentType): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the shipment timestamp.
@@ -49,7 +49,7 @@ public function setContentType($contentType);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setReadyAtTimestamp(\DateTime $readyAtTimestamp);
+    public function setReadyAtTimestamp(\DateTime $readyAtTimestamp): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the number of pieces.
@@ -58,7 +58,7 @@ public function setReadyAtTimestamp(\DateTime $readyAtTimestamp);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setNumberOfPieces($numberOfPieces);
+    public function setNumberOfPieces(int $numberOfPieces): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the currency.
@@ -67,7 +67,7 @@ public function setNumberOfPieces($numberOfPieces);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setCurrency($currencyCode);
+    public function setCurrency(string $currencyCode): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the description.
@@ -76,7 +76,7 @@ public function setCurrency($currencyCode);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setDescription($description);
+    public function setDescription(string $description): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the customs value.
@@ -85,7 +85,7 @@ public function setDescription($description);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setCustomsValue($customsValue);
+    public function setCustomsValue(float $customsValue): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the serviceType.
@@ -94,7 +94,7 @@ public function setCustomsValue($customsValue);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setServiceType($serviceType);
+    public function setServiceType(string $serviceType): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the payers account number.
@@ -103,7 +103,7 @@ public function setServiceType($serviceType);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setPayerAccountNumber($accountNumber);
+    public function setPayerAccountNumber(string $accountNumber): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the billing account number.
@@ -112,7 +112,7 @@ public function setPayerAccountNumber($accountNumber);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setBillingAccountNumber($accountNumber);
+    public function setBillingAccountNumber(string $accountNumber): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the insurance.
@@ -122,7 +122,15 @@ public function setBillingAccountNumber($accountNumber);
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setInsurance($insuranceValue, $insuranceCurrency);
+    public function setInsurance(float $insuranceValue, string $insuranceCurrency): ShipmentRequestBuilderInterface;
+
+    /**
+     * Adds the waybill document request flag.
+     *
+     * @param bool $isRequested
+     * @return ShipmentRequestBuilderInterface
+     */
+    public function setWaybillDocumentRequested(bool $isRequested): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the shipper.
@@ -139,15 +147,15 @@ public function setInsurance($insuranceValue, $insuranceCurrency);
      * @return ShipmentRequestBuilderInterface
      */
     public function setShipper(
-        $countryCode,
-        $postalCode,
-        $city,
+        string $countryCode,
+        string $postalCode,
+        string $city,
         array $streetLines,
-        $name,
-        $company,
-        $phone,
-        $email = null
-    );
+        string $name,
+        string $company,
+        string $phone,
+        string $email = null
+    ): ShipmentRequestBuilderInterface;
 
     /**
      * Sets the recipient.
@@ -164,15 +172,15 @@ public function setShipper(
      * @return ShipmentRequestBuilderInterface
      */
     public function setRecipient(
-        $countryCode,
-        $postalCode,
-        $city,
+        string $countryCode,
+        string $postalCode,
+        string $city,
         array $streetLines,
-        $name,
-        $company,
-        $phone,
-        $email = null
-    );
+        string $name,
+        string $company,
+        string $phone,
+        string $email = null
+    ): ShipmentRequestBuilderInterface;
 
     /**
      * Adds a package to the list of packages.
@@ -189,15 +197,15 @@ public function setRecipient(
      * @return ShipmentRequestBuilderInterface
      */
     public function addPackage(
-        $sequenceNumber,
-        $weight,
-        $weightUOM,
-        $length,
-        $width,
-        $height,
-        $dimensionsUOM,
-        $customerReferences
-    );
+        int $sequenceNumber,
+        float $weight,
+        string $weightUOM,
+        float $length,
+        float $width,
+        float $height,
+        string $dimensionsUOM,
+        string $customerReferences
+    ): ShipmentRequestBuilderInterface;
 
     /**
      * Set dry ice.
@@ -207,12 +215,12 @@ public function addPackage(
      *
      * @return ShipmentRequestBuilderInterface
      */
-    public function setDryIce($unCode, $weight);
+    public function setDryIce(string $unCode, float $weight): ShipmentRequestBuilderInterface;
 
     /**
      * Builds the shipment request instance.
      *
      * @return ShipmentRequestInterface
      */
-    public function build();
+    public function build(): ShipmentRequestInterface;
 }
diff --git a/src/Model/Request/Shipment/LabelOptions.php b/src/Model/Request/Shipment/LabelOptions.php
@@ -0,0 +1,26 @@
+<?php
+/**
+ * See LICENSE.md for license details.
+ */
+
+namespace Dhl\Express\Model\Request\Shipment;
+
+use Dhl\Express\Api\Data\Request\Shipment\LabelOptionsInterface;
+
+class LabelOptions implements LabelOptionsInterface
+{
+    /**
+     * @var bool
+     */
+    private $waybillDocumentRequested;
+
+    public function __construct(bool $waybillDocumentRequested)
+    {
+        $this->waybillDocumentRequested = $waybillDocumentRequested;
+    }
+
+    public function isWaybillDocumentRequested(): bool
+    {
+        return $this->waybillDocumentRequested;
+    }
+}