onfleet/php-onfleet

Onfleet's PHP API Wrapper Package

v1.0.4 2023-10-10 18:16 UTC

Requires

• php: >=7.4

Requires (Dev)

• phpunit/phpunit: ^9.5

MIT

• Victoria Denysova
• Santiago Botero Ruiz

• OnFleet
• php-onfleet

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 [e-mail].

Table of contents

• Table of contents
• Synopsis
• Installation
• Requirements
• Usage
  • Authentication
  • Throttling
  • Supported CRUD operations
    • GET Requests
      • Examples of get()
      • Examples of get(param)
      • Examples of getByLocation
    • POST Requests
      • Examples of create()
    • PUT Requests
      • Examples of update()
      • Examples of insertTask()
    • DELETE Requests
      • Examples of deleteOne()
  • Examples of utilizing your CRUD operations
  • Things NOT to do

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:

Entity	GET	POST	PUT	DELETE
Admins/Administrators	get()	create(obj), matchMetadata(obj)	update(id, obj)	deleteOne(id)
Containers	get(id, 'workers'), get(id, 'teams'), get(id, 'organizations')	x	update(id, obj)	x
Destinations	get(id)	create(obj), matchMetadata(obj)	x	x
Hubs	get()	create(obj)	update(id, obj)	x
Organization	get(), get(id)	x	insertTask(id, obj)	x
Recipients	get(id), get(name, 'name'), get(phone, 'phone')	create(obj), matchMetadata(obj)	update(id, obj)	x
Tasks	get(query), get(id), get(shortId, 'shortId')	create(obj), clone(id), forceComplete(id), batch(obj), autoAssign(obj), matchMetadata(obj)	update(id, obj)	deleteOne(id)
Teams	get(), get(id), getWorkerEta(id, obj)	create(obj), autoDispatch(id, obj)	update(id, obj), insertTask(id, obj)	deleteOne(id)
Webhooks	get()	create(obj)	x	deleteOne(id)
Workers	get(), get(query), get(id), getByLocation(obj), getSchedule(id)	create(obj), setSchedule(id, obj), matchMetadata(obj)	update(id, obj), insertTask(id, obj)	deleteOne(id)

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" => "[phone]",
  "teams" => ["<team_ID>", "<team_ID> (optional)", ...],
  "vehicle" => [
    "type" => "CAR",
    "description" => "Tesla Model 3",
    "licensePlate" => "FKNS9A",
    "color" => "purple",
  ],
];

$onfleet->workers->create($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->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, 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.