Download the PHP package bam-bam-bigelow/shipment-tracker without Composer

Shipment Tracker

A simple tool to scrape the parcel tracking data for DHL, DHL Express, GLS, UPS, FedEx USPS, Swiss Post Service and Austria Post Service

Some parcel services give you a really hard time when it comes to registering some kind of merchant or developer account. All you actually want is to simply keep track of a shipment and have an eye on its status. Yes, you could keep refreshing the tracking pages, but sometimes you've just got better stuff to do.

So here's a tool that does this automatically, without any of the developer-account and API mumbo jumbo. It just simply scrapes the website with the tracking information and transforms the data into an easily consumable format for humans and computers. Let me show you how it works!

Installation

Just pull this package in through composer or by adding it to your composer.json file:

Don't forget to run

$ composer update

after that.

Supported Carriers

The following carriers and languages are currently supported by this package:

• DHL (de, en)
• DHL Express (de, en) (so far only for waybill numbers, not for shipment numbers of the individual pieces)
• GLS (de, en)
• UPS (de, en)
• Fedex (en) (hat tip to @avrahamappel)
• USPS (en)
• PostCH (Swiss Post Service) (de, en)
• PostAT (Austria Post Service) (de, en)

Basic Usage

And that's it. Let's check if this parcel was delivered:

Possible statuses are:

• Track::STATUS_IN_TRANSIT
• Track::STATUS_DELIVERED
• Track::STATUS_PICKUP
• Track::STATUS_EXCEPTION
• Track::STATUS_WARNING
• Track::STATUS_UNKNOWN

So where is it right now and what's happening with it?

You can grab an array with the whole event history with $track->events(). The events are sorted by date in descending order. The date is a Carbon object.

What else?

You just want to build up the URL for the tracking website? No problem:

Oh, you need it to link to the english version? Sure thing:

"But wait, what if I need that URL with additional parameteres?" - Well, just pass them:

Other features

Additional details

Tracks and Events both can hold additional details, accessible via e.g. $track->getAdditionalDetails('foo'). Currently, this is only relevant for GLS and UPS:

• GLS:

  • $track->getAdditionalDetails('parcelShop') gets the parcel shop details and the opening hours if the parcel was delivered to one

• UPS:

  • $track->getAdditionalDetails('accessPoint') gets the address of the access point if the parcel was delivered to one
  • $track->getAdditionalDetails('pickupDueDate') gets the pickup due date as a Carbon instance

• DHL Express (waybills):

  • $track->getAdditionalDetails('pieces') gets the tracking numbers of the individual pieces that belong to this shipment
  • $event->getAdditionalDetails('pieces') gets the tracking numbers of the individual pieces to which this event applies
• FedEx:
  • $track->getAdditionalDetails('totalKgsWgt') gets the weight of the shipment in kgs if it's returned
  • $track->getAdditionalDetails('totalLbsWgt') gets the weight of the shipment in lbs if it's returned

Data Providers

By default, this package uses Guzzle as well as the PHP Http client (a.k.a. file_get_contents()) to fetch the data. You can pass your own provider if you need to, e.g. if you have the page contents chillin' somewhere in a cache. Just make sure that it implements Sauladam\ShipmentTracker\DataProviders\DataProviderInterface, which only requires a get() method.

Then, you can just pass it to the factory: $dhlTracker = ShipmentTracker::get('DHL', new CacheDataProvider);

If you pass your data provider, it's used by default, but you can swap it out later if you want:

Currently available providers are:

• guzzle
• php
• custom (referring to the provider that you've passed)

Notes

Please keep in mind that this is just a tool to make your life easier. I do not recommend using it in a critical environment, because, due to the way it works, it can break down as soon as the tracking website where the data is pulled from changes its structure or renames/rephrases the event descriptions. So please use it at your own risk!

Also, there's always a chance that a status can not be resolved because the event description is not known by this package, even though the most common events should be resolved correctly.

Also, the tracking data, therefore the data provided by this package, is the property of the carrier (I guess), so under no circumstances you should use it commercially (like selling it or integrating it in a commercial service). It is intended only for personal use.