How biegalski-llc/nhtsa-vehicle-api works
1. What this repository is
- This is a PHP Composer library, not a standalone app.
- Its job is to provide a small, typed-ish facade over the NHTSA Vehicle API for:
- VIN decoding
- listing vehicle years
- listing makes
- listing models by make/year
2. Primary public entrypoint
- The main consumer-facing class is src/VehicleApi.php.
- The README shows the intended usage pattern: instantiate VehicleApi, then call methods like listYears(), listAllMakes(), listModelsByMake(), and decodeVin().
- This class is the API boundary for package users; the rest of the code is internal implementation detail.
3. Internal service split
- The implementation is organized into small service classes under src/Services:
- Listing/Years.php
- Listing/Makes.php
- Listing/Models.php
- Decode/Vin.php
- src/Services/Service.php is the shared base layer, likely holding common setup and/or shared helpers for the concrete services.
4. Main data-flow pattern
- Most methods follow the same flow:
1. accept a simple input such as a year, make ID, VIN, or a list of IDs
2. call the NHTSA API or read local configuration data
3. normalize and sort the output
4. return an array of vehicle records
- The README explicitly says all methods return an alphabetized array of data.
5. External integration boundary
- The package integrates with the NHTSA Vehicles API over HTTP.
- src/Traits/HttpRequestTrait.php strongly suggests HTTP request logic is centralized there instead of duplicated across services.
- config/nhtsa.php likely contains API base URL and endpoint configuration, keeping the remote service boundary isolated from the business logic.
6. Listing years: mostly local generation
- listYears() is different from the other calls: it does not need remote lookup for the year values themselves.
- The README indicates it generates a range from a provided starting year up to two years beyond the current year.
- That means the years subsystem is mostly a local data generator with no external dependency.
7. Listing makes: live vs curated
- Makes.php supports multiple source strategies:
- listAllMakes() pulls the full live make list from NHTSA
- listPreloadedMakes() reads from curated local config lists
- listAcceptedListMakes([...]) filters based on caller-supplied NHTSA make IDs
- The curated lists live under config/VehicleMakes/, with separate files for:
- default mixed list
- car/truck list
- motorcycle/scooter list
- This is a key architectural boundary: remote completeness vs local curated subsets.
8. Listing models: dependent on make and year
- Models.php builds model results from NHTSA data using upstream identifiers:
- by make ID only
- by make ID plus year
- The returned records include both make and model metadata, so this layer is responsible for joining/structuring the API response into a consumer-friendly shape.
9. VIN decoding
- src/Services/Decode/Vin.php handles VIN lookups.
- This is the most direct external-call use case: the caller provides a VIN string, and the service returns decoded vehicle details from NHTSA.
- Architecturally, it is separate from the listing flows, but likely reuses the same request and normalization infrastructure.
10. Shared traits
- DataSortTrait.php likely centralizes result ordering and/or array shaping so every service returns consistently sorted output.
- HttpRequestTrait.php centralizes HTTP behavior, reducing duplication and making the NHTSA integration consistent across services.
- These traits are part of the package’s internal plumbing, not the public API.
11. Static configuration as a data source
- The repository includes several config/data files rather than a database or cache layer.
- The preloaded make lists are stored as PHP arrays, which means the package can work offline for those curated make subsets.
- There is no persistence layer, queue, or background worker; all work appears to be request/response and in-memory transformation.
12. Testing and delivery
- Tests exist for the core listing behaviors: MakesTest, ModelsTest, and YearsTest.
- The presence of .travis.yml indicates CI automation, and phpunit.xml confirms PHPUnit-based testing.
- This repository is therefore a small, test-driven library with CI, a single public facade, internal services, and a clear external dependency on the NHTSA API.
Main entry points: Makes.php Makes · Models.php Models · Vin.php VIN Decode · VehicleApi.php Vehicle API
Components 13
Public API
Consumer-facing entrypoint for the package.
- Vehicle API · Main consumer entrypoint for listing and decoding methods.
src/VehicleApi.php
Services
Internal request and normalization logic for vehicle data.
- Service Base · Common service layer used by concrete vehicle operations.
src/Services/Service.php - Years · Generates year ranges and returns sorted year lists.
src/Services/Listing/Years.php - Makes · Lists all makes, curated makes, or accepted subsets.
src/Services/Listing/Makes.php - Models · Builds model records from make and year inputs.
src/Services/Listing/Models.php - VIN Decode · Decodes a VIN into vehicle details.
src/Services/Decode/Vin.php - HTTP Request · Centralized HTTP request behavior for NHTSA calls.
src/Traits/HttpRequestTrait.php - Data Sort · Shared sorting and output normalization helpers.
src/Traits/DataSortTrait.php
Config Data
Static configuration and curated make lists.
- NHTSA Config · Remote API base and endpoint configuration.
config/nhtsa.php - Make List · Default curated make list for offline or narrowed lookup.
config/VehicleMakes/preloadedMakeList.php - Car List · Curated car and truck make list.
config/VehicleMakes/preloadedCarMakeList.php - Moto List · Curated motorcycle and scooter make list.
config/VehicleMakes/preloadedMotoMakeList.php
External API
Remote NHTSA Vehicle API boundary.
- NHTSA API · Remote vehicle data source used for makes, models, and VIN decode.
Connections 21
- Vehicle API → Years: listYears · Public facade delegates year listing to the years service.
- Vehicle API → Makes: listMakes · Public facade delegates make listing to the makes service.
- Vehicle API → Models: listModels · Public facade delegates model listing to the models service.
- Vehicle API → VIN Decode: decodeVin · Public facade delegates VIN decoding to the decode service.
- Years → Data Sort: sort · Years output is normalized and alphabetized.
- Makes → Service Base: extends · Make listing builds on the shared service base.
- Makes → HTTP Request: http · Live make listing uses shared request handling.
- Makes → Data Sort: sort · Make results are normalized and alphabetized.
- Makes → Make List: curated · Default curated makes are loaded from static config.
- Makes → Car List: curated · Car and truck curated makes are loaded from static config.
- Makes → Moto List: curated · Motorcycle and scooter curated makes are loaded from static config.
- Makes → NHTSA API: live makes · Full make lists are retrieved from the NHTSA API.
- Models → Service Base: extends · Model listing builds on the shared service base.
- Models → HTTP Request: http · Model lookup uses shared request handling.
- Models → Data Sort: sort · Model results are normalized and alphabetized.
- Models → NHTSA API: live models · Model lists are retrieved from the NHTSA API.
- VIN Decode → Service Base: extends · VIN decoding builds on the shared service base.
- VIN Decode → HTTP Request: http · VIN lookup uses shared request handling.
- VIN Decode → Data Sort: sort · Decoded output is normalized and alphabetized.
- VIN Decode → NHTSA API: decode · VIN decode requests are sent to the NHTSA API.
- HTTP Request → NHTSA Config: config · HTTP behavior reads base and endpoint configuration.