new Vat number validations

Author: tanthammar

CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Laravel package that provides custom validation rules, factory helpers, and services primarily focused on Swedish localization. The package includes validation rules for Swedish business/personal numbers, phone numbers, bank accounts, and VAT IDs.
+
+## Architecture
+
+### Core Components
+
+- **Rules**: Custom Laravel validation rules in `src/Rules/`
+- **Factories**: Faker providers for generating test data in `src/Factories/`
+- **Services**: Business logic services in `src/Services/`
+- **Helpers**: Legacy helper functions in `src/Helpers/` and `src/RuleHelpers.php`
+
+### Key Dependencies
+
+- `personnummer/personnummer`: Swedish personal number validation
+- `organisationsnummer/organisationsnummer`: Swedish organization number validation
+- `brick/phonenumber`: International phone number validation
+- `byrokrat/banking`: Swedish banking system validation
+- `mpociot/vat-calculator`: EU VAT validation services
+- `tanthammar/laravel-extras`: Custom Laravel utilities
+
+### Service Provider
+
+The `LaravelRulesServiceProvider` registers custom validation rules and handles translations:
+- Extends basic Laravel validators with Swedish-specific rules
+- Registers custom text validation rules: `alpha_space`, `alpha_num_space`, `alpha_dash_space`, etc.
+- Handles internationalization for Swedish (`sv`) and English (`en`)
+
+## Rule Architecture
+
+All validation rules follow Laravel's Rule contract and implement both legacy and modern validation patterns:
+- Legacy: `passes()` method with `message()` method
+- Modern: `validate()` method with closure-based failure handling
+
+### Key Validation Rules
+
+- **PersonNummer**: Swedish personal identification numbers
+- **OrgNummer**: Swedish organization numbers  
+- **VatNumber**: EU VAT ID validation with service availability handling
+- **PhoneNumber**: International phone numbers with automatic "+" prefix handling
+- **BankGiro/PlusGiro**: Swedish payment system validation
+- **BankKonto**: Swedish bank account validation
+
+## Development Workflow
+
+### Installation
+```bash
+composer require tanthammar/laravel-rules
+```
+
+### Usage Pattern
+```php
+use TantHammar\LaravelRules\Rules\PhoneNumber;
+use TantHammar\LaravelRules\Rules\PersonNummer;
+
+$field->rules([new PhoneNumber]);
+$field->rules([new PersonNummer]);
+```
+
+### Testing Data Generation
+Use factory classes for generating Swedish test data:
+```php
+FakePhoneNumber::make(international: true)
+FakePhoneNumber::gdprSafe() // GDPR-compliant test numbers
+```
+
+## Services and Deprecation
+
+The package has migrated from static helper methods to dedicated service classes:
+- `RuleHelpers::getBusinessNameFromVatID()` → `BusinessNameFromVatID::lookup()`
+- `RuleHelpers::getVATDetailsFromVatID()` → `VatDetailsFromVatID::lookup()`
+- `RuleHelpers::check_business_type()` → `BusinessTypeFromNr::make()`
+
+## Internationalization
+
+Translations are stored in `resources/lang/` with support for Swedish and English. Error messages are prefixed with `laravel-rules::messages.` for proper namespacing.
+
+## Development Commands
+
+This package does not include test suites, linting, or build scripts. Development is typically done by:
+- Installing the package in a Laravel project via `composer require tanthammar/laravel-rules`
+- Testing validation rules directly in Laravel applications
+- Manual testing of factory helpers and services
+
+## Development Notes
+
+- The package supports PHP 8.1+ and Laravel 10.0+
+- External API dependencies (VAT validation) include proper exception handling for service unavailability
+- Phone number validation automatically handles missing "+" prefix
+- All number inputs are cleaned using `CleanNumber::make()` from the extras package

README.md

@@ -1,33 +1,212 @@
-# Missing validation rules and fakers, for Laravel
-In this repository I will add validators and factory helpers, that I use in my SaaS app. I think especially Swedish developers will find them handy.
+# Laravel Rules & Validators
+Custom validation rules, factory helpers, and services for Laravel applications, with a focus on Swedish localization.
 
 ## Requirements
-- PHP 8.1
-- Laravel v9.0
+- PHP 8.1+
+- Laravel 10.0+
 
 ## Installation
 ```bash
 composer require tanthammar/laravel-rules
 ```
 
-## Rules, Fakers and more
-See src folder
+## Validation Rules
 
