Validation Laravel Package

Getting Started

composer require anetwork/validation

The package wires itself into Laravel via a service provider that calls Validator::extend(...) for a set of Iranian/Persian-specific rules. On Laravel 5.5+ auto-discovery handles registration; on older 5.x apps add the provider manually to config/app.php:

'providers' => [
    // ...
    Anetwork\Validation\ValidationServiceProvider::class,
],

If the package ships a config or lang directory, publish it once so you can edit messages:

php artisan vendor:publish --provider="Anetwork\Validation\ValidationServiceProvider"

Where to look first: open src/ValidationServiceProvider.php (or equivalent) and read the boot() method. Every Validator::extend('name', ...) call is the authoritative list of rule strings you can use — the README on an archived package is often out of sync with the code. Next, look at the lang/ directory for the message keys, because those keys are what you override later.

First use case — a Persian registration form:

$validated = $request->validate([
    'first_name'    => 'required|string|max:255|persian_alpha',
    'last_name'     => 'required|string|max:255|persian_alpha',
    'mobile'        => 'required|ir_mobile',
    'national_code' => 'required|ir_national_code',
    'postal_code'   => 'nullable|ir_postal_code',
]);

Rule names vary by version (persian_alpha, persian_num, ir_mobile, ir_national_code, ir_postal_code, ir_bank_card_number, ir_sheba, ir_currency, persian_alpha_num, …). Confirm each one against the provider before shipping — don't trust a blog post.

Implementation Patterns

Compose with core rules, not instead of them. Package rules are single-purpose regex/checksum checks. Always pair them with required, string, max:, nullable:

'mobile' => ['required', 'string', 'ir_mobile'],

Form Requests are the natural home. For anything with more than two Persian fields, move rules out of controllers:

class StoreProfileRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name'          => ['required', 'string', 'max:100', 'persian_alpha'],
            'phone'         => ['required', 'ir_mobile'],
            'national_code' => ['required', 'ir_national_code'],
        ];
    }

    public function messages(): array
    {
        return [
            'name.persian_alpha'   => 'نام باید فقط شامل حروف فارسی باشد.',
            'phone.ir_mobile'      => 'شماره موبایل معتبر نیست.',
            'national_code.ir_national_code' => 'کد ملی معتبر نیست.',
        ];
    }
}

Normalize input before validating. This is the pattern that saves the most time in production. Persian keyboard digits (۰-۹), Arabic-Indic digits (٠-٩), Arabic yeh/kaf (ي, ك), and ZWNJ (‌) routinely cause otherwise-valid input to fail regex rules:

protected function prepareForValidation(): void
{
    $this->merge([
        'mobile' => strtr($this->mobile, [
            '۰'=>'0','۱'=>'1','۲'=>'2','۳'=>'3','۴'=>'4','۵'=>'5','۶'=>'6','۷'=>'7','۸'=>'8','۹'=>'9',
            '٠'=>'0','١'=>'1','٢'=>'2','٣'=>'3','٤'=>'4','٥'=>'5','٦'=>'6','٧'=>'7','٨'=>'8','٩'=>'9',
            'ي'=>'ی','ك'=>'ک', ' '=>'',
        ]),
    ]);
}

Reusable rule sets for APIs. For JSON endpoints, return 422 with $validator->errors(); the package rules slot in unchanged because they're plain Laravel validator extensions:

$validator = Validator::make($request->all(), [
    'sheba' => ['required', 'ir_sheba'],
]);

if ($validator->fails()) {
    return response()->json(['errors' => $validator->errors()], 422);
}

Front-end pairing. Bind a small JS normalizer to the same fields so users see consistent feedback; the server-side prepareForValidation() is the safety net, not the primary UX.

Testing. Rules are pure and fast to test without HTTP:

$this->assertTrue(Validator::make(
    ['code' => '0013542419'],
    ['code' => 'ir_national_code']
)->passes());

Build a small matrix of valid/invalid fixtures per rule (especially national code checksums and bank card Luhn) and lock it in before you touch the package.

Gotchas and Tips

Archived since 2017 — this is the big one. The package predates Laravel 6+ and PHP 8. Expect composer require to fail on modern apps due to laravel/framework / php constraints. Options, in order of preference: (1) copy the regex/checksum logic into your own invokable rule classes (php artisan make:rule PersianAlpha) — the logic is small and self-contained; (2) fork the repo, loosen constraints, and maintain it internally; (3) install with --ignore-platform-reqs only as a stopgap. Do not plan on upstream fixes.

Rule names are global and unprefixed. Another package defining ir_mobile or persian_num will silently conflict — last Validator::extend() wins. If you have overlapping validation packages, grep vendor/ for the rule name before debugging your own rules.

National code is checksum-based, not length-based. A 10-digit string can still be invalid. Test with known-good codes; sequences of identical digits (e.g. 1111111111) are commonly rejected by the algorithm. If users report false negatives, verify the checksum implementation by hand rather than assuming the rule is broken.

Digit and character normalization is the #1 source of "the rule is wrong" tickets. Persian users type Persian digits, half-spaces, and Arabic look-alike letters. Normalize before validation (see above), and be aware that some versions of persian_alpha reject ZWNJ — decide explicitly whether names with ZWNJ should pass, and add a custom rule if the package disagrees.

Spaces and country prefixes in phone/IBAN rules. ir_mobile typically expects 09xxxxxxxxx with no spaces, while ir_sheba may expect IR + 24 digits. Strip spaces and dashes in prepareForValidation() rather than loosening the regex.

Message overrides may not take. If you published the lang file but still see English or generic messages, check the exact message key the rule uses — some packages use validation.persian_alpha while others use a custom namespace. php artisan view:clear and config:clear after publishing doesn't hurt.

Debugging checklist for a mysteriously failing rule:

1. Validator::make($data, $rules)->errors()->toArray() in Tinker — confirm which rule fired.
2. array_keys(app('validator')->extensions) — confirm the rule is actually registered.
3. Feed a hand-verified known-good value (e.g. a national code you validated on paper) to isolate checksum bugs from normalization bugs.
4. Log the raw input alongside the normalized input; most failures are the raw value reaching the validator.

Extension points worth knowing. You can add project-specific Iranian rules without touching the package:

Validator::extend('ir_melli_suffix', function ($attribute, $value) {
    return preg_match('/^[0-9]{10}$/', $value) === 1;
});

Validator::replacer('ir_melli_suffix', function ($message, $attribute, $rule, $parameters) {
    return str_replace(':attribute', $attribute, 'The :attribute is not a valid Iranian national code.');
});

Migration path when you outgrow it. Each rule maps cleanly onto a Laravel Rule object. Port them one at a time, keep the existing rule strings as aliases during the transition, and you can drop the dependency entirely without touching form requests.