diff --git a/composer.json b/composer.json index 2f18026..7203d56 100644 --- 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 index 367fa5d..b351671 100644 --- 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 index 6991c68..e6c41b5 100644 --- 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 index b393eb2..8a9989b 100644 --- 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 index c2fd0cd..21f9f78 100644 --- a/src/Address.php +++ b/src/Address.php @@ -18,16 +18,19 @@ 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); } @@ -35,16 +38,14 @@ public function setAddress2(string|int $value): self /** * 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); } @@ -52,11 +53,9 @@ public function setAddress1(string|int $value): self /** * 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); } @@ -64,11 +63,9 @@ public function setCity(string|int $value): self /** * 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); } @@ -76,11 +73,9 @@ public function setState(string|int $value): self /** * 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); } @@ -88,28 +83,27 @@ public function setZip4(string|int $value): self /** * 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); } @@ -117,12 +111,9 @@ public function setFirmName(string|int $value): self /** * 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 index 81b38d9..c16b7a6 100644 --- 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 index 1f4dd31..81baf47 100644 --- 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,13 +37,9 @@ 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]; @@ -55,5 +47,7 @@ public function addZipCode($zip5, $zip4 = '', $id = null): void $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 new file mode 100644 index 0000000..fb1a2ef --- /dev/null +++ b/src/Enum/MailType.php @@ -0,0 +1,13 @@ +route = [ 'OriginZip' => $origin_zip, 'DestinationZip' => $destination_zip, ]; + + return $this; } } diff --git a/src/InternationalLabel.php b/src/InternationalLabel.php index cd7182c..bcbde09 100644 --- a/src/InternationalLabel.php +++ b/src/InternationalLabel.php @@ -2,17 +2,14 @@ namespace USPS; -/** - * Class InternationalLabel. - */ class InternationalLabel 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 = 'ExpressMailIntl'; /** - * @var array - route added so far. + * @var array route added so far. */ protected array $fields = []; @@ -20,8 +17,6 @@ class InternationalLabel extends USPSBase /** * Perform the API call. - * - * @return string */ public function createLabel(): string { @@ -52,8 +47,6 @@ public function createLabel(): string /** * Return the USPS confirmation/tracking number if we have one. - * - * @return string|bool */ public function getConfirmationNumber(): string|bool { @@ -70,8 +63,6 @@ public function getConfirmationNumber(): string|bool /** * Return the USPS label as a base64 encoded string. - * - * @return string|bool */ public function getLabelContents(): string|bool { @@ -88,8 +79,6 @@ public function getLabelContents(): string|bool /** * returns array of all fields added. - * - * @return array */ public function getPostFields(): array { @@ -99,25 +88,17 @@ public function getPostFields(): array /** * Add shipping contents. * - * @param $description - * @param $value - * @param $pounds - * @param $ounces - * @param int $quantity - * @param null $tarrifNumber - * @param null $countryOfOrigin - * - * @return InternationalLabel + * @return $this */ public function addContent( - $description, - $value, - $pounds, - $ounces, + string $description, + string $value, + string $pounds, + string $ounces, int $quantity = 1, - $tariffNumber = null, - $countryOfOrigin = null - ): self + string $tariffNumber = null, + string $countryOfOrigin = null + ): static { $this->contents['ItemDetail'][] = [ 'Description' => $description, @@ -135,19 +116,7 @@ public function addContent( /** * Set the from address. * - * @param string $firstName - * @param string $lastName - * @param string $company - * @param string $address - * @param string $city - * @param string $state - * @param string $zip - * @param string|null $address2 - * @param string|null $zip4 - * @param string|null $phone - * @param string|null $middleName - * - * @return InternationalLabel + * @return $this */ public function setFromAddress( string $firstName, @@ -161,7 +130,7 @@ public function setFromAddress( string $zip4 = null, string $phone = null, string $middleName = null - ): self + ): static { $this->setField(5, 'FromFirstName', $firstName); $this->setField(6, 'FromMiddleInitial', $middleName); @@ -181,24 +150,7 @@ public function setFromAddress( /** * Set the to address. * - * @param string $firstName - * @param string $lastName - * @param string $company - * @param string $address - * @param string $city - * @param string $province - * @param string $country - * @param string $zip - * @param string|null $address2 - * @param string $poBoxFlag - * @param string|null $phone - * @param string|null $fax - * @param string|null $email - * - * @return InternationalLabel - * - * @internal param string $state - * @internal param string $zip4 + * @return $this */ public function setToAddress( string $firstName, @@ -214,7 +166,7 @@ public function setToAddress( string $phone = null, string $fax = null, string $email = null - ): self + ): static { $this->setField(16, 'ToFirstName', $firstName); $this->setField(17, 'ToLastName', $lastName); @@ -237,13 +189,9 @@ public function setToAddress( * Set any other required string make sure you set the correct position as well * as the position of the items matters. * - * @param int $position - * @param string $key - * @param mixed $value - * - * @return InternationalLabel + * @return $this */ - public function setField(int $position, string $key, mixed $value): self + public function setField(int $position, string $key, mixed $value): static { $this->fields[$position.':'.$key] = $value; @@ -255,9 +203,9 @@ public function setField(int $position, string $key, mixed $value): self * * @param float|int $weight * - * @return InternationalLabel + * @return $this */ - public function setWeightOunces(float|int $weight): self + public function setWeightOunces(float|int $weight): static { $this->setField(33, 'GrossOunces', $weight); @@ -269,9 +217,9 @@ public function setWeightOunces(float|int $weight): self * * @param float|int $weight * - * @return InternationalLabel + * @return $this */ - public function setWeightPounds(float|int $weight): self + public function setWeightPounds(float|int $weight): static { $this->setField(32, 'GrossPounds', $weight); diff --git a/src/OpenDistributeLabel.php b/src/OpenDistributeLabel.php index 788a766..ca703ac 100644 --- a/src/OpenDistributeLabel.php +++ b/src/OpenDistributeLabel.php @@ -8,18 +8,16 @@ class OpenDistributeLabel 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 = 'OpenDistributePriorityV2'; /** - * @var array - route added so far. + * @var array route added so far. */ protected array $fields = []; /** * Perform the API call. - * - * @return string */ public function createLabel(): string { @@ -45,10 +43,8 @@ public function createLabel(): string /** * Return the USPS confirmation/tracking number if we have one. - * - * @return string|bool */ - public function getConfirmationNumber() + public function getConfirmationNumber(): string|bool { $response = $this->getArrayResponse(); // Check to make sure we have it @@ -63,10 +59,8 @@ public function getConfirmationNumber() /** * Return the USPS label as a base64 encoded string. - * - * @return string|bool */ - public function getLabelContents() + public function getLabelContents(): string|bool { $response = $this->getArrayResponse(); @@ -82,10 +76,8 @@ public function getLabelContents() /** * returns array of all fields added. - * - * @return array */ - public function getPostFields() + public function getPostFields(): array { return $this->fields; } @@ -93,29 +85,20 @@ public function getPostFields() /** * Set the from address. * - * @param string $firstName - * @param string $lastName - * @param string $company - * @param string $address - * @param string $city - * @param string $state - * @param string $zip - * @param string $address2 - * @param string $zip4 - * - * @return object + * @return $this */ public function setFromAddress( - $firstName, - $lastName, - $company, - $address, - $city, - $state, - $zip, - $address2 = null, - $zip4 = null - ) { + string $firstName, + string $lastName, + string $company, + string $address, + string $city, + string $state, + string $zip, + string $address2 = null, + string $zip4 = null + ): static + { $this->setField(5, 'FromName', trim($firstName.' '.$lastName)); $this->setField(7, 'FromFirm', $company); $this->setField(8, 'FromAddress1', $address2); @@ -131,17 +114,17 @@ public function setFromAddress( /** * Set the to address. * - * @param string $company - * @param string $address - * @param string $city - * @param string $state - * @param string $zip - * @param string $address2 - * @param string $zip4 - * - * @return object + * @return $this */ - public function setToAddress($company, $address, $city, $state, $zip, $address2 = null, $zip4 = null) + public function setToAddress( + string $company, + string $address, + string $city, + string $state, + string $zip, + string $address2 = null, + string $zip4 = null + ): static { $this->setField(15, 'ToFacilityName', $company); $this->setField(18, 'ToFacilityAddress1', $address2); @@ -157,11 +140,9 @@ public function setToAddress($company, $address, $city, $state, $zip, $address2 /** * Set package weight in ounces. * - * @param $weight - * * @return $this */ - public function setWeightOunces($weight) + public function setWeightOunces(int|string $weight): static { $this->setField(38, 'WeightInOunces', $weight); @@ -171,11 +152,9 @@ public function setWeightOunces($weight) /** * Set package weight in ounces. * - * @param $weight - * * @return $this */ - public function setWeightPounds($weight) + public function setWeightPounds(int|string $weight): static { $this->setField(37, 'WeightInPounds', $weight); @@ -186,13 +165,9 @@ public function setWeightPounds($weight) * Set any other requried string make sure you set the correct position as well * as the position of the items matters. * - * @param int $position - * @param string $key - * @param string $value - * - * @return object + * @return $this */ - public function setField($position, $key, $value) + public function setField(int $position, string $key, string $value): static { $this->fields[$position.':'.$key] = $value; @@ -201,10 +176,8 @@ public function setField($position, $key, $value) /** * Add missing required elements. - * - * @return void */ - protected function addMissingRequired() + protected function addMissingRequired(): void { $required = [ '1:Revision' => '', diff --git a/src/PriorityLabel.php b/src/PriorityLabel.php index 48f1aed..e320a35 100644 --- a/src/PriorityLabel.php +++ b/src/PriorityLabel.php @@ -8,18 +8,16 @@ class PriorityLabel 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 = 'ExpressMailLabel'; /** - * @var array - route added so far. + * @var array route added so far. */ protected array $fields = []; /** * Perform the API call. - * - * @return string */ public function createLabel(): string { @@ -45,8 +43,6 @@ public function createLabel(): string /** * Return the USPS confirmation/tracking number if we have one. - * - * @return string|bool */ public function getConfirmationNumber(): string|bool { @@ -63,8 +59,6 @@ public function getConfirmationNumber(): string|bool /** * Return the USPS label as a base64 encoded string. - * - * @return string|bool */ public function getLabelContents(): string|bool { @@ -81,8 +75,6 @@ public function getLabelContents(): string|bool /** * Return the USPS receipt as a base64 encoded string. - * - * @return string|bool */ public function getReceiptContents(): string|bool { @@ -99,8 +91,6 @@ public function getReceiptContents(): string|bool /** * returns array of all fields added. - * - * @return array */ public function getPostFields(): array { @@ -110,31 +100,20 @@ public function getPostFields(): array /** * Set the from address. * - * @param string $firstName - * @param string $lastName - * @param string $company - * @param string $address - * @param string $city - * @param string $state - * @param string $zip - * @param string $address2 - * @param string $zip4 - * @param string $phone - * - * @return PriorityLabel + * @return $this */ public function setFromAddress( - $firstName, - $lastName, - $company, - $address, - $city, - $state, - $zip, - $address2 = null, - $zip4 = null, - $phone = null - ): self + string $firstName, + string $lastName, + string $company, + string $address, + string $city, + string $state, + string $zip, + string $address2 = null, + string $zip4 = null, + string $phone = null + ): static { $this->setField(5, 'FromFirstName', $firstName); $this->setField(6, 'FromLastName', $lastName); @@ -153,31 +132,20 @@ public function setFromAddress( /** * Set the to address. * - * @param string $firstName - * @param string $lastName - * @param string $company - * @param string $address - * @param string $city - * @param string $state - * @param string $zip - * @param string $address2 - * @param string $zip4 - * @param string $phone - * - * @return PriorityLabel + * @return $this */ public function setToAddress( - $firstName, - $lastName, - $company, - $address, - $city, - $state, - $zip, - $address2 = null, - $zip4 = null, - $phone = null - ): self + string $firstName, + string $lastName, + string $company, + string $address, + string $city, + string $state, + string $zip, + string $address2 = null, + string $zip4 = null, + string $phone = null + ): static { $this->setField(15, 'ToFirstName', $firstName); $this->setField(16, 'ToLastName', $lastName); @@ -196,11 +164,9 @@ public function setToAddress( /** * Set package weight in ounces. * - * @param $weight - * - * @return PriorityLabel + * @return $this */ - public function setWeightOunces($weight): self + public function setWeightOunces(string $weight): static { $this->setField(25, 'WeightInOunces', $weight); @@ -211,13 +177,9 @@ public function setWeightOunces($weight): self * Set any other requried string make sure you set the correct position as well * as the position of the items matters. * - * @param int $position - * @param string $key - * @param string $value - * - * @return PriorityLabel + * @return $this */ - public function setField($position, $key, $value): self + public function setField(int $position, string $key, string $value): static { $this->fields[$position.':'.$key] = $value; @@ -226,8 +188,6 @@ public function setField($position, $key, $value): self /** * Add missing required elements. - * - * @return void */ protected function addMissingRequired(): void { diff --git a/src/Rate.php b/src/Rate.php index bab2782..3a2424e 100644 --- a/src/Rate.php +++ b/src/Rate.php @@ -21,59 +21,49 @@ class Rate extends USPSBase /** * Perform the API call. - * - * @param int $timeout Time-out in seconds. - * - * @return string */ - public function getRate($timeout = 60) + public function getRate(int $timeout = 60): string { - return $this->doRequest(NULL, $timeout); + return $this->doRequest(null, $timeout); } /** * returns array of all packages added so far. - * - * @return array */ - public function getPostFields() + public function getPostFields(): array { return $this->packages; } /** * sets the type of call to perform domestic or international. - * - * @param $status - * - * @return array */ - public function setInternationalCall($status) + public function setInternationalCall(bool $status): array { $this->apiVersion = $status === true ? 'IntlRateV2' : 'RateV4'; } /** * Add other option for International & Insurance. - * - * @param string|int $key - * @param string|int $value */ - public function addExtraOption($key, $value) + public function addExtraOption(string|int $key, mixed $value): static { $this->packages[$key][] = $value; + + return $this; } /** * Add Package to the stack. * - * @param RatePackage $data - * @param string $id the address unique id + * @param string|null $id the address unique id */ - public function addPackage(RatePackage $data, $id = null) + public function addPackage(RatePackage $data, string $id = null): static { $packageId = $id !== null ? $id : ((count($this->packages) + 1)); $this->packages['Package'][] = array_merge(['@attributes' => ['ID' => $packageId]], $data->getPackageInfo()); + + return $this; } } diff --git a/src/RatePackage.php b/src/RatePackage.php index 3008ee8..d0b8526 100644 --- a/src/RatePackage.php +++ b/src/RatePackage.php @@ -2,6 +2,9 @@ namespace USPS; +use USPS\Enum\MailType; +use USPS\Enum\ServiceType; + /** * USPS Rate Package * used by the ups rate class to create packages represented as objects. @@ -14,41 +17,16 @@ class RatePackage extends Rate * @var array - list of all packages added so far */ protected array $packageInfo = []; - /** - * Services constants. - */ - const SERVICE_FIRST_CLASS = 'FIRST CLASS'; - const SERVICE_FIRST_CLASS_COMMERCIAL = 'FIRST CLASS COMMERCIAL'; - const SERVICE_FIRST_CLASS_HFP_COMMERCIAL = 'FIRST CLASS HFP COMMERCIAL'; - const SERVICE_PRIORITY = 'PRIORITY'; - const SERVICE_PRIORITY_COMMERCIAL = 'PRIORITY COMMERCIAL'; - const SERVICE_PRIORITY_HFP_COMMERCIAL = 'PRIORITY HFP COMMERCIAL'; - const SERVICE_EXPRESS = 'EXPRESS'; - const SERVICE_EXPRESS_COMMERCIAL = 'EXPRESS COMMERCIAL'; - const SERVICE_EXPRESS_SH = 'EXPRESS SH'; - const SERVICE_EXPRESS_SH_COMMERCIAL = 'EXPRESS SH COMMERCIAL'; - const SERVICE_EXPRESS_HFP = 'EXPRESS HFP'; - const SERVICE_EXPRESS_HFP_COMMERCIAL = 'EXPRESS HFP COMMERCIAL'; - const SERVICE_PARCEL = 'PARCEL'; - const SERVICE_MEDIA = 'MEDIA'; - const SERVICE_LIBRARY = 'LIBRARY'; - const SERVICE_ALL = 'ALL'; - const SERVICE_ONLINE = 'ONLINE'; /** * First class mail type * required when you use one of the first class services. */ - const MAIL_TYPE_LETTER = 'LETTER'; - const MAIL_TYPE_FLAT = 'FLAT'; - const MAIL_TYPE_PARCEL = 'PARCEL'; - const MAIL_TYPE_POSTCARD = 'POSTCARD'; - const MAIL_TYPE_PACKAGE = 'PACKAGE'; - const MAIL_TYPE_PACKAGE_SERVICE = 'PACKAGE SERVICE'; + /** * Container constants. */ - const CONTAINER_VARIABLE = 'VARIABLE'; - const CONTAINER_FLAT_RATE_ENVELOPE = 'FLAT RATE ENVELOPE'; + public const CONTAINER_VARIABLE = 'VARIABLE'; + public const CONTAINER_FLAT_RATE_ENVELOPE = 'FLAT RATE ENVELOPE'; const CONTAINER_PADDED_FLAT_RATE_ENVELOPE = 'PADDED FLAT RATE ENVELOPE'; const CONTAINER_LEGAL_FLAT_RATE_ENVELOPE = 'LEGAL FLAT RATE ENVELOPE'; const CONTAINER_SM_FLAT_RATE_ENVELOPE = 'SM FLAT RATE ENVELOPE'; @@ -71,35 +49,29 @@ class RatePackage extends Rate /** * Set the service property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setService(string|int $value): self + public function setService(ServiceType $value): static { - return $this->setField('Service', $value); + return $this->setField('Service', $value->value); } /** * Set the first class mail type property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setFirstClassMailType(string|int $value): self + public function setFirstClassMailType(MailType $value): static { - return $this->setField('FirstClassMailType', $value); + return $this->setField('FirstClassMailType', $value->value); } /** * Set the zip origin property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setZipOrigination(string|int $value): self + public function setZipOrigination(string|int $value): static { return $this->setField('ZipOrigination', $value); } @@ -107,11 +79,9 @@ public function setZipOrigination(string|int $value): self /** * Set the zip destination property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setZipDestination(string|int $value): self + public function setZipDestination(string|int $value): static { return $this->setField('ZipDestination', $value); } @@ -119,11 +89,9 @@ public function setZipDestination(string|int $value): self /** * Set the pounds property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setPounds(string|int $value): self + public function setPounds(string|int $value): static { return $this->setField('Pounds', $value); } @@ -131,11 +99,9 @@ public function setPounds(string|int $value): self /** * Set the ounces property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setOunces(string|int $value): self + public function setOunces(string|int $value): static { return $this->setField('Ounces', $value); } @@ -143,11 +109,9 @@ public function setOunces(string|int $value): self /** * Set the container property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setContainer(string|int $value): self + public function setContainer(string|int $value): static { return $this->setField('Container', $value); } @@ -155,11 +119,9 @@ public function setContainer(string|int $value): self /** * Set the size property. * - * @param string|int $value - * - * @return RatePackage + * @return $this */ - public function setSize(string|int $value): self + public function setSize(string|int $value): static { return $this->setField('Size', $value); } @@ -167,12 +129,9 @@ public function setSize(string|int $value): self /** * Add an element to the stack. * - * @param string|int $key - * @param mixed $value - * - * @return RatePackage + * @return $this */ - public function setField(string|int $key, mixed $value): self + public function setField(string|int $key, mixed $value): static { $this->packageInfo[ucwords($key)] = $value; @@ -181,8 +140,6 @@ public function setField(string|int $key, mixed $value): self /** * Returns a list of all the info we gathered so far in the current package object. - * - * @return array */ public function getPackageInfo(): array { diff --git a/src/ServiceDeliveryCalculator.php b/src/ServiceDeliveryCalculator.php index 656098b..e57dd33 100644 --- a/src/ServiceDeliveryCalculator.php +++ b/src/ServiceDeliveryCalculator.php @@ -8,18 +8,16 @@ class ServiceDeliveryCalculator 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 = 'SDCGetLocations'; /** - * @var array - route added so far. + * @var array route added so far. */ protected array $route = []; /** * Perform the API call. - * - * @return string */ public function getServiceDeliveryCalculation(): string { @@ -28,8 +26,6 @@ public function getServiceDeliveryCalculation(): string /** * returns array of all routes added so far. - * - * @return array */ public function getPostFields(): array { @@ -37,7 +33,7 @@ public function getPostFields(): array } /** - * @param $mail_class integer from 0 to 6 indicating the class of mail. + * @param int $mailClass integer from 0 to 6 indicating the class of mail. * “0” = All Mail Classes * “1” = Express Mail * “2” = Priority Mail @@ -45,24 +41,31 @@ public function getPostFields(): array * “4” = Standard Mail * “5” = Periodicals * “6” = Package Services - * @param $origin_zip 5 digit zip code. - * @param $destination_zip 5 digit zip code. - * @param null $accept_date string in the format dd-mmm-yyyy. - * @param null $accept_time string in the format HHMM. + * @param string $originZip 5 digit zip code. + * @param string $destinationZip 5 digit zip code. + * @param string|null $acceptDate string in the format dd-mmm-yyyy. + * @param string|null $acceptTime string in the format HHMM. + * + * @return $this */ - public function addRoute($mail_class, $origin_zip, $destination_zip, $accept_date = null, $accept_time = null): void + public function addRoute(int $mailClass, string $originZip, string $destinationZip, string $acceptDate = null, string $acceptTime = null): static { $route = [ - 'MailClass' => $mail_class, - 'OriginZIP' => $origin_zip, - 'DestinationZIP' => $destination_zip, + 'MailClass' => $mailClass, + 'OriginZIP' => $originZip, + 'DestinationZIP' => $destinationZip, ]; - if (!empty($accept_date)) { - $route['AcceptDate'] = $accept_date; + + if ($acceptDate !== null) { + $route['AcceptDate'] = $acceptDate; } - if (!empty($accept_time)) { - $route['AcceptTime'] = $accept_time; + + if ($acceptTime !== null) { + $route['AcceptTime'] = $acceptTime; } + $this->route = $route; + + return $this; } } diff --git a/src/TrackConfirm.php b/src/TrackConfirm.php index 7f84206..2b781fb 100644 --- a/src/TrackConfirm.php +++ b/src/TrackConfirm.php @@ -8,23 +8,23 @@ class TrackConfirm 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 = 'TrackV2'; /** - * @var string - revision version for including additional response fields + * @var string revision version for including additional response fields */ protected string $revision = ''; /** - * @var string - User IP address. Required when TrackFieldRequest[Revision=’1’]. + * @var string User IP address. Required when TrackFieldRequest[Revision=’1’]. */ protected string $clientIp = ''; /** - * @var string - Internal User Identification. Required when TrackFieldRequest[Revision=’1’]. + * @var string Internal User Identification. Required when TrackFieldRequest[Revision=’1’]. */ protected string $sourceId = ''; /** - * @var array - list of all packages added so far + * @var array list of all packages added so far */ protected array $packages = []; @@ -35,8 +35,6 @@ public function getEndpoint(): string /** * Perform the API call. - * - * @return string */ public function getTracking(): string { @@ -45,8 +43,6 @@ public function getTracking(): string /** * returns array of all packages added so far. - * - * @return array */ public function getPostFields(): array { @@ -63,11 +59,13 @@ public function getPostFields(): array * * @param string $id the address unique id * - * @return void + * @return $this */ - public function addPackage(string $id): void + public function addPackage(string $id): static { $this->packages['TrackID'][] = ['@attributes' => ['ID' => $id]]; + + return $this; } /** @@ -75,9 +73,9 @@ public function addPackage(string $id): void * * @param string|int $value * - * @return TrackConfirm + * @return $this */ - public function setRevision(string|int $value): self + public function setRevision(string|int $value): static { $this->revision = (string)$value; @@ -87,13 +85,11 @@ public function setRevision(string|int $value): self /** * Set the ClientIp value * - * @param string $value - * - * @return TrackConfirm + * @return $this */ - public function setClientIp($value): self + public function setClientIp(string $value): static { - $this->clientIp = (string)$value; + $this->clientIp = $value; return $this; } @@ -101,13 +97,11 @@ public function setClientIp($value): self /** * Set the SourceId value * - * @param string $value - * - * @return TrackConfirm + * @return $this */ - public function setSourceId($value): self + public function setSourceId(string $value): static { - $this->sourceId = (string)$value; + $this->sourceId = $value; return $this; } diff --git a/src/USPSBase.php b/src/USPSBase.php index f2d300a..7fd3af8 100644 --- a/src/USPSBase.php +++ b/src/USPSBase.php @@ -149,11 +149,11 @@ public function setApiVersion($version): self /** * Set whether we are in a test mode or not. * - * @param bool $value + * @return $this */ - public function setTestMode(bool $value): self + public function setTestMode(bool $value): static { - self::$testMode = (bool) $value; + self::$testMode = $value; return $this; } @@ -327,7 +327,7 @@ public function setResponse(mixed $response = ''): self /** * Get the response data. */ - public function getResponse(): mixed + public function getResponse(): string { return $this->response; } diff --git a/src/ZipCodeLookup.php b/src/ZipCodeLookup.php index 9ced8ea..646326b 100644 --- a/src/ZipCodeLookup.php +++ b/src/ZipCodeLookup.php @@ -2,27 +2,19 @@ namespace USPS; -/** - * USPS Zip code lookup by city/state - * used to find a zip code by city/state lookup. - * - * @since 1.0 - */ class ZipCodeLookup 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 = 'ZipCodeLookup'; /** - * @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 { @@ -31,8 +23,6 @@ public function lookup(): string /** * returns array of all addresses added so far. - * - * @return array */ public function getPostFields(): array { @@ -44,8 +34,10 @@ public function getPostFields(): array * * @param Address $data * @param string $id the address unique id + * + * @return $this */ - public function addAddress(Address $data, $id = null): self + public function addAddress(Address $data, string $id = null): static { $packageId = $id !== null ? $id : ((count($this->addresses) + 1));