Key Files in the Laravel-Validate Repository: A Complete Guide

The laravel-validate repository centers around a service provider that registers validation rules, a configuration file for customization, individual rule classes in src/Rules/, utility callbacks for phone validation, and translation files for localized error messages.

The laravel-validate package by milwad-dev extends Laravel's validation system with specialized rules for VAT IDs, IBANs, strong passwords, and more. Understanding the key files in the laravel-validate repository helps developers customize validation logic, add country-specific phone validators, and maintain clean separation between rule implementations. This guide breaks down the core architecture, utility classes, and localization structure that power this open-source validation library.

Core Architecture and Entry Points

Service Provider (src/LaravelValidateServiceProvider.php)

The LaravelValidateServiceProvider.php file serves as the bootstrap mechanism for the entire package. In its register() method, the provider publishes language and configuration assets when running in console mode and loads the package's translation namespace. The boot() method handles dynamic rule registration by reading the phone-country and landline-country arrays from the config and invoking CountryPhoneCallback::addValidator() and CountryLandlineCallback::addValidator() to register country-specific validators.

If the using_container option is set to true in the configuration, the service provider automatically scans the src/Rules/ directory and registers each rule with Laravel's validator container using Validator::extend(). This enables developers to use snake-cased rule names (e.g., valid_vatid) directly in validation arrays without manually instantiating classes.

Configuration File (config/laravel-validate.php)

The laravel-validate.php configuration file controls optional features and extensibility points. It contains three primary sections:

• using_container: A boolean flag that toggles automatic container-based rule registration.
• phone-country: An associative array mapping ISO country codes to custom validator classes (e.g., ['IR' => \App\Validators\IranPhoneValidator::class]).
• landline-country: A similar array for landline-specific validation logic.

This configuration allows developers to inject custom phone validation logic for specific regions without modifying the core rule classes.

Validation Rule Implementation

Rule Classes (src/Rules/)

The src/Rules/ directory contains the heart of the package—individual validation rule classes. Each file implements Laravel's Rule contract or provides a passes() method that encapsulates specific validation logic. Key examples include:

• ValidVatId.php: Validates European VAT identification numbers.
• ValidUuid.php: Validates UUID formats (v4, v5, etc.).
• ValidUsername.php: Enforces username format constraints.
• ValidStrongPassword.php: Checks password strength against configurable criteria.
• ValidIban.php: Validates International Bank Account Numbers using shared logic from IbanTrait.

These classes follow a consistent naming convention where each rule is prefixed with Valid and uses PascalCase. When using_container is enabled, Laravel automatically maps snake_case rule names (e.g., valid_uuid) to these classes.

Utility Callbacks for Phone and Landline

The package uses two utility classes to manage extensible phone validation:

• src/Utils/CountryPhoneCallback.php: Maintains a registry of country-specific phone validators. The static addValidator($code, $class) method allows developers to register custom classes for specific country codes. The ValidPhoneNumber rule queries this registry to determine which validation logic to apply based on the country parameter.
• src/Utils/CountryLandlineCallback.php: Provides identical functionality for landline numbers, supporting the ValidLandlineNumber rule.

This callback architecture decouples the rule implementation from country-specific validation logic, enabling third-party extensions without core modifications.

Shared Traits (src/Traits/IbanTrait.php)

The src/Traits/IbanTrait.php file contains reusable IBAN validation logic used by ValidIban.php. This trait likely implements checksum algorithms and country-specific IBAN length validation, allowing multiple rules or future extensions to share the same validation logic without code duplication.

Localization and Documentation

Translation Files (lang/)

The lang/ directory houses localization files for validation error messages. Each subdirectory represents a locale (e.g., en/, pt_BR/, zh_CN/), containing a validate.php file that maps rule names to human-readable error messages. When the service provider publishes these files, they become available under resources/lang/vendor/validation/ in the host application, allowing developers to customize messages or add new translations.

Documentation and Tests

• docs/1.x/: Contains Markdown documentation for each rule (e.g., valid-vatid.md), providing usage examples, parameters, and edge cases.
• tests/Rules/: A comprehensive PHPUnit test suite where each rule has a corresponding test class (e.g., ValidVatIdTest.php) ensuring correctness across different inputs and locales.

Practical Usage Examples

Enabling Container-Based Registration

To use snake-cased rule names without manual instantiation, publish and modify the configuration:

php artisan vendor:publish --tag=laravel-validate-config

Then set in config/laravel-validate.php:

'using_container' => true,

Now you can validate using string-based rules:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(
    [
        'vat_id'   => 'NL123456789B01',
        'password' => 'StrongP@ssw0rd!',
    ],
    [
        'vat_id'   => 'valid_vatid',
        'password' => 'valid_strong_password'
    ]
);

Adding a Custom Country Phone Validator

Create a custom validator class:

namespace App\Validators;

class MyCountryPhoneValidator
{
    public function validate($attribute, $value, $parameters)
    {
        // Custom validation logic for country code 'XX'
        return preg_match('/^\+123\d{8}$/', $value);
    }
}

Register it in config/laravel-validate.php:

'phone-country' => [
    'XX' => \App\Validators\MyCountryPhoneValidator::class,
],

The ValidPhoneNumber rule will now use your custom logic when validating phone numbers for country code XX.

Summary

• src/LaravelValidateServiceProvider.php – Bootstraps the package, publishes assets, and registers validation rules via the container or direct instantiation.
• config/laravel-validate.php – Controls automatic rule registration (using_container) and maps country codes to custom phone/landline validators.
• src/Rules/*.php – Individual rule classes (e.g., ValidVatId.php, ValidUuid.php) that implement specific validation logic.
• src/Utils/CountryPhoneCallback.php & CountryLandlineCallback.php – Utility classes that register and manage country-specific phone validation callbacks.
• src/Traits/IbanTrait.php – Reusable IBAN validation logic shared across rules.
• lang/ – Localization files providing translated error messages for supported locales.
• tests/ & docs/ – PHPUnit test suite and Markdown documentation ensuring reliability and developer guidance.

Frequently Asked Questions

What is the purpose of the LaravelValidateServiceProvider.php file?

The LaravelValidateServiceProvider.php file serves as the package's bootstrap mechanism. It registers the package's translation namespace, publishes configuration and language files, and conditionally registers validation rules with Laravel's container when the using_container config option is enabled. It also initializes country-specific phone and landline validators based on the configuration mappings.

How does the using_container configuration option affect rule usage?

When using_container is set to true in config/laravel-validate.php, the service provider automatically scans the src/Rules/ directory and registers each rule with Laravel's validator using Validator::extend(). This allows developers to use snake-cased string rule names (like valid_vatid or valid_uuid) directly in validation arrays without manually instantiating rule classes.

What is the role of the CountryPhoneCallback utility class?

The CountryPhoneCallback.php file provides an extensible registry for country-specific phone validation logic. It exposes a static addValidator($code, $class) method that maps ISO country codes to custom validator classes. When the ValidPhoneNumber rule executes, it queries this registry to determine which validation logic to apply based on the country parameter provided, allowing developers to add support for new countries without modifying core rule files.

Where are the error messages for validation rules stored?

Error messages are stored in the lang/ directory, with subdirectories for each supported locale (such as en/, pt_BR/, or zh_CN/). Each locale contains a validate.php file that maps rule names to human-readable error messages. When you publish the package assets using php artisan vendor:publish --tag=validate-lang-en, these files are copied to resources/lang/vendor/validation/ in your application, allowing you to customize messages or add new translations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}