Skip to content

Latest commit

 

History

History
171 lines (135 loc) · 5.24 KB

README.md

File metadata and controls

171 lines (135 loc) · 5.24 KB
Raw

SimpleUPS

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

Scrutinizer Code Quality

README Contents

## 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 by adding the following line to the require block of your composer.json file:

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

Then run composer update.

## 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.

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

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

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 
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>';
}