diff --git a/README.md b/README.md index fd2a72f7..2c2ab7d1 100644 --- a/README.md +++ b/README.md @@ -13,20 +13,23 @@ Tracking API, Shipping API, Rating API and Time in Transit API. Feel free to con 1. [Requirements](#requirements) 2. [Installation](#installation) -3. [QuantumView Class](#quantumview-class) +3. [Address Validation Class](#addressvalidation-class) + * [Example](#addressvalidation-class-example) + * [Parameters](#addressvalidation-class-parameters) +4. [QuantumView Class](#quantumview-class) * [Example](#quantumview-class-example) * [Parameters](#quantumview-class-parameters) -4. [Tracking Class](#tracking-class) +5. [Tracking Class](#tracking-class) * [Example](#tracking-class-example) * [Parameters](#tracking-class-parameters) -5. [Rate Class](#rate-class) +6. [Rate Class](#rate-class) * [Example](#rate-class-example) * [Parameters](#rate-class-parameters) -6. [TimeInTransit Class](#timeintransit-class) +7. [TimeInTransit Class](#timeintransit-class) * [Example](#timeintransit-class-example) * [Parameters](#timeintransit-class-parameters) -7. [Shipping Class](#shipping-class) -8. [Logging](#logging) +8. [Shipping Class](#shipping-class) +9. [Logging](#logging) ## Requirements @@ -50,6 +53,48 @@ add the following lines to your ``composer.json`` file. } ``` + +## Address Validation Class (Street Level) + +The Address Validation Class allow you to validate an address at street level. Suggestions are given when address is invalid. + +Note: UPS has two Address Validations. This is Street Level option, which includes all option +of the normal Address Validation class and adds street level validation. + +Not all countries are supported, see UPS documentation. Currently US & Puerto Rico are supported. + + +### Example + +```php +$address = new \Ups\Entity\Address(); +$address->setAttentionName('Test Test'); +$address->setBuildingName('Test'); +$address->setAddressLine1('Address Line 1'); +$address->setAddressLine2('Address Line 2'); +$address->setAddressLine3('Address Line 3'); +$address->setStateProvinceCode('NY'); +$address->setCity('New York'); +$address->setCountryCode('US'); +$address->setPostalCode('10000'); + +$xav = new \Ups\AddressValidation($accessKey, $userId, $password); +try { + $response = $xav->validate($address, $requestOption = \Ups\AddressValidation::REQUEST_OPTION_ADDRESS_VALIDATION, $maxSuggestion = 15); +} catch (Exception $e) { + var_dump($e); +} +``` + + +### Parameters + +Adress Validation parameters are: + + * `address` Address object as constructed in example + * `requestOption` One of the three request options + * `maxSuggestion` Maximum number of suggestions to be returned. Max = + ## QuantumView Class diff --git a/src/Ups/AddressValidation.php b/src/Ups/AddressValidation.php index eef218b3..a5c3200a 100644 --- a/src/Ups/AddressValidation.php +++ b/src/Ups/AddressValidation.php @@ -40,6 +40,13 @@ class AddressValidation extends Ups * @var int */ private $maxSuggestion; + + /** + * Request Options + */ + const REQUEST_OPTION_ADDRESS_VALIDATION = 1; + const REQUEST_OPTION_ADDRESS_CLASSIFICATION = 2; + const REQUEST_OPTION_ADDRESS_VALIDATION_AND_CLASSIFICATION = 3; /** * @param string|null $accessKey UPS License Access Key @@ -57,17 +64,26 @@ public function __construct($accessKey = null, $userId = null, $password = null, parent::__construct($accessKey, $userId, $password, $useIntegration, $logger); } - + /** - * Get package address suggestions from UPS + * Get address suggestions from UPS * - * @param Ups\Entity\Address $address The address to validate on street level. - * @param string $requestOption Optional processing. For Mail Innovations the only valid options are Last Activity and All activity. + * @param $address + * @param int $requestOption + * @param int $maxSuggestion * @return stdClass * @throws Exception */ - public function validate($address, $requestOption = 1, $maxSuggestion = 5) + public function validate($address, $requestOption = self::REQUEST_OPTION_ADDRESS_VALIDATION, $maxSuggestion = 15) { + if($maxSuggestion > 50) { + throw new \Exception('Maximum of 50 suggestions allowed'); + } + + if(!in_array($requestOption, range(1, 3))) { + throw new \Exception('Invalid request option supplied'); + } + $this->address = $address; $this->requestOption = $requestOption; $this->maxSuggestion = $maxSuggestion; @@ -96,8 +112,6 @@ public function validate($address, $requestOption = 1, $maxSuggestion = 5) /** * Create the XAV request * - * @todo Use Address toNode() - * * @return string */ private function createRequest() diff --git a/tests/Ups/Tests/_files/requests/AddressValidation/Request1.xml b/tests/Ups/Tests/_files/requests/AddressValidation/Request1.xml index 44bc41d6..e88d2964 100644 --- a/tests/Ups/Tests/_files/requests/AddressValidation/Request1.xml +++ b/tests/Ups/Tests/_files/requests/AddressValidation/Request1.xml @@ -5,7 +5,7 @@ XAV 1 - 5 + 15 Test Test Building 1