README

⚠️ BETA VERSION - Active Development This package is currently in beta (v0.2.x). The API and configuration may change significantly in future versions. Use in production at your own risk. We recommend pinning to a specific version in your composer.json.

Agnostic package for intra-community NIF-VAT/VAT verification in Laravel.

Description

Lararoi is an independent package that provides services to verify tax identification numbers (NIF-VAT) of intra-community operators in the European Union. It is designed to be agnostic and reusable, although its main use is as a dependency of the Larabill package.

Features

• ✅ Verification via VIES (European Commission)
• ✅ Support for multiple API providers (free and paid)
• ✅ Integrated caching system (memory + database)
• ✅ Automatic fallback between providers
• ✅ Robust error handling
• ✅ Logging and auditing
• ✅ Development commands for testing with real APIs

Installation

composer require aichadigital/lararoi

Configuration

Publish the configuration:

php artisan vendor:publish --provider="Aichadigital\Lararoi\LararoiServiceProvider" --tag="config"

Publish the migrations:

php artisan vendor:publish --provider="Aichadigital\Lararoi\LararoiServiceProvider" --tag="migrations"
php artisan migrate

Basic Usage

use Aichadigital\Lararoi\Contracts\VatVerificationServiceInterface;

$service = app(VatVerificationServiceInterface::class);

$result = $service->verifyVatNumber('B12345678', 'ES');

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

Documentation

Complete documentation is available in the docs/ directory:

• Usage Guide - Basic usage, configuration, and examples
• Configuration - Detailed configuration options and environment variables
• Integration Guide - How to integrate with other packages (e.g., Larabill)
• Project Information - Complete documentation of available APIs and services
• Development Guide - Development commands and testing with real APIs
• Contributing - Guidelines for developers and contributors
• License - MIT License

Testing & Quality

The package maintains high quality standards with:

• ✅ Automated tests with Pest PHP
• ✅ Static analysis with PHPStan (level 5)
• ✅ Code style with Laravel Pint
• ✅ Code coverage minimum of 20%
• ✅ CI/CD with GitHub Actions

To run tests locally:

# Run tests
composer test

# Run tests with coverage
composer test:coverage

# Static analysis with PHPStan
composer analyse

# Format code
composer format

License

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

Credits

• Abdelkarim Mateos
• Aicha Digital
• All Contributors