README

Lararoi is the Laravel package that owns the intra-community VAT/NIF verification domain: the verification itself, its cache, and a multi-consumer tracking/audit log — served to consuming apps through explicit, stable contracts and agnostic configuration. Consumers (billing, accounting, …) consume it; they never reimplement the domain.

The verification model is provider-agnostic (VIES SOAP/REST, isvat, viesapi, vatlayer) with automatic fallback and per-country syntax validation. See the architecture decisions (ADR-001, ADR-002) for the domain-ownership rationale.

Features

✅ VAT/NIF verification via VIES (European Commission) + multiple free/paid providers, with automatic fallback
✅ Per-country syntax validation (short-circuits obviously invalid numbers without hitting a provider)
✅ TTL cache (memory + database), one current row per NIF, enforced by a UNIQUE key
✅ Multi-consumer tracking / audit log — append-only, consumer-attributed, inert by default
✅ Per-consumer retention (declared in config, UTC) with a prune command
✅ Per-consumer output mapping — adapt the canonical result to your own shape without forking code
✅ Formal, documented contract set — swap the model, the tracking model, or the mapper via config/contracts
✅ Robust, typed error handling; development commands for testing against real APIs

Requirements

PHP 8.3+
Laravel 12+

Installation

composer require aichadigital/lararoi

The database schema is package-managed — just run migrations, no stub to publish:

php artisan migrate

This creates the cache table roi_vat_verifications and the tracking table roi_verification_queries. Optionally publish the config to tune providers, cache, tracking and retention:

php artisan vendor:publish --tag="lararoi-config"

Basic Usage

use Aichadigital\Lararoi\Contracts\VatVerificationServiceInterface;

$result = app(VatVerificationServiceInterface::class)
    ->verifyVatNumber('B12345678', 'ES');

if ($result['is_valid']) {
    echo "Valid VAT: {$result['company_name']}";
}

Tracking is off by default. A consumer that wants an audit trail enables lararoi.tracking.enabled, registers itself in the lararoi.consumers allow-list (with a retention policy), and passes a VerificationContext — see the Integration Guide.

Documentation

Integration Guide — install → verify → track → retain → map (the full consumer flow)
Contracts — the public contract set (interfaces, value object, exceptions)
Configuration — config keys and environment variables
Usage Guide — usage patterns and examples
Architecture Decisions — ADR-001 (domain ownership), ADR-002 (v1.0 design)
Development Guide — development commands and testing with real APIs
Contributing — guidelines for contributors

Testing & Quality

Pest PHP test suite, PHPStan level 5, Laravel Pint, GitHub Actions CI.

composer test        # run the suite
composer quality     # pint + phpstan + tests

License

The MIT License (MIT). Please see License File for more information.

aichadigital / lararoi

Maintainers

Package info

Fund package maintenance!

Statistics

Security