PHPackages chrisjohnleah/velocity-fleet-api-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. chrisjohnleah/velocity-fleet-api-laravel ActiveLibrary[API Development](/categories/api) chrisjohnleah/velocity-fleet-api-laravel ======================================== Laravel bridge for the Radius Velocity Fleet API SDK — service provider, facade, Eloquent token store, and artisan commands. v0.1.0(today)00MITPHPPHP ^8.3CI failing Since Jun 9Pushed todayCompare [ Source](https://github.com/chrisjohnleah/velocity-fleet-api-laravel)[ Packagist](https://packagist.org/packages/chrisjohnleah/velocity-fleet-api-laravel)[ Docs](https://github.com/chrisjohnleah/velocity-fleet-api-laravel)[ RSS](/packages/chrisjohnleah-velocity-fleet-api-laravel/feed)WikiDiscussions main Synced today READMEChangelogDependencies (10)Versions (2)Used By (0) Velocity Fleet API — Laravel Bridge =================================== [](#velocity-fleet-api--laravel-bridge) [![CI](https://github.com/chrisjohnleah/velocity-fleet-api-laravel/actions/workflows/ci.yml/badge.svg)](https://github.com/chrisjohnleah/velocity-fleet-api-laravel/actions/workflows/ci.yml)[![Packagist Version](https://camo.githubusercontent.com/3886021c347cf5b6e01d75033a8b66cf35c6ff5e2246782299a0a7d95bcf4e7c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63687269736a6f686e6c6561682f76656c6f636974792d666c6565742d6170692d6c61726176656c2e737667)](https://packagist.org/packages/chrisjohnleah/velocity-fleet-api-laravel)[![Total Downloads](https://camo.githubusercontent.com/101141184b314a5db4cd3219ff4a6f2685e5c5a47d46eecc24e452520f2060c1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63687269736a6f686e6c6561682f76656c6f636974792d666c6565742d6170692d6c61726176656c2e737667)](https://packagist.org/packages/chrisjohnleah/velocity-fleet-api-laravel)[![PHP Version](https://camo.githubusercontent.com/b64bea291bbb93e7f7efc2543424cf3dde10f8815a79e618bf246693e0a2f6ad/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f63687269736a6f686e6c6561682f76656c6f636974792d666c6565742d6170692d6c61726176656c2e737667)](https://packagist.org/packages/chrisjohnleah/velocity-fleet-api-laravel)[![License: MIT](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE) The Laravel bridge for [`chrisjohnleah/velocity-fleet-api`](https://github.com/chrisjohnleah/velocity-fleet-api) — the framework-agnostic [Radius Velocity Fleet](https://www.velocityfleet.com) 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](https://github.com/chrisjohnleah/velocity-fleet-api). Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 11, 12, or 13 Installation ------------ [](#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 ------------- [](#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 ----- [](#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 ---------------- [](#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 ----------------- [](#token-persistence) Tokens live in a single `velocity_fleet_tokens` row via [`EloquentTokenStore`](src/EloquentTokenStore.php) (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 ------ [](#errors) The core SDK throws typed exceptions, all extending `ChrisJohnLeah\VelocityFleet\Exceptions\VelocityFleetException`: ExceptionWhen`NotConnectedException`No token available — run `velocity-fleet:connect` or set the env vars`AuthenticationException``401`/`403` after a refresh attempt — re-authorise`ApiException`Any other API error (carries `->status`, `->body`, `->headers`, `header()`, `retryAfter()`)Observability (optional) ------------------------ [](#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 ``` Fleet platform (v0.2) --------------------- [](#fleet-platform-v02) 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 [](#fleet-queries) `VelocityFleet::fleet($customerId)` returns a chainable `DeviceCollection`: ``` use ChrisJohnLeah\VelocityFleet\Laravel\Facades\VelocityFleet; $nearby = VelocityFleet::fleet($customer->id) ->moving() ->inDriverGroup(7) ->near($lat, $lon, 5.0); // within 5 km ``` Scopes: `moving()`, `idling()`, `ignitionOn()`, `ignitionOff()`, `online()`, `offline()`, `inDeviceGroup()`, `inDriverGroup()`, `near()`, `byRegistration()`, `withDriver()`. ### Caching (stale-while-revalidate) [](#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 [](#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 [](#geofences--notifications) Define circle or polygon `Geofence`s; 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) [](#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](SECURITY.md). ### Commands [](#commands) ``` php artisan velocity-fleet:poll {customer?} # dispatch a poll (also scheduled when polling on) php artisan velocity-fleet:prune-positions # retention prune (scheduled daily when history on) php artisan velocity-fleet:encrypt-tokens # migrate any plaintext token rows to ciphertext php artisan velocity-fleet:doctor # CI-runnable config/security self-check ``` ### Testing toolkit [](#testing-toolkit) ``` use ChrisJohnLeah\VelocityFleet\Laravel\Testing\InteractsWithVelocityFleet; use ChrisJohnLeah\VelocityFleet\Laravel\Testing\FakeDevice; // fakeFleet([...]) / FakeDevice::make([...]) / FakeDevicePositions::withDevices([...]) / FleetScenario ``` Testing ------- [](#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 ------------ [](#contributing) Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Please report security issues privately per [SECURITY.md](SECURITY.md). Licence ------- [](#licence) MIT © [Chris John Leah](https://github.com/chrisjohnleah). See [LICENSE](LICENSE). > Not affiliated with or endorsed by Radius or Velocity Fleet. "Radius", "Velocity" and "Kinesis" are trademarks of their respective owners. ### Health Score 37 — LowBetter than 81% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/ec2ce54c81968f6fc293587599bbaaa4221e303eec07cd2a50de1d99a6f0f2a4?d=identicon)[chrisjohnleah](/maintainers/chrisjohnleah) --- Top Contributors [![chrisjohnleah](https://avatars.githubusercontent.com/u/959104?v=4)](https://github.com/chrisjohnleah "chrisjohnleah (3 commits)") --- Tags laraveloauth2KinesisBridgeradiusfleetvelocitytelematicsvelocity-fleet ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/chrisjohnleah-velocity-fleet-api-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/chrisjohnleah-velocity-fleet-api-laravel/health.svg)](https://phpackages.com/packages/chrisjohnleah-velocity-fleet-api-laravel) ``` ### Alternatives [larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k51.0M7.4k](/packages/larastan-larastan)[laravel/ai The official AI SDK for Laravel. 9782.1M153](/packages/laravel-ai)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[spatie/laravel-health Monitor the health of a Laravel application 87311.3M149](/packages/spatie-laravel-health)[illuminate/queue The Illuminate Queue package. 20432.2M1.5k](/packages/illuminate-queue)[tallstackui/tallstackui TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications. 719160.4k12](/packages/tallstackui-tallstackui) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)