onfleet / php-onfleet
Onfleet's PHP API Wrapper Package
Installs: 16 070
Dependents: 1
Suggesters: 0
Security: 0
Stars: 3
Watchers: 16
Forks: 5
Open Issues: 3
Requires
- php: >=7.4
Requires (Dev)
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2024-12-05 14:09:14 UTC
README
Read this document in another language: EspaƱol
Visit our blog post on the API wrapper project to learn more about our initiatives. If you have any questions, please reach us by submitting an issue here or contact support@onfleet.com.
Table of contents
- Table of contents
- Synopsis
- Installation
- Requirements
- Usage
Synopsis
The Onfleet PHP library provides convenient access to the Onfleet API.
Installation
composer require onfleet/php-onfleet
Requirements
The Onfleet PHP library requires bcmath extension to be installed.
Usage
Before using the API wrapper, you will need to obtain an API key from one of your organization's admins.
Creation and integration of API keys are performed through the Onfleet dashboard.
To start utilizing the library, you simply need to create an Onfleet
object with your API key:
$onfleet = new Onfleet("<your_api_key>");
Optionally, you can introduce a customized timeout that is less than the default Onfleet API timeout (70,000 ms) by providing a 2nd parameter:
$onfleet = new Onfleet("<your_api_key>", 30000);
Authentication
Once the Onfleet
object is created, you can test on the authentication endpoint:
$onfleet->verifyKey(); // Returns a boolean
Throttling
Rate limiting is enforced by the API with a threshold of 20 requests per second across all your organization's API keys. Learn more about it here.
We have also implemented a limiter on this library to avoid you from unintentionally exceeding your rate limitations and eventually be banned for.
Supported CRUD Operations
Here are the operations available for each entity:
GET Requests
To get all the documents within an endpoint, this returns an array of results:
get();
Examples of get()
$onfleet->workers->get(); $onfleet->workers->get($queryParams);
Optionally you can send an array of query params for some certain endpoints. Refer back to API documentation for endpoints that support query parameters.
$onfleet->workers->get([ "phones" => "<phone_number>" ]); $onfleet->tasks->get([ "from" => "<from_time>", "to" => "<to_time>" ]);
To get one of the documents within an endpoint, if the optional paramName is not provided, the library will search by ID. If paramName is provided, it will search by paramName:
get(<parameter>, <paramName> (optional), <queryParam> (optional));
paramName can be any of:
id
name
phone
shortId
Examples of get(param)
$onfleet->workers->get("<24_digit_ID>"); $onfleet->workers->get("<24_digit_ID>", [ "analytics" => true ]); $onfleet->tasks->get("<shortId>", "shortId"); $onfleet->recipients->get("<phone_number>", "phone"); $onfleet->recipients->get("<recipient_name>", "name"); $onfleet->recipients->get("<recipient_name>", "name", [ "skipPhoneNumberValidation" => true ]); $onfleet->containers->get("<24_digit_ID>", "workers"); $onfleet->containers->get("<24_digit_ID>", "teams"); $onfleet->containers->get("<24_digit_ID>", "organizations");
To get a driver by location, use the getByLocation
function:
getByLocation($queryParams);
Examples of getByLocation
$locationParams = [ "longitude" => -122.404, "latitude" => 37.789, "radius" => 10000, ]; $onfleet->workers->getByLocation($locationParams);
POST Requests
To create a document within an endpoint:
create($data);
Examples of create()
$data = [ "name" => "John Driver", "phone" => "+16173428853", "teams" => ["<team_ID>", "<team_ID> (optional)", ...], "vehicle" => [ "type" => "CAR", "description" => "Tesla Model 3", "licensePlate" => "FKNS9A", "color" => "purple", ], ]; $onfleet->workers->create($data);
Examples of getDeliveryManifest()
$data = [ "hubId" => "<hubId>", // Required "workerId" => "<workerId>", // Required "googleApiKey" => "<googleApiKey>", // Optional "startDate" => "<startDate>", // Optional - Timestamp format e.g. 1557936000000 "endDate" => "<endDate>" // Optional - Timestamp format e.g. 1557936000000 ]; $onfleet->workers->getDeliveryManifest($data);
Extended POST requests include clone
, forceComplete
, batchCreate
, autoAssign
on the Tasks endpoint; setSchedule
on the Workers endpoint; autoDispatch
on the Teams endpoint; and matchMetadata
on all supported entities. For instance:
$onfleet->tasks->clone('<24_digit_ID>'); $onfleet->tasks->forceComplete('<24_digit_ID>', $data); $onfleet->tasks->batchCreate($data); $onfleet->tasks->autoAssign($data); $onfleet->workers->setSchedule('<24_digit_ID>', $data); $onfleet->workers->getDeliveryManifest($data); $onfleet->teams->autoDispatch('<24_digit_ID>', $data); $onfleet-><entity_name_pluralized>->matchMetadata($data);
For more details, check our documentation on clone
, forceComplete
, batchCreate
, autoAssign
, setSchedule
, matchMetadata
, getDeliveryManifest
, and autoDispatch
.
PUT Requests
To update a document within an endpoint:
update("<24_digit_ID>", $data);
Examples of update()
$newData = [ "name" => "Jack Driver", ]; $onfleet->workers->update("<24_digit_ID>", $newData);
Examples of insertTask()
$onfleet->workers->insertTask("<24_digit_ID>", $data);
DELETE Requests
To delete a document within an endpoint:
deleteOne("<24_digit_ID>");
Examples of deleteOne()
$onfleet->workers->deleteOne("<24_digit_ID>");
Examples of utilizing your CRUD operations
- Get all the recipients:
try { $tasks = $onfleet->tasks->get([ "from" =>"1557936000000", "to" => "1558022400000" ]); foreach ($tasks['tasks'] as $task) { if (is_set($task['recipients'][0])) { // Do something with the recipients } } } catch (Exception $error) { // Do something with the error }
Things NOT to do
-
Inefficient pattern, use metadata instead:
// DONT try { $workers = $onfleet->workers.get(); for ($workers as $worker) { foreach ($worker['metadata'] as $metadataEntry) { if ($metadataEntry['name'] === "hasFreezer" && $metadataEntry['value']) { // Do something } } } } catch (Exception $error) { // Do something with the error } // DO try { $workers = $onfleet->workers->matchMetadata([["name" => "hasFreezer", "type" => "boolean", "value" => true]]); for ($workers as $worker) { // Do something } } catch (Exception $error) { // Do something with the error }
Go to top.