Velocity Fleet API — Laravel Bridge

The Laravel bridge for chrisjohnleah/velocity-fleet-api — the framework-agnostic Radius Velocity Fleet telematics SDK. Adds a service provider, a facade, a persistent Eloquent token store, and artisan commands so a Laravel app talks to the API with zero wiring.

This package only wires the SDK into Laravel — auth, refresh, HTTP, and the typed DTOs all live in the core SDK.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13

Installation

composer require chrisjohnleah/velocity-fleet-api-laravel

The service provider and VelocityFleet facade are auto-discovered. Publish the config and run the migration that backs the token store:

php artisan vendor:publish --tag=velocity-fleet-config
php artisan migrate

Configuration

Set the credentials in your .env. There are two ways to authenticate (you only need one):

# Existing customers — an API token generated in the Velocity UI
# (Account Settings > API Integrations > Create API Token):
VELOCITY_FLEET_ACCESS_TOKEN=your-api-token

# OR, third-party integrations — a customer-supplied refresh token
# (plus client credentials if your OAuth client requires them):
VELOCITY_FLEET_REFRESH_TOKEN=customer-refresh-token
VELOCITY_FLEET_CLIENT_ID=
VELOCITY_FLEET_CLIENT_SECRET=

Whatever you set is auto-seeded into the token store on first use. The mode is decided by what you provide: a refresh token uses the OAuth2 refresh flow (with proactive refresh and reactive retry on a 401); a bare access token is used as a static Bearer token. A stored token always wins over config, so a redeploy never clobbers a rotated refresh token.

Usage

Via the facade:

use ChrisJohnLeah\VelocityFleet\Laravel\Facades\VelocityFleet;

foreach (VelocityFleet::customers()->list() as $customer) {
    // Use $customer->id (the unique id) for device positions — not $customer->number.
    $positions = VelocityFleet::devicePositions()->forCustomer($customer->id);

    foreach ($positions->devices as $device) {
        info("{$device->vehicleRegistration} @ {$device->lat},{$device->lon} — ignition ".
            ($device->ignitionOn() ? 'on' : 'off'));
    }
}

Or inject the client (type-hint the core class — the container builds it for you):

use ChrisJohnLeah\VelocityFleet\VelocityFleet;

public function index(VelocityFleet $velocity)
{
    return $velocity->customers()->list();
}

Artisan commands

php artisan velocity-fleet:connect   # store a token: --token=… or --refresh-token=… (defaults to config)
php artisan velocity-fleet:status    # show the stored token's mode / expiry
php artisan velocity-fleet:customers # live connectivity check — list linked customers

Token persistence

Tokens live in a single velocity_fleet_tokens row via EloquentTokenStore (bound to the core's TokenStore contract). put() overwrites that row, so a rotated refresh token always replaces the previous one. Change the table name with VELOCITY_FLEET_TOKEN_TABLE, or bind your own TokenStore implementation to swap the storage entirely.

Errors

The core SDK throws typed exceptions, all extending ChrisJohnLeah\VelocityFleet\Exceptions\VelocityFleetException:

Observability (optional)

Want outgoing Velocity API calls to show up in Laravel Telescope or Nightwatch? Install the official Saloon Laravel plugin — it auto-registers recording middleware on every connector, no changes here required:

composer require saloonphp/laravel-plugin

Testing

composer test      # Pest (orchestra/testbench)
composer analyse   # Larastan (max)
composer lint      # Pint --test
composer check     # all three

Tests run against an in-memory SQLite database and never hit the network.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Please report security issues privately per SECURITY.md.

Licence

MIT © Chris John Leah. See LICENSE.

Not affiliated with or endorsed by Radius or Velocity Fleet. "Radius", "Velocity" and "Kinesis" are trademarks of their respective owners.