Set return typing and updated examples

GeNyaa · Feb 14, 2023 · fcceaf6 · fcceaf6
1 parent c3c07ea
commit fcceaf6
Show file tree

Hide file tree

Showing 19 changed files with 292 additions and 437 deletions.
diff --git a/composer.json b/composer.json
@@ -25,7 +25,7 @@
     }
   ],
   "require":     {
-    "php":      ">=8.0",
+    "php": "^8.1",
     "ext-curl": "*"
   },
   "autoload":    {

diff --git a/demos/domestic_rate.php b/demos/domestic_rate.php
@@ -2,6 +2,8 @@
 
 require_once('autoload.php');
 
+use USPS\Enum\MailType;
+use USPS\Enum\ServiceType;
 use USPS\RatePackage;
 
 // Initiate and set the username provided from usps
@@ -15,8 +17,8 @@
 // to set them as the example below
 // set the RatePackage for more info about the constants
 $package = (new RatePackage())
-    ->setService(RatePackage::SERVICE_FIRST_CLASS)
-    ->setFirstClassMailType(RatePackage::MAIL_TYPE_LETTER)
+    ->setService(ServiceType::FIRST_CLASS)
+    ->setFirstClassMailType(MailType::LETTER)
     ->setZipOrigination(91601)
     ->setZipDestination(91730)
     ->setPounds(0)

diff --git a/demos/open_label.php b/demos/open_label.php
@@ -3,13 +3,25 @@
 require_once('autoload.php');
 
 // Initiate and set the username provided from usps
-$label = new \USPS\OpenDistributeLabel('xxxx');
+$label = (new \USPS\OpenDistributeLabel('xxxx'))
+    ->setFromAddress(
+        'John',
+        'Doe',
+        '',
+        '5161 Lankershim Blvd',
+        'North Hollywood',
+        'CA',
+        '91601',
+        '# 204'
+    )->setToAddress(
+        'Vincent Gabriel',
+        '5440 Tujunga Ave',
+        'North Hollywood',
+        'CA',
+        '91601',
+        '707'
+    )->setWeightOunces(1);
 
-$label->setFromAddress('John', 'Doe', '', '5161 Lankershim Blvd', 'North Hollywood', 'CA', '91601', '# 204');
-$label->setToAddress('Vincent Gabriel', '5440 Tujunga Ave', 'North Hollywood', 'CA', '91601', '707');
-$label->setWeightOunces(1);
-
-// Perform the request and return result
 $label->createLabel();
 
 print_r($label->getPostData());

diff --git a/demos/priority_label.php b/demos/priority_label.php
@@ -6,12 +6,28 @@
 $label = new \USPS\PriorityLabel('xxxx');
 
 // During test mode this seems not to always work as expected
-$label->setTestMode(true);
-
-$label->setFromAddress('John', 'Doe', '', '5161 Lankershim Blvd', 'North Hollywood', 'CA', '91601', '# 204', '', '8882721214');
-$label->setToAddress('Vincent', 'Gabriel', '', '230 Murray St', 'New York', 'NY', '10282');
-$label->setWeightOunces(1);
-$label->setField(36, 'LabelDate', '03/12/2014');
+$label->setTestMode(true)
+    ->setFromAddress(
+        'John',
+        'Doe',
+        '',
+        '5161 Lankershim Blvd',
+        'North Hollywood',
+        'CA',
+        '91601',
+        '# 204',
+        '',
+        '8882721214'
+    )->setToAddress(
+        'Vincent',
+        'Gabriel',
+        '',
+        '230 Murray St',
+        'New York',
+        'NY',
+        '10282'
+    )->setWeightOunces(1)
+    ->setField(36, 'LabelDate', '03/12/2014');
 
 // Perform the request and return result
 $label->createLabel();

diff --git a/src/Address.php b/src/Address.php
@@ -18,111 +18,102 @@ class Address
     /**
      * Set the address2 property.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setAddress(string|int $value): self
+    public function setAddress(string|int $value): static
     {
         return $this->setAddress2($value);
     }
 
-    public function setAddress2(string|int $value): self
+    /**
+     * Set the address2 property.
+     *
+     * @return $this
+     */
+    public function setAddress2(string|int $value): static
     {
         return $this->setField('Address2', $value);
     }
 
     /**
      * Set the address1 property usually the apt or suit number.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setApt(string|int $value): self
+    public function setApt(string|int $value): static
     {
         return $this->setAddress1($value);
     }
 
-    public function setAddress1(string|int $value): self
+    public function setAddress1(string|int $value): static
     {
         return $this->setField('Address1', $value);
     }
 
     /**
      * Set the city property.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setCity(string|int $value): self
+    public function setCity(string|int $value): static
     {
         return $this->setField('City', $value);
     }
 
     /**
      * Set the state property.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setState(string|int $value): self
+    public function setState(string|int $value): static
     {
         return $this->setField('State', $value);
     }
 
     /**
      * Set the zip4 property - zip code value represented by 4 integers.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setZip4(string|int $value): self
+    public function setZip4(string|int $value): static
     {
         return $this->setField('Zip4', $value);
     }
 
     /**
      * Set the zip5 property - zip code value represented by 5 integers.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setZip5(string|int $value): self
+    public function setZip5(string|int $value): static
     {
         return $this->setField('Zip5', $value);
     }
 
-    public function setZipcode(string|int $value): self
+    /**
+     * @return $this
+     */
+    public function setZipcode(string|int $value): static
     {
         return $this->setZip5($value);
     }
 
     /**
-     * Set the firmname property.
+     * Set the firm name property.
      *
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setFirmName(string|int $value): self
+    public function setFirmName(string|int $value): static
     {
         return $this->setField('FirmName', $value);
     }
 
     /**
      * Add an element to the stack.
      *
-     * @param string|int $key
-     * @param string|int $value
-     *
-     * @return Address
+     * @return $this
      */
-    public function setField(string|int $key, string|int $value): self
+    public function setField(string|int $key, string|int $value): static
     {
         $this->addressInfo[ucwords($key)] = $value;
 
@@ -131,8 +122,6 @@ public function setField(string|int $key, string|int $value): self
 
     /**
      * Returns a list of all the info we gathered so far in the current address object.
-     *
-     * @return array
      */
     public function getAddressInfo(): array
     {

diff --git a/src/AddressVerify.php b/src/AddressVerify.php
@@ -25,8 +25,6 @@ class AddressVerify extends USPSBase
 
     /**
      * Perform the API call to verify the address.
-     *
-     * @return string
      */
     public function verify(): string
     {
@@ -35,8 +33,6 @@ public function verify(): string
 
     /**
      * returns array of all addresses added so far.
-     *
-     * @return array
      */
     public function getPostFields(): array
     {
@@ -47,10 +43,9 @@ public function getPostFields(): array
     /**
      * Add Address to the stack.
      *
-     * @param Address $data
-     * @param ?string  $id   the address unique id
+     * @return $this
      */
-    public function addAddress(Address $data, string $id = null): self
+    public function addAddress(Address $data, string $id = null): static
     {
         $packageId = $id !== null ? $id : ((count($this->addresses) + 1));
 
@@ -62,11 +57,9 @@ public function addAddress(Address $data, string $id = null): self
     /**
      * Set the revision value
      *
-     * @param string|int $value
-     *
-     * @return AddressVerify
+     * @return $this
      */
-    public function setRevision(string|int $value): self
+    public function setRevision(string|int $value): static
     {
         $this->revision = (string)$value;
 

diff --git a/src/CityStateLookup.php b/src/CityStateLookup.php
@@ -10,18 +10,16 @@
 class CityStateLookup extends USPSBase
 {
     /**
-     * @var string - the api version used for this type of call
+     * @var string the api version used for this type of call
      */
     protected string $apiVersion = 'CityStateLookup';
     /**
-     * @var array - list of all addresses added so far
+     * @var array list of all addresses added so far
      */
     protected array $addresses = [];
 
     /**
      * Perform the API call.
-     *
-     * @return string
      */
     public function lookup(): string
     {
@@ -30,8 +28,6 @@ public function lookup(): string
 
     /**
      * returns array of all addresses added so far.
-     *
-     * @return array
      */
     public function getPostFields(): array
     {
@@ -41,19 +37,17 @@ public function getPostFields(): array
     /**
      * Add zip zip code to the stack.
      *
-     * @param string $zip5 - zip code 5 integers
-     * @param string $zip4 - optional 4 integers zip code
-     * @param string $id   the address unique id
-     *
-     * @return void
+     * @return $this
      */
-    public function addZipCode($zip5, $zip4 = '', $id = null): void
+    public function addZipCode(string $zip5, string $zip4 = '', string $id = null): static
     {
         $packageId = $id !== null ? $id : ((count($this->addresses) + 1));
         $zipCodes = ['Zip5' => $zip5];
         if ($zip4) {
             $zipCodes['Zip4'] = $zip4;
         }
         $this->addresses['ZipCode'][] = array_merge(['@attributes' => ['ID' => $packageId]], $zipCodes);
+
+        return $this;
     }
 }
diff --git a/src/Enum/MailType.php b/src/Enum/MailType.php
@@ -0,0 +1,13 @@
+<?php declare(strict_types=1);
+
+namespace USPS\Enum;
+
+enum MailType: string
+{
+    case LETTER = 'LETTER';
+    case FLAT = 'FLAT';
+    case PARCEL = 'PARCEL';
+    case POSTCARD = 'POSTCARD';
+    case PACKAGE = 'PACKAGE';
+    case PACKAGE_SERVICE = 'PACKAGE SERVICE';
+}
diff --git a/src/Enum/ServiceType.php b/src/Enum/ServiceType.php
@@ -0,0 +1,24 @@
+<?php declare(strict_types=1);
+
+namespace USPS\Enum;
+
+enum ServiceType: string
+{
+    case FIRST_CLASS = 'FIRST CLASS';
+    case FIRST_CLASS_COMMERCIAL = 'FIRST CLASS COMMERCIAL';
+    case FIRST_CLASS_HFP_COMMERCIAL = 'FIRST CLASS HFP COMMERCIAL';
+    case PRIORITY = 'PRIORITY';
+    case PRIORITY_COMMERCIAL = 'PRIORITY COMMERCIAL';
+    case PRIORITY_HFP_COMMERCIAL = 'PRIORITY HFP COMMERCIAL';
+    case EXPRESS = 'EXPRESS';
+    case EXPRESS_COMMERCIAL = 'EXPRESS COMMERCIAL';
+    case EXPRESS_SH = 'EXPRESS SH';
+    case EXPRESS_SH_COMMERCIAL = 'EXPRESS SH COMMERCIAL';
+    case EXPRESS_HFP = 'EXPRESS HFP';
+    case EXPRESS_HFP_COMMERCIAL = 'EXPRESS HFP COMMERCIAL';
+    case PARCEL = 'PARCEL';
+    case MEDIA = 'MEDIA';
+    case LIBRARY = 'LIBRARY';
+    case ALL = 'ALL';
+    case ONLINE = 'ONLINE';
+}