Merge pull request #5 from proclame/add-label-void

Add Void Shipment functionality with associated classes and documentation

Author: rgodiyal

demo/void-shipment.php

@@ -0,0 +1,28 @@
+<?php
+
+use RahulGodiyal\PhpUpsApiWrapper\Entity\VoidShipmentQuery;
+use RahulGodiyal\PhpUpsApiWrapper\VoidShipment;
+
+require_once('./vendor/autoload.php');
+
+$client_id = "xxxxxxxxxxxxxxxx"; // UPS Client ID
+$client_secret = "xxxxxxxxxxxxxxx"; // UPS Client Secret
+
+// Shipment identification number to void
+$shipmentIdentificationNumber = "1Zxxxxxxxxxxxxxxxx"; // Replace with actual shipment ID
+
+/********* Void Shipment Query *********/
+$query = new VoidShipmentQuery(); // optional
+$query->setTrackingNumber(""); // optional
+/********* End Void Shipment Query *********/
+
+/************ Void Shipment **********/
+$voidShipment = new VoidShipment();
+$voidShipmentRes = $voidShipment
+    ->setQuery($query) // optional
+    ->setShipmentIdentificationNumber($shipmentIdentificationNumber)
+//     ->setMode('PROD') // optional - uncomment for production
+    ->voidShipment($client_id, $client_secret);
+/************ End Void Shipment **********/
+
+echo '<pre>'; print_r($voidShipmentRes); echo '</pre>';

readme.md

@@ -10,9 +10,10 @@ Latest OAuth 2.0 Rest API Wrapper for UPS web services.
 3. [Address Validation](#address-validation)
 4. [Create Shipment | Shipping Label](#create-shipment--shipping-label)
 5. [Tracking API](#tracking-api)
-6. [Documentation](#documentation)
-7. [License](#license)
-8. [Support the Project](#support-the-project)
+6. [Void Shipment](#void-shipment)
+7. [Documentation](#documentation)
+8. [License](#license)
+9. [Support the Project](#support-the-project)
 
 <a name="requirements"></a>
 ## Requirements
@@ -282,6 +283,37 @@ echo '<pre>'; print_r($shipRes); echo '</pre>';
 
 ```
 
+<a name="void-shipment"></a>
+## Void Shipment
+```php
+<?php
+
+use RahulGodiyal\PhpUpsApiWrapper\Entity\VoidShipmentQuery;
+use RahulGodiyal\PhpUpsApiWrapper\VoidShipment;
+
+require_once('./vendor/autoload.php');
+
+$client_id = "******************************"; // UPS Client ID
+$client_secret = "*****************************************"; // UPS Client Secret
+
+// Shipment identification number to void
+$shipmentIdentificationNumber = "1Z12345E0205271688"; // Replace with actual shipment ID
+
+/********* Void Shipment Query *********/
+$query = new VoidShipmentQuery(); // optional
+$query->setTrackingNumber(""); // optional - if you want to include tracking number in the query
+/********* End Void Shipment Query *********/
+
+$voidShipment = new VoidShipment();
+$voidShipmentRes = $voidShipment
+    ->setQuery($query) // optional
+    ->setShipmentIdentificationNumber($shipmentIdentificationNumber)
+    // ->setMode('PROD') // optional - uncomment for production
+    ->voidShipment($client_id, $client_secret);
+
+echo '<pre>'; print_r($voidShipmentRes); echo '</pre>'; die();
+```
+
 <a name="tracking-api"></a>
 ## Tracking API
 ```php
@@ -328,4 +360,3 @@ PHP UPS API is licensed under [The MIT License (MIT)](LICENSE).
 If you enjoy using this package, please consider [buying me a coffee](https://www.buymeacoffee.com/ragod). Your support keeps the development going! ☕
 
 [![Buy Me a Coffee](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://www.buymeacoffee.com/ragod)
-

src/Entity/VoidShipmentQuery.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace RahulGodiyal\PhpUpsApiWrapper\Entity;
+
+class VoidShipmentQuery
+{
+    private string $trackingNumber = "";
+
+    public function exists()
+    {
+        if (!empty($this->trackingNumber)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    public function setTrackingNumber(string $trackingNumber): self
+    {
+        $this->trackingNumber = $trackingNumber;
+        return $this;
+    }
+
+    public function getTrackingNumber(): string
+    {
+        return $this->trackingNumber;
+    }
+
+    public function toArray(): array
+    {
+        if ($this->trackingNumber) {
+            return [
+                "trackingnumber" => $this->trackingNumber
+            ];
+        }
+
+        return [];
+    }
+}

src/VoidShipment.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace RahulGodiyal\PhpUpsApiWrapper;
+
+use RahulGodiyal\PhpUpsApiWrapper\Entity\VoidShipmentQuery;
+use RahulGodiyal\PhpUpsApiWrapper\Utils\HttpClient;
+
+class VoidShipment extends Auth
+{
+    private const VERSION = "v2409";
+
+    private VoidShipmentQuery $query;
+    private string $shipmentIdentificationNumber;
+    private object $apiResponse;
+
+    public function __construct()
+    {
+        $this->query = new VoidShipmentQuery();
+    }
+
+    public function setQuery(VoidShipmentQuery $query): self
+    {
+        $this->query = $query;
+        return $this;
+    }
+
+    public function getQuery(): VoidShipmentQuery
+    {
+        return $this->query;
+    }
+
+    public function setShipmentIdentificationNumber(string $shipmentIdentificationNumber): self
+    {
+        $this->shipmentIdentificationNumber = $shipmentIdentificationNumber;
+        return $this;
+    }
+
+    public function getShipmentIdentificationNumber(): string
+    {
+        return $this->shipmentIdentificationNumber;
+    }
+
+    public function voidShipment(string $client_id, string $client_secret): array
+    {
+        $auth = $this->authenticate($client_id, $client_secret);
+
+        if ($auth['status'] === 'fail') {
+            return $auth;
+        }
+
+        $access_token = $auth['access_token'];
+
+        $queryParams = "";
+        if ($this->query->exists()) {
+            $queryParams = "?" . http_build_query($this->query->toArray());
+        }
+
+        $httpClient = new HttpClient();
+        $httpClient->setHeader([
+            "Authorization: Bearer $access_token",
+            "Content-Type: application/json",
+            "transId: string",
+            "transactionSrc: testing"
+        ]);
+        $httpClient->setUrl($this->_getAPIBaseURL() . "/api/shipments/" . self::VERSION . "/void/cancel/" . $this->shipmentIdentificationNumber . $queryParams);
+        $httpClient->setMethod("DELETE");
+        $this->apiResponse = $res = $httpClient->fetch();
+
+        if (!isset($res->VoidShipmentResponse)) {
+            if (isset($res->response)) {
+                $error = $res->response->errors[0]->message;
+            } else {
+                $error = "Voiding shipment failed! Please try again.";
+            }
+            return ['status' => 'fail', 'msg' => $error];
+        }
+
+        if (!isset($res->VoidShipmentResponse->Status)) {
+            return ['status' => 'fail', 'msg' => "Invalid Request."];
+        }
+
+        return ['status' => 'success', 'data' => $res->VoidShipmentResponse];
+    }
+
+    public function setMode(string $mode): self
+    {
+        parent::setMode($mode);
+        return $this;
+    }
+
+    public function getResponse(): string
+    {
+        return json_encode($this->apiResponse);
+    }
+}