-## Documentation
-There won't be much documentation written, this repository will grow as I add items.
-Hopefully the source code contains enough hints to use the components.
+### Swedish Personal & Organization Numbers
+```php
+use TantHammar\LaravelRules\Rules\PersonNummer;
+use TantHammar\LaravelRules\Rules\OrgNummer;
+use TantHammar\LaravelRules\Rules\PersonOrOrgNummer;
+
+// Swedish personal identification numbers
+$request->validate([
+    'person_number' => [new PersonNummer]
+]);
+
+// Swedish organization numbers
+$request->validate([
+    'org_number' => [new OrgNummer]
+]);
 
-They are all used in the same way, following Laravel conventions. 
+// Accept either personal or organization numbers
+$request->validate([
+    'number' => [new PersonOrOrgNummer]
+]);
+```
 
-Example:
+### Phone Numbers
 ```php
 use TantHammar\LaravelRules\Rules\PhoneNumber;
-use TantHammar\LaravelRules\Rules\PersonNummer;
+use TantHammar\LaravelRules\Rules\MobileNumber;
+use TantHammar\LaravelRules\Rules\FixedLineNumber;
+
+// International phone numbers (handles missing + prefix automatically)
+$request->validate([
+    'phone' => [new PhoneNumber]
+]);
+
+// Mobile numbers only
+$request->validate([
+    'mobile' => [new MobileNumber]
+]);
+
+// Fixed line numbers only
+$request->validate([
+    'landline' => [new FixedLineNumber]
+]);
+```
+
+### Swedish Banking
+```php
+use TantHammar\LaravelRules\Rules\BankKonto;
+use TantHammar\LaravelRules\Rules\BankGiro;
+use TantHammar\LaravelRules\Rules\PlusGiro;
+
+// Swedish bank account numbers
+$request->validate([
+    'bank_account' => [new BankKonto]
+]);
+
+// BankGiro payment numbers
+$request->validate([
+    'bankgiro' => [new BankGiro]
+]);
+
+// PlusGiro payment numbers
+$request->validate([
+    'plusgiro' => [new PlusGiro]
+]);
+```
+
+### VAT Number Validation
+
+⚠️ **Important**: Choose the right VAT validation rule based on your needs:
+
+#### VatNumberFormat (Recommended for most cases)
+Only validates the format using regex - no external API calls.
+```php
+use TantHammar\LaravelRules\Rules\VatNumberFormat;
+
+$request->validate([
+    'vat_number' => [new VatNumberFormat]
+]);
+```
+
+#### VatNumberAPI (Use with caution)
+Validates against the VIES EU API but throws exceptions when service is unavailable.
+```php
+use TantHammar\LaravelRules\Rules\VatNumberAPI;
+use Mpociot\VatCalculator\Exceptions\VATCheckUnavailableException;
+
+try {
+    $request->validate([
+        'vat_number' => [new VatNumberAPI]
+    ]);
+} catch (VATCheckUnavailableException $e) {
+    // Handle service unavailability
+    // Service can be down for hours or days
+    return back()->withErrors([
+        'vat_number' => 'VAT validation service is temporarily unavailable. Please try again later.'
+    ]);
+}
+```
+
+#### VatNumberAPIWithFormatFallback (Balanced approach)
+Tries API validation first, falls back to format validation if service is unavailable.
+```php
+use TantHammar\LaravelRules\Rules\VatNumberAPIWithFormatFallback;
+
+$request->validate([
+    'vat_number' => [new VatNumberAPIWithFormatFallback]
+]);
+```
+
+### Geographic Coordinates
+```php
+use TantHammar\LaravelRules\Rules\Latitude;
+use TantHammar\LaravelRules\Rules\Longitude;
+
+$request->validate([
+    'lat' => [new Latitude],
+    'lng' => [new Longitude]
+]);
+```
+
+### File Upload Validation
+```php
+use TantHammar\LaravelRules\Rules\MaxTotalFileSize;
+
+// Limit total size of all uploaded files
+$request->validate([
+    'documents.*' => ['file'],
+    'documents' => [new MaxTotalFileSize(5000)] // 5MB total
+]);
+```
+
+## Factory Helpers
+
+Generate realistic test data for Swedish formats:
+
+```php
+use TantHammar\LaravelRules\Factories\FakePhoneNumber;
+use TantHammar\LaravelRules\Factories\FakeMobileNumber;
+use TantHammar\LaravelRules\Factories\FakeBankgiro;
+use TantHammar\LaravelRules\Factories\FakePlusgiro;
+
+// Generate Swedish phone numbers
+$phone = FakePhoneNumber::make(international: true);
+$localPhone = FakePhoneNumber::make(international: false);
+
+// GDPR-safe phone numbers (official test ranges)
+$gdprPhone = FakePhoneNumber::gdprSafe();
+
+// Mobile numbers
+$mobile = FakeMobileNumber::make();
+
+// Payment numbers
+$bankgiro = FakeBankgiro::make();
+$plusgiro = FakePlusgiro::make();
+```
+
+## Services
+
+### VAT Information Lookup
+```php
+use TantHammar\LaravelRules\Services\BusinessNameFromVatID;
+use TantHammar\LaravelRules\Services\VatDetailsFromVatID;
+
+// Get business name from VAT ID
+$businessName = BusinessNameFromVatID::lookup('SE556556567801');
+
+// Get full VAT details
+$details = VatDetailsFromVatID::lookup('SE556556567801');
+```
+
+### Business Type Detection
+```php
+use TantHammar\LaravelRules\Helpers\BusinessTypeFromNr;
+
+// Determine if number is personal, business, or undefined
+$type = BusinessTypeFromNr::make('199001011234'); // Returns: 'individual'
+$type = BusinessTypeFromNr::make('556556567801'); // Returns: 'business'
+$type = BusinessTypeFromNr::make('invalid');     // Returns: 'undefined'
+```
+
+## Legacy Helper Methods (Deprecated)
+
+These methods are deprecated but still available for backwards compatibility:
+
+```php
+use TantHammar\LaravelRules\RuleHelpers;
+
+// Use BusinessNameFromVatID::lookup() instead
+$name = RuleHelpers::getBusinessNameFromVatID($vatId);
+
+// Use VatDetailsFromVatID::lookup() instead  
+$details = RuleHelpers::getVATDetailsFromVatID($vatId);
 
-SomeField::make('phone')
-    ->rules([ new PhoneNumber ])
-SomeField::make('person_nummer')
-    ->rules([ new PersonNummer ])
+// Use BusinessTypeFromNr::make() instead
+$type = RuleHelpers::check_business_type($number);
 ```
 
 

