How to Validate DNI, NIE, and Passports in PHP, Laravel & Symfony Projects

Jose Luis Bermejo Meléndez — Wed, 29 Jul 2026 18:06:13 +0000

Luhnify SDK for PHP

Validating national identity documents (such as Spain's DNI, NIE, or Passports) in web applications can quickly become a maintenance headache.

Maintaining custom regular expressions or checksum algorithms per country across different frameworks adds unnecessary technical debt.

The official luhnify/luhnify-php SDK provides a unified, zero-PII, stateless API to validate official identity documents natively in Laravel, Symfony, or Vanilla PHP.

🚀 1. Base Installation

Add the package to your project using Composer:

composer require luhnify/luhnify-php

📦 2. Environment Configuration

Depending on your application's architecture, choose your project type below to complete the setup in a single step:

🔹 Option A: If you are using Laravel (Automatic)

The SDK features Package Autodiscovery, meaning Laravel will automatically detect the package without requiring you to register Service Providers manually.

Run the installation wizard: Execute the following Artisan command in your terminal:

php artisan luhnify:install

What this command does for you:
- Securely prompts you for your private Luhnify API Key (X-API-Key) in the console.
- Automatically injects the LUHNIFY_API_KEY=your_key variable at the end of your .env file.
- Publishes the framework configuration file to config/luhnify.php.
- Registers the client as a singleton in the service container, ready for Dependency Injection.

🔹 Option B: If you are using Symfony (Automatic Script)

Thanks to the built-in installer hooked into Composer's lifecycle, the SDK auto-configures itself upon download without requiring manual YAML service mapping.

Check your project files:
After running composer require, the SDK will automatically create two things in your project:
- A global configuration file at config/packages/luhnify.yaml.
- An environment variable block at the bottom of your .env file.
Add your API Key:
Open your .env file and replace the placeholder value with your real credential:

# .env
###> luhnify/luhnify-php ###
LUHNIFY_API_KEY=your_real_luhnify_api_key_here
###< luhnify/luhnify-php ###

That's it! Symfony's Autowiring now automatically knows how to instantiate and inject the client into your controllers using this variable.

🔹 Option C: Native PHP / Vanilla PHP (Manual)

If you are not using a framework or are working on a custom legacy setup, initialization is performed explicitly at your application's entry point.

Require the Composer Autoload at the top of your script.
Instantiate the client manually:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Luhnify\ValidationSdk\ValidationClient;

// It is highly recommended to read the key from system environment variables
$apiKey = getenv('LUHNIFY_API_KEY') ?: 'your_direct_api_key_here';

$luhnify = new ValidationClient($apiKey);

⚡ 3. Quick Usage Example

Once configured, performing a document validation is exactly the same across all environments:

use Luhnify\ValidationSdk\ValidationPayload;
use Luhnify\ValidationSdk\LuhnifyException;

// 1. Prepare the document data you want to validate
$payload = new ValidationPayload([
    'country_code'    => 'es',
    'document_type'   => 'dni',
    'document_number' => '12345678Z'
]);

try {
    // 2. Execute validation against the official API
    $result = $luhnify->ValidateDocument($payload);

    if ($result->valid) {
        echo "Success: The document is valid.";
    } else {
        echo "Warning: The document did not pass validation rules.";
    }

} catch (LuhnifyException $e) {
    echo "Luhnify API Error ({$e->getStatusCode()}): " . $e->getMessage();
} catch (\Exception $e) {
    echo "Unexpected system error: " . $e->getMessage();
}

🔒 Security & Privacy

Zero PII Retention: Validation is stateless—document numbers are processed in memory and never persisted to a database.
Environment Isolation: Keep your LUHNIFY_API_KEY secure using .env files and avoid committing keys to version control.
All requests run securely over HTTPS targeting https://api.luhnify.com/v1.

🔗 Useful Links

Dashboard & API Keys: Luhnify.com
GitHub Repository: Luhnify PHP SDK

How to Validate DNI, NIE, CIF, and International Tax IDs in Your Backend

Jose Luis Bermejo Meléndez — Sat, 25 Jul 2026 10:30:05 +0000

Stop writing complex custom regexes for every country — validate format structures and checksums with a single lightweight API call.

Global ID format validation architecture

Handling identity document validation across international markets is a recurring pain point for software engineering teams. When onboarding users, entering invalid IDs or typos leads to corrupted database entries, failed billing pipelines, and compliance headaches. Writing custom regular expressions (regex) or local checksum algorithms (like Luhn or specific country rules) for dozens of countries quickly becomes an unmaintainable mess.

The Solution: Format Validation at the Input Stage

Instead of building and updating validation logic for every nation from scratch, you can offload structure and checksum validation to Luhnify, a free, lightweight API designed for real-time format verification across 200+ countries.

It checks the structure, character rules, and mathematical validity (checksums) without storing sensitive payload data or requiring slow biometric KYC processes.
Quick Integration Example

Here is how simple it is to validate an international ID using a single HTTP request:

curl -X POST https://api.luhnify.com/api/v1/validate \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_number": "12345678A",
    "document_type": "dni",
    "country_code": "ES"
  }'

You receive a clean JSON payload indicating whether the format and checksum are valid, allowing your frontend or backend to immediately accept or prompt the user for corrections:

{
  "valid": true,
  "message": "Document is valid."
}

Key Benefits

Ultra-fast Performance: Average response time under 50 ms, perfect for real-time form validation without slowing down user onboarding.
200+ Countries supported: Standardized responses regardless of nationality.
8 Official SDKs: Ready-to-use packages for PHP (Laravel, Symfony, native PHP), TypeScript, Java, Go, C#, Swift, Kotlin, and Python. Drop it into your stack with zero setup friction.
Zero PII Storage: High performance without unnecessary data retention risks.
Developer First: Built by engineers to keep onboarding forms clean and database inputs valid.

Try it out for free at luhnify.com and keep your registration flow clean!

DEV Community: Jose Luis Bermejo Meléndez