Download the PHP package estin92/laravel-dvla-ves without Composer

Laravel DVLA VES

Laravel DVLA VES is a PHP package that looks up UK vehicle details by registration number through the official DVLA Vehicle Enquiry Service (VES) API.

Pass a number plate and it returns a typed, immutable VehicleData object exposing tax status, MOT status and expiry, fuel type, CO2 emissions, make, colour, year of manufacture and more.

It is built for Laravel 12 and 13 on PHP 8.2+, with first-class enums, response caching, a fake driver for testing and an Artisan lookup command. This package is an independent open-source connector and is not affiliated with or endorsed by the DVLA.

Install

Configure

Set your API key in .env:

You supply your own DVLA VES API key, obtained from the DVLA Developer Portal. Your use of the API is governed by DVLA's own terms of use - this package is an independent connector and is not affiliated with or endorsed by the DVLA.

Usage

lookup() returns a readonly VehicleData. Every wire field is exposed as a typed property - all nullable except registrationNumber (see Why is almost every field nullable? below):

Domain helpers wrap the nullable enums/flags and always return a plain bool:

Accessors return a typed value rather than a bool:

The enums carry their own helpers and a translatable label:

Failures throw - catch the base exception or a specific subclass:

Validating make

make is a plain ?string, not an enum, because the set of DVLA makes is open and grows continually, the casing is inconsistent (10Ten, AC (ELECTRIC), LYNK & CO), and there is no per-make behaviour to model — an enum would add friction and reject unseen-but-valid makes. When you need to validate or autocomplete against the known set, use the KnownMake reference helper instead:

A value absent from KnownMake is not necessarily invalid — the DVLA may have added it since the bundled snapshot.

Where this data comes from. The enum case lists (taxStatus, motStatus, fuelType, euroStatus, wheelplan, typeApproval) and the KnownMake make list come from a list the DVLA ([email protected]) sent on Friday 19 June 2026 at 11:46am. If you hit a value the enums resolve to Unknown (it's logged) or one that KnownMake doesn't recognise, please open a PR adding it.

The monthOfFirstRegistration / monthOfFirstDvlaRegistration fields are "YYYY-MM" strings by default. Either call getFirstRegistrationDate() for a CarbonImmutable or set DVLA_VES_CAST_YEAR_MONTH_ONLY_FIELDS_TO_CARBON=true to receive these properties as CarbonImmutable (start of month) directly.

Why is almost every field nullable?

DVLA has been tested and found to return a different subset of fields per vehicle, omitting the ones that don't apply rather than returning them as null. Every property except registrationNumber is typed ? and defaults to null when its key is absent. Across 21 real vehicle lookups, the number of responses that contained each field was:

We have opted to keep all fields, including those that appeared in all 21, nullable too - the sample can't guarantee every vehicle returns them. No captured response contained an explicit null; DVLA seems instead to only ever omit attributes. Typing every field as nullable means an omitted attribute defaults to null rather than triggering an unnecessary fatal error during hydration. To avoid null checks, use the boolean helpers (e.g. isElectric(), hasValidMot()), which treat a missing value as false.

API reference

• DvlaVes::lookup(string $registration): VehicleData
• DvlaVes::isConfigured(): bool.
• VehicleData - readonly DTO; full property and helper list shown under Usage.
• Enums: FuelType, TaxStatus, MotStatus, EuroStatus, Wheelplan, TypeApproval (each with fromApi() + translated label()).
• Support\KnownMake - reference helper for the make field: all(), isKnown(), canonical().
• Exceptions: VehicleNotFoundException, InvalidRegistrationException, RateLimitExceededException, ServiceUnavailableException - all extend DvlaVesException.

VehicleData::$automatedVehicle (?bool) is documented in the DVLA VES v1.2.0 OpenAPI reference (both the JSON spec and its rendered HTML), though DVLA's separate prose service-description page omits it. It is sparsely included and in practice, our testing has shown the DVLA only returns it for certain vehicles - so the raw property is nullable. Use isAutomatedVehicle() for a plain boolean; it returns false for both false and null, since a vehicle DVLA never flags is not an automated vehicle.

Caching (off by default)

Caches successful lookups keyed by normalised registration.

Testing

Artisan

AI agent support (Laravel Boost)

This package ships Laravel Boost resources - an AI guideline and a dvla-ves skill - so coding agents (Claude Code, Cursor, etc.) get accurate context about VehicleData, the enums, exceptions, caching and the fake driver.

Boost surfaces them once it is made aware of this package:

• If you install or reconfigure Boost with php artisan boost:install, this package's guideline and skill are offered for publishing.
• In a project where Boost is already installed, scan for this newly added package and be prompted to publish its resources with:

Plain php artisan boost:update only refreshes resources you have already published - it will not discover this package on its own, so use --discover (or re-run boost:install) the first time. Once published, the resources are recorded in boost.json and stay current on every boost:update. To automate that, add Boost's update command to your app's composer.json post-update-cmd scripts.

Contributing

Contributions are welcome — see SECURITY.md rather than opening a public issue.

License

MIT. See LICENSE.