Official core library for developers working with the Detrack API
Official core library for PHP applications to interact with the Detrack API.
Important v2 release v2 is incompatible with code using the v1 library due to major overhauls in the backend API. Class names and method names have been changed. Please review the documentation carefully and refactor your code accordingly should you decide to upgrade.
Install the package via composer:
composer require detrack/detrack-core:^2.0
Composer will handle all the dependencies for you.
Requires PHP >= 7.1
PHP 5.6 and 7.0 has already been officially deprecated; our new library and API takes advantage of the new features PHP 7.1 has to offer for better stability.
You must also have created a (free!) account on Detrack, and understand our basic workflow.
And remember to include the autoloader, if you haven't already:
In this short guide, we'll pretend that we're an e-shop who sells ice-cream, and use the Detrack service to track our deliveries. We will use this library to implement the bare-minimum functionality for Detrack to function. (An advanced guide is available further below)
First, you need to configure the static facade of
All objects in this library will then use this API key for the rest of your request lifecycle.
When your e-shop confirms payment from a customer, you need to send a request to us regarding the details of the delivery so that a free vehicle in your fleet can be assigned to complete this delivery. This is represented via the
Detrack\DetrackCore\Resource\Job represents a single delivery job you assign to your drivers. In the context of an e-shop, this also represents a single order on the store.
Detrack\DetrackCore\Resource\Model\Item represents an item from your shop within the order. While you do not need this for Detrack to function, it will show up in the Electronic Proof of Deliveries (POD) that you and your customer will get when the Delivery is marked as complete.
There are three attributes that you must give the Job object before you submit it, date, do_number (Delivery order number) and address.
use Detrack\DetrackCore\Resource\Job; $delivery = new Job([ "date"=>"2018-12-19", "do_number"=>"DO# 12345", "address"=>"Null Island", "instructions"=>"Tell recipient to come out and retrieve ice cream from van" //not required, but you can specify other fields that are documented on our API reference ]); $delivery->save();
You can also first pass no arguments into the constructor, then modify the attributes later:
use Detrack\DetrackCore\Resource\Job; $delivery = new Job(); $delivery->date = "2018-12-19"; $delivery->do_number = "DO# 12345"; $delivery->address = "Null Island"; $delivery->instructions = "Tell recipient to come out and retrieve ice cream from van"; //not required, but you can specify other fields that are documented on our API reference $delivery->save(); //submits the delivery to Detrack
Remember that you must ensure that the required attributes date, do_number and address are set before you call
Note that the
save() function behaves as an "upsert" function, which automatically creates jobs that do not yet exist or updates jobs that already exist. If you require a "strict insert" and "strict update", use
save() respectively, but be prepared to catch an
create() is called on a job with a conflicting do_number on the same day and
update() is called on a job that does not yet exist.
And that's it! You've submitted your first delivery to Detrack. If you have your vehicles set up correctly on the Detrack Control Panel, your system will automatically assign deliveries to your drivers and you can start tracking them through their other apps.
While what is documented in the previous section is the bare minimum required to get your application integrated with Detrack, you should add more information that is useful to both your staff and your customers. The next point we shall cover is adding items to your deliveries. These items will show up on receipts and Electronic PODs that you and will customers will receive.
Item object has three base required attributes: sku (stock keeping unit (number)), qty (quantity) and desc description.
Creating the Item objects is similar to Deliveries, but you need not use factories since there's no client to attach:
use Detrack\DetrackCore\Resource\Model\Item; $item = new Item([ "sku"=>"IC 456", "qty"=>"5", "desc"=>"Strawberry flavoured ice-cream" ]);
Alternatively, like jobs, you can pass an empty argument into the constructor, then set the attributes later:
use Detrack\DetrackCore\Model\Item; $item = new Item(); $item->sku = "IC 456"; $item->qty = "5"; $item->desc = "Strawberry flavoured ice-cream";
Then, you need to add them to a delivery object by first accessing the
items property and then calling the
$delivery->items->add($item); $delivery->save() //sends the info to Detrack
And that's it: The
items property is an instance of
Detrack\DetrackCore\Model\ItemCollection, and contains methods like
pop() for you to manipulate the items attached to the delivery. Don't forget to call
save() afterwards to commit the changes to the Detrack API.
This part contains miscellaneous bits and pieces of info should you require more fine control.
Deliveries stored in the Detrack database are identified by both their do_number and their scheduled delivery date.
hydrate() method is available to fill up the rest of the attributes given the do_number and date.
This is usually used to retrieve updated information of a delivery.
delete() functions work in the Object-Relation-Mapping style, and you can call them on any
// Update instructions $delivery->instructions = "Change of plan, leave ice cream package in the mailbox instead"; $delivery->save(); // Customer no longer wants ice cream $delivery->delete();
Upon deleting, the Delivery job will no longer show up on the Detrack Dashboard, and will no longer be tracked.
As mentioned above, if you require strict inserts and updates, use
$delivery = new Job(); $delivery->do_number = "DO# 12345"; $delivery->address = "PHP Island"; $delivery->date = date("Y-m-d"); $delivery->items->add(new Item(["sku"=>"1","qty"=>5,"desc"=>"Chocolate Ice Cream"])); //will throw exception $delivery->update(); //ok $delivery->create(); $delivery->items->pop(); $delivery->items->add(new Item(["sku"=>"2","qty"=>5,"desc"=>"Strawberry Ice Cream"])); //will throw exception $delivery->create(); //ok $delivery->update();
downloadDoc(String $document, String $format, String $target) method is available to download documents relevant to each
NULLis passed, raw file data will be returned to you as a string.
- If the path of an existing folder is given, the file is downloaded into that folder with the default file name from the server.
- If a path to a nonexistent file is given, the file will be downloaded to that exact path with that name.
Bulk operations are available for list, create (strict) and delete. However, you should use them with caution when handling large datasets as they may cause your script to timeout if your
MAX_EXECUTION_TIME setting in PHP is not long enough.
Job::listJobs(array $args, String $query)To use if you need to display many jobs like an overview in a dashboard.
$argsis an associative array with the following keys:
String, provide the attribute name to sort by (e.g.
"date"). Add a minus sign in front to flip the order. Does not work if you use together with
Y-m-dformat, only list deliveries on that day
Stringonly show jobs driven by this driver
Stringonly show jobs of a certain status. Available are
Stringonly show jobs of a certain DO number. Used to show reattempts (because reattempts will have the same DO number but different date)
$queryis a search term that lets you search across all other fields such as address.
Job::createJobs(array $jobs)Bulk create an array of jobs. You can either pass an array of
Jobobjects or an array of associative arrays representing attributes of
Job::deleteJobs(array $jobs)Bulk delete an array of jobs. You can either pass an array of
Jobobjects or an array of associative arrays representing attributes of
Jobobjects, although you only need the id field. The method will automatically strip the other attributes for you.
Vehicles can also be created, retrieved, updated and deleted in a fashion similar to Jobs. The fully qualified class name is
There are three keys to
Vehicles in the Detrack backend –
name, which is the name of the driver the organisation sets,
detrack_id, the id unique to the driver, and
id, the id unique to the pairing of the driver and the organisation.
The detrack_id is the hash string unique to each Driver that can be seen when they open the Detrack Proof of Delivery App on their phone. To create a delivery, construct a
Vehicle object and fill in the detrack_id and driver attributes:
use Detrack\DetrackCore\Resource\Vehicle; $vehicle = new Vehicle(); $vehicle->detrack_id = "SGVsbG8gV29ybGQ"; $vehicle->name = "Tom's Van"; $vehicle->save(); //or $vehicle->create();
delete() functions are also available for
assignTo(Vehicle $vehicle) method on
Job objects to assign a job to your drivers. Continuing from the above examples:
$tomsVehicle = new Vehicle(); $tomsVehicle->name = "Tom's Van"; $tomsVehicle = $tomsVehicle->hydrate(); //optional, assignTo will do it for you anyway $delivery->assignTo($tomsVehicle);
Thereafter somewhere else in your code, you can then call
getVehicle() on the
Job objects to retrieve the
Vehicle that has been assigned to it.
echo $delivery->getVehicle()->name; //prints "Tom's Van"
We are open to contributions. If you feel something can be improved, feel free to open a pull request.
Open an issue on GitHub, or send an email to email@example.com addressed to the Engineering team.
Clone this repository and install composer dev dependencies.
git clone https://github.com/detrack/detrack-core-php.git . composer install
Refer to the
.env.example file and create your own
.env to enter testing API Keys, DO numbers, Driver detrack_id etc.
The test will create sample jobs on your Detrack Dashboard, and on successful completion, delete them thereafter. (Consequently, an internet connection is required to run the test suites)
phpunit on the
tests folder, either through the
vendor folder or through a globally installed executable.
- GuzzleHttp - The underlying HTTP library
- Chester Koh - Initial work - chesnutcase
This project is licensed under the MIT License - see the LICENSE.md file for details