README

This is the official PHP client library for interacting with the GPS Insight API (V2).

GPS Insight provides vehicle fleet GPS tracking and FMCSA-compliant electronic logging devices (ELD) for regulating hours of service (HOS). GPS Insight's API (V2) provides a programmatic way to push your fleet's data from our system to your back-end systems (e.g., ERP, Dispatch, CRM). By using our API you can effortlessly integrate your fleet's data into your back-end systems to provide transparency into payroll, fuel card transactions, additional documentation, asset management, and more.

The GPS Insight API documentation is hosted on our website. Be sure to sign up for an account and follow the directions to get API credentials before using this library.

Installation

This package is hosted on Packagist and is installable via Composer.

Requirements

• PHP version 5.5 or greater (5.6+ recommended)
• Composer (for installation)
• Guzzle is installed automatically as a dependency and requires one of the following to make HTTP requests:
  • A recent version of cURL (minimum 7.19.4) compiled with OpenSSL and zlib.
  • Enable allow_url_fopen in your system's php.ini.

Installing Via Composer

Run the following command (assuming composer is available in your PATH):

$ composer require gpsinsight/api-v2-client

This will set the GPS Insight API Client Library as a dependency in your project and install it.

When bootstrapping your application, you will need to require 'vendor/autoload.php' in order to setup autoloading for the GPS Insight API Client Library and any of your other Composer-installed packages.

Basic Usage

Code

use GpsInsight\Api\V2\GpsInsight;

// Create and configure an SDK object
$gpsInsight = new GpsInsight([
    'username'  => 'johndoe3000',
    'app_token' => '490f5ed342ca8',
]);

// Call the "create" method of the "driver" service
// Note: API authentication is applied automatically by the client library
$result = $gpsInsight->driver->create([
    'lastname' => 'Lindblom',
    'firstname' => 'Jeremy',
    'email' => 'jlindblom@example.com',
    'timezone' => 'US/Arizona',
]);

print_r($result->getData());

Output

Array
(
    [id] => 4551485
    [message] => Driver added
)

Additional Usage

If you are using an IDE like PhpStorm that supports intellisense, the names of services and operations will autocomplete for you. For parameters, you should consult the official GPS Insight API documentation.

Concepts

Classes

All classes are in the root namespace of GpsInsight\Api\V2.

• GpsInsight – The starting point to the library (as seen above in the example). Users can access the various available services via readonly, intellisense-ready properties (e.g., $gpsInsight->driver, $gpsInsight->landmark)
• ServiceClient – Encapsulates APIs for a particular service (e.g., $gpsInsight->driver->create())
• Client – A guzzlehttp/command-powered client that is used by the GpsInsight and various ServiceClient classes
• Result – An ArrayAccessible object that encapsulates the parsed data from an API response. It is returned as the result of any API call (e.g., $result = $gpsInsight->driver->create(); echo $result['message'];)
• Services – A class containing the list of valid services names
• Middleware – The Middleware directory contains guzzlehttp/command middleware that are used to perform transformations on the command or result prior to them being serialized to a request or response. For example, auth is handled via a middleware, as is applying an app channel.

Configuration

When instantiating the GpsInsight class, you must provide configuration options to setup the API client. The following settings are allowed:

• app_token (string, conditionally required ^†) – GPS Insight API "App Token", which acts as a credential for a specific application
• channel (string, recommended) – An identifier to tag your requests with for your application. You can then retrieve stats about your application's API usage with the channel APIs
• endpoint (string, optional) – Base URL endpoint for accessing the GPS Insight API. Defaults to the production GPS Insight API endpoint: "https://api.gpsinsight.com"
• http_handler (callable, optional) – Custom or shared Guzzle HTTP handler. See docs for handler in the Guzzle documentation for "Creating a Client"
• http_options (associative array, optional) – A set of Guzzle HTTP request options. See docs for Request Options in the Guzzle Documentation
• password (string, conditionally required ^†) – GPS Insight API account password
• session_token (string, conditionally required ^†) – GPS Insight API "session token"
• token_cache (TokenCacheInterface, recommended) – A token cache for storing/retrieving session tokens.
• username (string, required) – GPS Insight API account username
• version (string, recommended) – A version number to tag your requests with for your application. Use this with in combination with channel
• wire_log (bool|LoggerInterface, optional) – Use this to enable wire logging for debugging purposes. Set to true for the default logger that writes to STDOUT, or provide a PSR-3 compliant LoggerInterface

^† You must provide at least one of app_token, password, or session_token along with your username to authenticate to the GPS Insight API. For more information about API credentials, please read the GPS Insight API documentation.

Advanced Example

use GpsInsight\Api\V2\GpsInsight;
use GpsInsight\Api\V2\TokenCache\CallbackCache as TokenCallbackCache;

// Create and configure an SDK object
$gpsInsight = new GpsInsight([
    'username'  => 'johndoe3000',
    'app_token' => '490f5ed342ca8',
    'channel' => 'my_custom_app',
    'version' => '2.10.1',
    'token_cache' => new TokenCallbackCache(
        function ($key) {
            return isset($_SESSION['gpsinsight_tokens'][$key])
                ? $_SESSION['gpsinsight_tokens'][$key]
                : null;
        },
        function ($key, $token) {
            $_SESSION['gpsinsight_tokens'][$key] = $token;
        }
    ),
]);

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email websecurity@gpsinsight.com directly instead of using the issue tracker. This allows us to take appropriate actions to mitigate the issues as quickly as possible.

Credits

• Jeremy Lindblom
• Jennifer Dearing
• Grant Anderson
• Drew LeSueur

License

The MIT License (MIT). Please see License File for more information.