Merge pull request #2 from ctwillie/development

Development

Author: ctwillie

README.md

@@ -1,6 +1,6 @@
 # Laravel-Usps
 
-This package provides a very simple wrapper for the United States Postal Service API. Currently, this package only provides address verification features, but will soon comprise all features offered by the USPS API. In the meantime, consider using [johnpaulmedina/laravel-usps](https://github.com/johnpaulmedina/laravel-usps), which is a great package.
+This package provides a very simple wrapper for the United States Postal Service API. Currently, this package only provides address validation features, but will soon comprise all features offered by the USPS API. In the meantime, consider using [johnpaulmedina/laravel-usps](https://github.com/johnpaulmedina/laravel-usps), which is a great package.
 
 ### Prerequisites
 
@@ -13,54 +13,80 @@ from the United States Postal Service. This user ID is required to use this pack
 composer require ctwillie/laravel-usps
 ```
 
-## Setup
-
-Starting at Laravel 5.5, this package will be automatically discovered and registered as a service provider.
-For earlier versions of Laravel, you will need to manually register this packages' service provider in `config/app.php`
-by adding this class to the providers array.
-
-```php
-'providers' => [
-    ...
-    ctwillie\Usps\UspsServiceProvider::class
-];
-```
-Then add an alias for the class also in `config/app.php` inside the aliases array.
-
-```php
-'aliases' => [
-    ...
-    'Usps' => ctwillie\Usps\UspsServiceProvider::class
-];
-```
-
 ## Configuration
 
-There are two important configurations.
+There are three important configurations.
 1. Your USPS user ID:
     - If you have not received your USPS user ID, follow the link in the [prerequisites](#Prerequisites) section  to register with the 
       United States Postal Service. It is required to use this package.
 
 2. Whether you want SSL verification enabled for API requests:
-    - This setting is set to `true` by default for security reasons. You can override this behavior by setting the `verrifyssl` config     setting to `false`. Do this at your own risk.
+    - This setting is set to `true` by default for security reasons. You can override this behavior by setting the `verrifyssl` config     setting to `false`.   Do this at your own risk.
+
+3. Which environment you are working in:
+	- The options are `'local' and 'production'` which tell the package which API url to use, testing or production respectively. If no configuration is found     for `env`, it will default to the environment recognized by laravel. This setting takes precedence over `APP_ENV` from your `.env` file.
 
 We recommend placing all configuration settings in your `.env` file and use Laravel's `env()` helper function to access these values.
 
-In `config/services.php` add these two settings.
+In `config/services.php` add these three settings.
 
 ```php
 'usps' => [
 
-    'userid' => env('USPS_USER_ID'), // ********
-    'verifyssl' => env('USPS_VERIFY_SSL') // true|false
-
+    'userid' => env('USPS_USER_ID'), // string
+    'verifyssl' => env('USPS_VERIFY_SSL'), // bool
+    'env' => env('USPS_ENV') //string
 ];
 ```
 
 ## Usage
 
-The current features offered by this package are listed below.
- - [Address Verification](#Address)
+The current features offered by this package are:
+ - [Address Validation](#Address-Validation) 
+
+
+## Address Validation
+
+The `Address` class handles creating and formatting address data. Pass the constructor an associative array of address details. Array keys are case-sensitive.
+Below is an example of creating an address and making an api request for validation.
+
+```php
+use ctwillie\Usps\Address;
+
+$address = new Address([
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+]);
+
+$response = $address->validate();
+```
+The USPS api supports up to 5 address validations per request. If you need to validate more than one address at a time, pass a multi dim array to the `Address` constructor.
+
+```php
+use ctwillie\Usps\Address;
+
+$address1 = [
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+];
+
+$address2 = [
+    'Address2' => '6406 Ivy Lane',
+    'City' => 'Greenbelt',
+    'State' => 'MD',
+    'Zip5' => 20770
+];
+
+$addresses = new Address([$address1, $address2])
+
+$response = $addresses->validate();
+```
+
+The response will contain the [corrected address](https://www.usps.com/business/web-tools-apis/address-information-api.pdf), or an error if not enough information was given or the address does not exists.
 
 ## Contributing
 

dev-notes.txt

@@ -0,0 +1,13 @@
+## Using a local repository
+"repositories": [
+    {
+        "type": "path",
+        "url": "~/code/packages/ctwillie/laravel-usps",
+        "options": {
+            "symlink": true
+        }
+    }
+ ]
+
+# Then run
+composer require package-name @dev

src/Usps/API.php

@@ -7,49 +7,75 @@
 use Spatie\ArrayToXml\ArrayToXml;
 use GuzzleHttp\Client;
 
+/**
+ * Class used by each entity to interact with the API and get configurations
+ * 
+ * Each entity will be responsible for managing its own data used in the api
+ * request. This class handles the common functions, such as, data formatting,
+ * creating http client, making request, returning response etc.
+ * 
+ */
 abstract class API {
 
     const PROD_URL = 'https://secure.shippingapis.com/ShippingAPI.dll';
     const LOCAL_URL = 'http://production.shippingapis.com/ShippingAPITest.dll';
     protected $env;
     protected $apiUrl;
     protected $userId;
+    protected $rootElements = [
+        'Verify' => 'AddressValidateRequest'
+    ];
 
+    /** Determines env to set api url, http client settings etc. */
     public function __construct() {
         $this->setEnvironment();
         $this->setUrl();
         $this->userId = config('services.usps.userid');
     }
 
-    // Determines the current application environment
+    /** Determines the current application env */
     public function setEnvironment()
     {
         if (Config::has('services.usps.env')) {
+
             $this->env = strtolower(config('services.usps.env'));
+
         } elseif (App::environment(['local', 'development'])) {
+
             $this->env = 'local';
-        } 
+        }
+
         $this->env = 'production';
     }
 
+    /** Determines the api url to use based on running env */
     public function setUrl()
     {
         $this->apiUrl = $this->env === 'local' ? self::LOCAL_URL : self::PROD_URL;
     }
 
+    /**
+     * Makes sure a userid has been provided
+     * 
+     * @throws Exception If no userid is found in config/services.php
+     */
     public function checkForUserId()
     {
         if (is_null($this->userId)) {
             throw new \Exception('USPS: A user ID is required. None found in config/services.php');
         }
     }
 
-    // create a map to determine the rootElementName foreach api type
+    /**
+     * Converts entity data into xml format and url encodes
+     * 
+     * @return string
+     */
     protected function convertToXML()
     {
         $xml = ArrayToXml::convert( $this->getRequestData(),
             [
-                'rootElementName' => $this->rootElementName,
+                'rootElementName' => $this->rootElements[$this->apiType],
 
                 '_attributes' => ['USERID' => $this->userId]
 
@@ -58,6 +84,14 @@ protected function convertToXML()
         return urlencode($xml);
     }
 
+    /**
+     * Handles making the api request
+     * 
+     * This method handles creating the http client and gathering
+     * all necessary data for making the api request.
+     * 
+     * @return StreamInterface of the response content body
+     */
     public function makeRequest()
     {
         $this->checkForUserId();
@@ -71,8 +105,12 @@ public function makeRequest()
         return $response->getBody();
     }
 
-    // Abstract to be defined by each entity
-    abstract public function getRequestData() : array;
+    /**
+     * Each entity decides the array structure for the request data
+     * 
+     * @return array
+     */
+    abstract public function getRequestData();
 
     public function validate()
     {

src/Usps/Address.php

@@ -2,11 +2,14 @@
 
 namespace ctwillie\Usps;
 
+/**
+ * This class gathers data for the 'Verify' api route
+ * 
+ * It is responsible for formatting address request data that
+ * will be handled by the API class
+ */
 class Address extends API
 {
-    // use map to determine root element
-    // key will be api type ('verify' => 'AddressValidateRequest')
-    protected $rootElementName = 'AddressValidateRequest';
     protected $apiType = 'Verify';
     protected $addresses = [];
     protected $allowedProperties = ['Address1','Address2','City','State','Zip4','Zip5'];
@@ -16,8 +19,6 @@ class Address extends API
      * Handles single or multiple addresses passes to constructor
      * 
      * @param array $addresses
-     * @return void
-     * 
      */
     public function __construct(array $addresses = [])
     {
@@ -26,11 +27,9 @@ public function __construct(array $addresses = [])
     }
 
     /**
-     * Handles multiple addresses 
+     * Handles adding multiple addresses 
      * 
      * @param array $addresses
-     * @return void
-     * 
      */
     public function handleMultipleAddresses(array $addresses)
     {
@@ -55,13 +54,9 @@ public function handleMultipleAddresses(array $addresses)
     }
 
     /**
-     * Handles single address 
+     * Handles adding a single address
      * 
      * @param array $address
-     * @return void
-     * 
-     * Add addAddress method which calls this method and checks five address limit
-     * 
      */
     public function handleSingleAddress(array $address)
     {
@@ -80,7 +75,12 @@ public function handleSingleAddress(array $address)
         }
     }
 
-    public function getRequestData() : array
+    /**
+     * Formats the request data.
+     * 
+     * @return array
+     */
+    public function getRequestData()
     {
         return ['Address' => $this->addresses];
     }