Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhl/simple-ups

Fetch rates, track packages and verify addresses via the UPS API
https://github.com/bkuhl/simple-ups

Last synced: 3 months ago
JSON representation

Fetch rates, track packages and verify addresses via the UPS API

Awesome Lists containing this project

README 

        
# SimpleUPS



An easy to use PHP UPS Library for tracking, rates and address validation



[![Total Downloads](https://poser.pugx.org/bkuhl/simple-ups/downloads.svg)](https://packagist.org/packages/bkuhl/simple-ups) [![License](https://poser.pugx.org/bkuhl/simple-ups/license.svg)](https://packagist.org/packages/bkuhl/simple-ups) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/bkuhl/simple-ups/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/bkuhl/simple-ups/?branch=master)



## README Contents



* [Features](#features)

* [Installation](#installation)

* [Requirements](#requirements)

* [Usage](#usage)

  * [Address Validation](#address-validation)

  * [Region Validation](#region-validation)

  * [Tracking Shipments](#tracking-shiments)

  * [Fetching Rates](#fetching-rates)





## Features



 * **Address Validation** - Ensure an address is valid before it's accepted by your application

 * **Address Correction** - If an address is invalid, we'll help you correct it

 * **Track Packages** - See current status, recent activity, delivery requirements (signature, etc.), insurance details and more

 * **Shipping Rates** - Get shipping estimates for packages





## Installation



You can install the library via [Composer](http://getcomposer.org) by running:



````

composer require bkuhl/simple-ups:1.*

````



 > 1.* versions will maintain PHP 5.3 compatibility.  `dev-master` will increase the PHP version requirement for future, 2.* versions.





## Usage



SimpleUPS is currently only available in a static context with the following methods:



 * SimpleUPS::getRates()

 * SimpleUPS::isValidRegion()

 * SimpleUPS::getSuggestedRegions()

 * SimpleUPS::trackByTrackingNumber()

 * SimpleUPS::isValidAddress()

 * SimpleUPS::getCorrectedAddress()

 * SimpleUPS::getSuggestedAddresses()

 * SimpleUPS::setAuthentication()

 * SimpleUPS::getAccountNumber()

 * SimpleUPS::getAccessLicenseNumber()

 * SimpleUPS::getPassword()

 * SimpleUPS::getUserId()

 * SimpleUPS::setShipper()

 * SimpleUPS::getShipper()

 * SimpleUPS::setCurrencyCode()

 * SimpleUPS::setDebug()

 * SimpleUPS::getDebugOutput()





### Address Validation



Validating an address can be useful to ensure an address that a user provides can be shipped to.



```php

$address = new Address();

$address->setStreet('1001 North Alameda Street');

$address->setStateProvinceCode('CA');

$address->setCity('Los Angeles');

$address->setPostalCode(90012);

$address->setCountryCode('US');

 

try {

    var_dump(UPS::isValidAddress($address)); // true

} catch(Exception $e) {

    //unable to validate address

}

```





### Region Validation



If an address fails, validating the region can help you determine if the city, state and zip is valid even if the street address isn't.



```php

$address = new Address();

$address->setStreet('xx North Alameda Street');

$address->setStateProvinceCode('CA');

$address->setCity('Los Angeles');

$address->setPostalCode(90012);

$address->setCountryCode('US');

 

try {

    if (!UPS::isValidAddress($address))

        var_dump(UPS::isValidRegion($address)); // true

} catch(Exception $e) {

    //unable to validate region or address

}

```





### Tracking Shipments



Tracking numbers may contain multiple shipments, and shipments may contain multiple packages, and activity is associated with packages.



```php

try {

    /* @var $shipment \SimpleUPS\Track\SmallPackage\Shipment */

    foreach (UPS::trackByTrackingNumber('1Z4861WWE194914215') as $shipment)

        foreach ($shipment->getPackages() as $package)

            foreach ($package->getActivity() as $activity)

                if ($activity->getStatusType()->isDelivered())

                    echo 'DELIVERED';

} catch (TrackingNumberNotFoundException $e) {

    //Tracking number does not exist

} catch (Exception $e) {

    //Unable to track package

}

 

var_dump(UPS::isValidAddress($address)); // false

```





### Fetching Rates



```php

try {

    //set shipper

    $fromAddress = new \SimpleUPS\InstructionalAddress();

    $fromAddress->setAddressee('Mark Stevens');

    $fromAddress->setStreet('10571 Pico Blvd');

    $fromAddress->setStateProvinceCode('CA');

    $fromAddress->setCity('Los Angeles');

    $fromAddress->setPostalCode(90064);

    $fromAddress->setCountryCode('US');

 

    $shipper = new \SimpleUPS\Shipper();

    $shipper->setNumber('xxxxxxx');

    $shipper->setAddress($fromAddress);

 

    UPS::setShipper($shipper);

 

    //define a shipping destination

    $shippingDestination = new \SimpleUPS\InstructionalAddress();

    $shippingDestination->setStreet('220 Bowery');

    $shippingDestination->setStateProvinceCode('NY');

    $shippingDestination->setCity('New York');

    $shippingDestination->setPostalCode(10453);

    $shippingDestination->setCountryCode('US');

 

    //define a package, we could specify the dimensions of the box if we wanted a more accurate estimate

    $package = new \SimpleUPS\Rates\Package();

    $package->setWeight('7');

 

    $shipment = new \SimpleUPS\Rates\Shipment();

    $shipment->setDestination($shippingDestination);

    $shipment->addPackage($package);

 

    echo 'Rates: ';

 

    echo '
    ';

            foreach (UPS::getRates($shipment) as $shippingMethod)

                echo '
  • '.$shippingMethod->getService()->getDescription().' ($'.$shippingMethod->getTotalCharges().')
    • ';

     

        echo '
';

 

} catch (Exception $e) {

    //doh, something went wrong

    echo 'Failed: ('.get_class($e).') '.$e->getMessage().'
';

    echo 'Stack trace:
'.$e->getTraceAsString().'
';

}

```