Merge pull request #89 from hm122/patch-2

Adjusts Tracking API, adds new attributes
gabrielbull · Mar 4, 2016 · 3ecce52 · 3ecce52
2 parents cb556d8 + 3549858
commit 3ecce52
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -228,6 +228,34 @@ Tracking parameters are:
  * `referenceNumber` The ability to track any UPS package or shipment by reference number. Reference numbers can be a purchase order number, job number, etc. Reference Number is supplied when generating a shipment.
  * `requestOption` Optional processing. For Mail Innovations the only valid options are Last Activity and All activity.
 
+<a name="tracking-class-example"></a>
+### Example using Reference Number with additional parameters
+
+```php
+$tracking = new Ups\Tracking($accessKey, $userId, $password);
+
+$tracking->setShipperNumber('SHIPPER NUMBER');
+
+$beginDate = new \DateTime('2016-01-01');
+$endDate = new \DateTime('2016-01-31');
+
+$tracking->setBeginDate($beginDate);
+$tracking->setEndDate($endDate);
+
+try {
+    $shipment = $tracking->trackByReference('REFERENCE NUMBER');
+
+    foreach($shipment->Package->Activity as $activity) {
+        var_dump($activity);
+    }
+
+} catch (Exception $e) {
+    var_dump($e);
+}
+```
+
+The parameters shipperNumber, beginDate and endDate are optional. Either of the parameters can be set individually. These parameters can help to narrow the search field when tracking by reference, since it might happen that the reference number used is not unique. When using tracking by tracking number these parameters are not needed since the tracking number is unique.
+
 <a name="rate-class"></a>
 ## Rate Class
 

diff --git a/src/Tracking.php b/src/Tracking.php
@@ -7,6 +7,7 @@
 use Psr\Log\LoggerInterface;
 use SimpleXMLElement;
 use stdClass;
+use DateTime;
 
 /**
  * Tracking API Wrapper.
@@ -41,6 +42,21 @@ class Tracking extends Ups
      */
     private $requestOption;
 
+    /**
+     * @var string
+     */
+    private $shipperNumber;
+
+    /**
+     * @var \DateTime
+     */
+    private $beginDate;
+
+    /**
+     * @var \DateTime
+     */
+    private $endDate;
+
     /**
      * @param string|null $accessKey UPS License Access Key
      * @param string|null $userId UPS User ID
@@ -127,6 +143,39 @@ public function trackByReference($referenceNumber, $requestOption = 'activity')
         }
     }
 
+    /**
+     * Set shipper number
+     *
+     * @param string $shipperNumber
+     *
+     */
+    public function setShipperNumber($shipperNumber)
+    {
+        $this->shipperNumber = $shipperNumber;
+    }
+
+    /**
+     * Set begin date
+     *
+     * @param string $beginDate
+     *
+     */
+    public function setBeginDate(DateTime $beginDate)
+    {
+        $this->beginDate = $beginDate;
+    }
+
+    /**
+     * Set end date
+     *
+     * @param string $endDate
+     *
+     */
+    public function setEndDate(DateTime $endDate)
+    {
+        $this->endDate = $endDate;
+    }
+
     /**
      * Check if tracking number is for mail innovations.
      *
@@ -221,6 +270,21 @@ private function createRequest()
         if (null !== $this->referenceNumber) {
             $trackRequest->appendChild($xml->createElement('ReferenceNumber'))->appendChild($xml->createElement('Value', $this->referenceNumber));
         }
+
+        if (null !== $this->shipperNumber) {
+            $trackRequest->appendChild($xml->createElement('ShipperNumber', $this->shipperNumber));
+        }
+
+        if (null !== $this->beginDate) {
+            $beginDate = $this->beginDate->format('Ymd');
+            $trackRequest->appendChild($xml->createElement('BeginDate', $beginDate));
+        }
+
+        if (null !== $this->endDate) {
+            $endDate = $this->endDate->format('Ymd');
+            $trackRequest->appendChild($xml->createElement('EndDate', $endDate));
+        }
+
         return $xml->saveXML();
     }