marcinjean/laravel-vpic

Laravel-native vPIC (NHTSA) VIN decoder with exception-based flow and idempotent persistence.

1.3.1 2025-09-29 01:27 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Suggests

• guzzlehttp/guzzle: ^7.7|^8.0

MIT

README

A lightweight, Laravel-native wrapper around NHTSA’s vPIC API for decoding VINs — with:

• Exception-based error handling using vPIC ErrorCode/ErrorText
• Clean, idempotent persistence (single canonical hash over full payload)
• Batch decoding with per-VIN errors
• Simple service (VPicService) and optional Facade (VPic) for ergonomic use

Works great for repair-story pipelines, TSB indexing, and recall integrations.

✨ Features

• Decode single or batch VINs via vPIC REST endpoints
• Throws meaningful exceptions:
  • InvalidVinException (bad VIN format)
  • VpicHttpException (HTTP failure)
  • VpicDecodeException (vPIC ErrorCode != 0; exposes ErrorText)
• Database persistence (optional) into vpic_decoded_vins with a single SHA-256 hash to avoid churn
• Sanitized payloads (common “nullish” values → null) and trimmed strings
• Publishable config + migration
• Clean service contract for future offline driver support

🧩 Requirements

• PHP: 8.2+
• Laravel: 11.x or 12.x (works with 10.x if you adjust constraints)
• PHP ext-json
• Laravel HTTP client available (standard in modern Laravel)

📦 Installation

composer require marcinjean/laravel-vpic
php artisan vendor:publish --tag=vpic-config
php artisan vendor:publish --tag=vpic-migrations
php artisan migrate