lukesnowden/simple-ups

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

SimpleUPS

An easy to use PHP UPS Library for tracking, rates and address validation, _(*1)

, _(*2)

README Contents

• Features
• Installation
• Usage
  • Address Validation
  • Region Validation
  • Tracking Shipments
  • Fetching Rates

, _(*3)

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

, _(*4)

Installation

You can install the library via Composer by adding the following line to the require block of your composer.json file:, _(*5)

"bkuhl/simple-ups": "dev-master"

Then run composer update., _(*6)

, _(*7)

Usage

SimpleUPS is currently only available in a static context with the following methods:, _(*8)

• 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()

, _(*9)

Address Validation

Validating an address can be useful to ensure an address that a user provides can be shipped to., _(*10)

$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
}

, _(*11)

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., _(*12)

$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
}

, _(*13)

Tracking Shipments

Tracking numbers may contain multiple shipments, and shipments may contain multiple packages, and activity is associated with packages., _(*14)

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

, _(*15)

Fetching Rates

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 '<ul>';
        foreach (UPS::getRates($shipment) as $shippingMethod)
            echo '<li>'.$shippingMethod->getService()->getDescription().' ($'.$shippingMethod->getTotalCharges().')</li>';

    echo '</ul>';

} catch (Exception $e) {
    //doh, something went wrong
    echo 'Failed: ('.get_class($e).') '.$e->getMessage().'<br/>';
    echo 'Stack trace:<br/><pre>'.$e->getTraceAsString().'</pre>';
}