DEV Community

Jose Luis Bermejo Meléndez
Jose Luis Bermejo Meléndez

Posted on

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

#php #symfony #laravel #api

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
Enter fullscreen mode Exit fullscreen mode

📦 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.

  1. Run the installation wizard: Execute the following Artisan command in your terminal: 
php artisan luhnify:install
Enter fullscreen mode Exit fullscreen mode
  1. 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.

  1. 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.

  2. 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 ###
Enter fullscreen mode Exit fullscreen mode

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.

  1. Require the Composer Autoload at the top of your script.

  2. 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);
Enter fullscreen mode Exit fullscreen mode

⚡ 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();
}
Enter fullscreen mode Exit fullscreen mode

🔒 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

Top comments (0)