composer.json

@@ -20,7 +20,7 @@
         "php": "^8.1|^8.2|^8.3|^8.4",
         "brick/phonenumber": "^0.8.0",
         "byrokrat/banking": "^2.2",
-        "laravel/framework": "^9.0|^10.0|^11.0|^12.0",
+        "laravel/framework": "^10.0|^11.0|^12.0",
         "personnummer/personnummer": "^3.0.4",
         "organisationsnummer/organisationsnummer": "^2.0.0",
         "mpociot/vat-calculator": "^3.22.0",

resources/lang/en/messages.php

@@ -18,6 +18,7 @@
     'latitude' => 'The latitude value is invalid',
     'longitude' => 'The longitude value is invalid',
     'vat-service-unavailable' => 'Sorry, but the "VIES EU Vat service" is unavailable. Unable to validate your Vat ID. Please try again later or contact support for personal assistance.',
+    'vies-eu-unavailable' => "VIES EU Vat service is unavailable. Please try again later.",
     'vat-invalid' => 'The :attribute is not a valid VAT ID number.',
     'vat-name-unknown' => 'Unknown legal name',
     'total-file-sizes' => 'The sum of all file sizes should not exeed :kb Kb.',

resources/lang/sv/messages.php

@@ -17,7 +17,8 @@
     'plusgiro' => 'Du måste ange ett giltigt PlusGiro nummer',
     'latitude' => 'Latitude värdet är felaktigt',
     'longitude' => 'Longitude värdet är felaktigt',
-    'vat-service-unavailable' => 'Tyvärr svarar inte "VIES EU Vat test service". Det är därför omöjligt att verifiera ditt Moms-nr. Vänligen försök om en stund igen eller kontakta support för manuell hantering.',
+    'vat-service-unavailable' => 'Tyvärr svarar inte "VIES EU Vat test service". Det är därför omöjligt att verifiera ditt Moms-nr. Vänligen försök senare eller kontakta support för manuell hantering.',
+    'vies-eu-unavailable' => "VIES EU Vat service är inte tillgänglig. Vänligen försök senare.",
     'vat-invalid' => ':Attribute är ej ett giltigt momsregistreringsnummer',
     'vat-name-unknown' => 'Juridiskt namn saknas',
     'total-file-sizes' => 'Summan av filernas storlek får inte överstiga :kb Kb.',