Download the PHP package chrisjohnleah/velocity-fleet-api-laravel without Composer

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

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

Configuration

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

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:

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

Artisan commands

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:

Fleet platform (v0.2)

On top of the thin bridge, the package ships an opt-in fleet platform. Every subsystem below defaults to OFF/safe — upgrading changes nothing until you enable it in config/velocity-fleet.php.

Fleet queries

VelocityFleet::fleet($customerId) returns a chainable DeviceCollection:

Scopes: moving(), idling(), ignitionOn(), ignitionOff(), online(), offline(), inDeviceGroup(), inDriverGroup(), near(), byRegistration(), withDriver().

Caching (stale-while-revalidate)

VelocityFleet::cached()->positions($id) serves positions from a refresh-rate-aware cache with Cache::lock single-flight, so concurrent callers/workers collapse to one upstream POST per window. The TTL comes from the API's own live-map hints, clamped by cache.min_ttl. For multi-server / Octane, use a shared atomic-lock store (redis/database/memcached) — velocity-fleet:doctor warns otherwise.

Change-detection events

Enable polling, run a queue worker and the scheduler, and the poller fires events as devices change:

IgnitionTurnedOn · IgnitionTurnedOff · VehicleStartedMoving · VehicleStopped · DeviceWentStale · DeviceCameBackOnline, plus the umbrella DevicePositionsUpdated. Listen for them like any Laravel event.

Geofences & notifications

Define circle or polygon Geofences; with geofencing on, the matcher fires VehicleEnteredGeofence / VehicleExitedGeofence / VehicleDwelledInGeofence / VehicleArrived. With notifications on, arrival/offline/geofence/speeding/idling notifications are sent to configured routes, throttled to avoid storms. Speeding/idling are heuristics derived from poll cadence.

History (opt-in, encrypted)

With history.enabled, each poll ingests positions into velocity_fleet_device_positions (PII columns encrypted at rest, idempotent upsert). retention.positions_days (default 90) prunes old rows. Off by default — see GDPR notes in SECURITY.md.

Commands

Testing toolkit

Testing

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

Contributing

Issues and PRs welcome — see 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.