README

???????? Laravel Persian Validation

The Most Complete & Modern Persian Validation Package for Laravel

A comprehensive Laravel validation package for Persian (Farsi) language and Iranian-specific data validation. This package provides a complete set of validation rules for Persian text, Iranian national codes, mobile numbers, bank account numbers (Sheba), postal codes, Shamsi dates, and much more.

???? Why Choose This Package?

✅ Modern Laravel Support - Laravel 10.x, 11.x, 12.x
✅ Dual Validation Approach - Both ValidationRule objects AND string-based rules
✅ Complete Persian Coverage - All Iranian data formats supported
✅ High Performance - Optimized validation algorithms
✅ Comprehensive Testing - 100% test coverage
✅ Active Maintenance - Regular updates and security patches
✅ Developer Friendly - Excellent documentation and examples

???? Competitive Advantages

✨ Features

• ???? Persian Text Validation: Persian alphabet and number validation
• ???? Iranian Mobile Numbers: Complete validation for all Iranian mobile operators
• ???? Banking: Sheba (IBAN) validation for Iranian banks
• ???? National Code: Iranian national identification code validation
• ???? Postal Code: Iranian postal code format validation
• ???? Phone Numbers: Landline and area code validation
• ???? Payment Cards: Credit/debit card number validation with Luhn algorithm
• ???? Username: Standard username format validation
• ???? Base64: Base64 string format validation
• ???? Address: Multi-language address validation

???? Requirements

• PHP: 8.1, 8.2, 8.3, 8.4
• Laravel: 10.x, 11.x, 12.x
• PHPUnit: 10.x, 11.x, 12.x (for testing)

???? Installation

Install the package via Composer:

composer require iamfarhad/validation

The package will automatically register itself with Laravel's service container.

???? Migration from Other Packages

From sadegh19b/laravel-persian-validation

This package provides a modern alternative with backward compatibility:

// Old way (still works) 'mobile' => ['ir_mobile'] // New modern way  'mobile' => [new Mobile()] // Both approaches are supported!

Migration Benefits:

• ✅ Keep your existing validation rules
• ✅ Gradually migrate to modern ValidationRule objects
• ✅ Better IDE support and type safety
• ✅ Improved performance

⚡ Quick Start

use Iamfarhad\Validation\Rules\{NationalCode, Mobile, ShamsiDate}; // Validate Iranian user registration $validator = Validator::make($request->all(), [ 'first_name' => ['required', 'persian_alpha'], 'last_name' => ['required', 'persian_alpha'], 'national_code' => ['required', new NationalCode()], 'mobile' => ['required', new Mobile()], 'birth_date' => ['required', new ShamsiDate()], 'company_id' => ['nullable', 'ir_company_id'], ]); if ($validator->fails()) { return response()->json(['errors' => $validator->errors()], 422); }

???? Usage

This package supports both modern ValidationRule objects and traditional string-based validation rules for maximum flexibility and compatibility.

???? Two Ways to Use Validation Rules

1. Modern ValidationRule Objects (Recommended)

use Illuminate\Support\Facades\Validator; use Iamfarhad\Validation\Rules\{NationalCode, Mobile, ShamsiDate}; $validator = Validator::make($request->all(), [ 'national_code' => ['required', new NationalCode()], 'mobile' => ['required', new Mobile()], 'birth_date' => ['required', new ShamsiDate()], ]);

2. String-based Rules (Laravel Traditional Style)

use Illuminate\Support\Facades\Validator; $validator = Validator::make($request->all(), [ 'national_code' => ['required', 'ir_national_code'], 'mobile' => ['required', 'ir_mobile'], 'birth_date' => ['required', 'shamsi_date'], 'domain' => ['required', 'domain'], 'website' => ['required', 'url_format'], ]);

???? In Form Requests

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\{Mobile, NationalCode, PersianAlpha, ShamsiDate}; public function rules(): array { return [ 'first_name' => ['required', new PersianAlpha()], 'last_name' => ['required', new PersianAlpha()], 'national_code' => ['required', new NationalCode()], 'mobile' => ['required', new Mobile()], 'birth_date' => ['nullable', new ShamsiDate()], ]; }

Using String-based Rules

public function rules(): array { return [ 'first_name' => ['required', 'persian_alpha'], 'last_name' => ['required', 'persian_alpha'], 'national_code' => ['required', 'ir_national_code'], 'mobile' => ['required', 'ir_mobile'], 'birth_date' => ['nullable', 'shamsi_date'], 'company_id' => ['nullable', 'ir_company_id'], 'website' => ['nullable', 'url_format'], 'username' => ['required', 'username_format'], ]; }

???? Available Validation Rules

???? Quick Reference Table

???? String Rules with Parameters

For rules that require parameters, use the following syntax:

// Shamsi date with custom separator 'birth_date' => ['required', 'shamsi_date:-,false'], // separator: -, convertPersianNumbers: false // Shamsi date between years 'event_date' => ['required', 'shamsi_date_between:1380,1420,/,true'], // startYear: 1380, endYear: 1420, separator: /, convertPersianNumbers: true

???? Detailed Examples

???? Persian Text Validation

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\{PersianAlpha, PersianNumber, PersianAlphaNum, PersianAlphaEngNum}; // Persian alphabet only Validator::make(['name' => 'فارسی'], [ 'name' => [new PersianAlpha()] ]); // Persian numbers only Validator::make(['number' => '۱۲۳۴۵'], [ 'number' => [new PersianNumber()] ]); // Persian alphabet + Persian numbers Validator::make(['text' => 'فارسی۱۲۳'], [ 'text' => [new PersianAlphaNum()] ]); // Persian alphabet + English numbers Validator::make(['text' => 'فارسی123'], [ 'text' => [new PersianAlphaEngNum()] ]);

Using String Rules

// Persian alphabet only Validator::make(['name' => 'فارسی'], [ 'name' => ['persian_alpha'] ]); // Persian numbers only Validator::make(['number' => '۱۲۳۴۵'], [ 'number' => ['persian_number'] ]); // Persian alphabet + Persian numbers Validator::make(['text' => 'فارسی۱۲۳'], [ 'text' => ['persian_alpha_num'] ]); // Persian alphabet + English numbers Validator::make(['text' => 'فارسی123'], [ 'text' => ['persian_alpha_eng_num'] ]);

???? Iranian Mobile Numbers

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\Mobile; // Supports all Iranian operators (Irancell, Rightel, Hamrah-e Avval, etc.) Validator::make(['mobile' => '09123456789'], [ 'mobile' => [new Mobile()] ]);

Using String Rules

// Iranian mobile validation Validator::make(['mobile' => '09123456789'], [ 'mobile' => ['ir_mobile'] ]);

???? National Code Validation

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\NationalCode; // Validates Iranian national identification codes Validator::make(['national_code' => '0112169228'], [ 'national_code' => [new NationalCode()] ]);

Using String Rules

// Iranian national code validation Validator::make(['national_code' => '0112169228'], [ 'national_code' => ['ir_national_code'] ]);

Banking (Sheba) Validation

use Iamfarhad\Validation\Rules\Sheba; // Iranian bank account numbers (IBAN format) Validator::make(['account' => 'IR930150000001351800087201'], [ 'account' => [new Sheba()] ]);

Phone Numbers

use Iamfarhad\Validation\Rules\Phone; use Iamfarhad\Validation\Rules\PhoneArea; // Landline numbers Validator::make(['phone' => '22345678'], [ 'phone' => [new Phone()] ]); // With area code Validator::make(['phone_area' => '02122345678'], [ 'phone_area' => [new PhoneArea()] ]);

Payment Cards

use Iamfarhad\Validation\Rules\CardNumber; // Validates using Luhn algorithm Validator::make(['card' => '4532015112830366'], [ 'card' => [new CardNumber()] ]);

Persian Text with Numbers

use Iamfarhad\Validation\Rules\PersianAlphaNum; use Iamfarhad\Validation\Rules\PersianAlphaEngNum; // Persian alphabet and Persian numbers Validator::make(['text' => 'فارسی۱۲۳'], [ 'text' => [new PersianAlphaNum()] ]); // Persian alphabet and English numbers Validator::make(['text' => 'فارسی123'], [ 'text' => [new PersianAlphaEngNum()] ]);

Iranian Company Validation

use Iamfarhad\Validation\Rules\CompanyId; // Iranian company identifier Validator::make(['company_id' => '14007650912'], [ 'company_id' => [new CompanyId()] ]);

URL and Domain Validation

use Iamfarhad\Validation\Rules\Url; use Iamfarhad\Validation\Rules\Domain; // URL validation Validator::make(['website' => 'https://example.com'], [ 'website' => [new Url()] ]); // Domain validation Validator::make(['domain' => 'example.com'], [ 'domain' => [new Domain()] ]);

Shamsi Date Validation

use Iamfarhad\Validation\Rules\ShamsiDate; use Iamfarhad\Validation\Rules\ShamsiDateBetween; // Basic Shamsi date Validator::make(['date' => '1400/01/01'], [ 'date' => [new ShamsiDate()] ]); // Shamsi date with custom separator Validator::make(['date' => '1400-01-01'], [ 'date' => [new ShamsiDate('-')] ]); // Shamsi date with Persian numbers Validator::make(['date' => '۱۴۰۰/۰۱/۰۱'], [ 'date' => [new ShamsiDate('/', true)] ]); // Shamsi date within year range Validator::make(['date' => '1400/01/01'], [ 'date' => [new ShamsiDateBetween(1380, 1420)] ]);

???? Company & Business Validation

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\{CompanyId, Url, Domain}; // Iranian company identifier Validator::make(['company_id' => '14007650912'], [ 'company_id' => [new CompanyId()] ]); // URL validation Validator::make(['website' => 'https://example.com'], [ 'website' => [new Url()] ]); // Domain validation Validator::make(['domain' => 'example.com'], [ 'domain' => [new Domain()] ]);

Using String Rules

// Company and web validation Validator::make($data, [ 'company_id' => ['ir_company_id'], 'website' => ['url_format'], 'domain' => ['domain'], ]);

???? Shamsi Date Validation (Advanced)

Using ValidationRule Objects

use Iamfarhad\Validation\Rules\{ShamsiDate, ShamsiDateBetween}; // Basic Shamsi date Validator::make(['date' => '1400/01/01'], [ 'date' => [new ShamsiDate()] ]); // Custom separator and Persian number support Validator::make(['date' => '۱۴۰۰-۰۱-۰۱'], [ 'date' => [new ShamsiDate('-', true)] // separator: -, convertPersianNumbers: true ]); // Date between years Validator::make(['event_date' => '1400/06/15'], [ 'event_date' => [new ShamsiDateBetween(1380, 1420)] ]);

Using String Rules

// Shamsi date validation Validator::make($data, [ 'birth_date' => ['shamsi_date'], // Default: separator='/', convertPersianNumbers=false 'start_date' => ['shamsi_date:-,true'], // Custom separator and Persian number conversion 'event_date' => ['shamsi_date_between:1380,1420,/,false'], // Between years 1380-1420 ]);

???? Mixed Usage Examples

Form Request with Both Approaches

use Iamfarhad\Validation\Rules\{Mobile, NationalCode, PersianAlpha, ShamsiDate}; public function rules(): array { return [ // Using ValidationRule objects 'first_name' => ['required', new PersianAlpha()], 'last_name' => ['required', new PersianAlpha()], 'national_code' => ['required', new NationalCode()], 'mobile' => ['required', new Mobile()], 'birth_date' => ['required', new ShamsiDate()], // Using string rules 'company_id' => ['nullable', 'ir_company_id'], 'website' => ['nullable', 'url_format'], 'username' => ['required', 'username_format'], 'bio' => ['nullable', 'persian_alpha_eng_num'], ]; }

???? Complete User Registration Example

use Iamfarhad\Validation\Rules\{Mobile, NationalCode, PersianAlpha, ShamsiDate, CompanyId}; $validator = Validator::make($request->all(), [ // Personal Information 'first_name' => ['required', new PersianAlpha()], 'last_name' => ['required', new PersianAlpha()], 'national_code' => ['required', new NationalCode()], 'mobile' => ['required', new Mobile()], 'birth_date' => ['required', new ShamsiDate()], // Business Information (String rules) 'company_id' => ['nullable', 'ir_company_id'], 'company_website' => ['nullable', 'url_format'], 'company_domain' => ['nullable', 'domain'], // Account Information 'username' => ['required', 'username_format'], 'bio' => ['nullable', 'persian_alpha_eng_num'], 'profile_image' => ['nullable', 'base64_format'], ]); if ($validator->fails()) { return response()->json([ 'success' => false, 'errors' => $validator->errors() ], 422); }

???? Translations

Publish the language files to customize error messages:

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

This will publish translation files to lang/vendor/validationRules/ directory where you can customize the error messages for each validation rule.

Available Languages

• English (en/messages.php)
• Persian/Farsi (fa/messages.php)

???? Testing

Run the test suite:

# Run all tests composer test # Run tests with coverage composer test-coverage # Run static analysis composer analyse # Run code formatting composer format # Run all checks (format, analyse, test) composer ci

⚡ Performance

This package is optimized for performance:

• Zero Dependencies: No external dependencies beyond Laravel core
• Efficient Algorithms: Optimized validation logic for Iranian data formats
• Memory Efficient: Minimal memory footprint
• Fast Execution: Benchmarked against other Persian validation packages

Benchmark Results

???? Package Statistics

• ✅ 100% Test Coverage
• ✅ PHPStan Level 8 (Maximum static analysis)
• ✅ Laravel Pint code formatting
• ✅ Automated CI/CD with GitHub Actions
• ✅ Semantic Versioning for reliable updates

????️ Development

Requirements for Development

• PHP 8.1+
• Composer
• Laravel 10+

Setup

git clone https://github.com/iamfarhad/validation.git cd validation composer install composer test

Code Quality

This package follows strict code quality standards:

• PHPStan Level 8 static analysis
• Laravel Pint code formatting (Laravel preset)
• PHPUnit 10+ for testing
• GitHub Actions for CI/CD

???? Contributing

We welcome contributions from the Laravel and Persian developer community!

How to Contribute

1. ???? Fork the repository
2. ???? Create a feature branch (git checkout -b feature/amazing-feature)
3. ✍️ Write tests for your changes
4. ✅ Ensure all tests pass (composer ci)
5. ???? Commit your changes (git commit -m 'Add amazing feature')
6. ???? Push to the branch (git push origin feature/amazing-feature)
7. ???? Open a Pull Request

What We're Looking For

• ???? Bug Reports: Found an issue? Report it!
• ???? New Features: Have an idea for a new validation rule?
• ???? Documentation: Help improve our docs
• ???? Tests: More test coverage is always welcome
• ???? Translations: Help translate error messages

Development Setup

# Clone your fork git clone https://github.com/your-username/validation.git cd validation # Install dependencies composer install # Run tests composer test # Run all quality checks composer ci

Code Standards

• ✅ PSR-12 coding standard (enforced by Laravel Pint)
• ✅ PHPStan Level 8 for static analysis
• ✅ 100% test coverage for new features
• ✅ Conventional commits for clear history

Community Guidelines

• ???? Be respectful and welcoming to all contributors
• ???? Provide constructive feedback on issues and PRs
• ???? Follow our code of conduct
• ???? Help others learn and grow

???? License

This package is open-sourced software licensed under the MIT license.

????‍???? Author

Farhad Zand

• ???? GitHub: @iamfarhad
• ???? Email: farhad.pd@gmail.com
• ???? Twitter: @iamfarhad_dev
• ???? LinkedIn: Farhad Zand

???? Show Your Support

If this package helps you build better Laravel applications, please consider:

• ⭐ Star this repository on GitHub
• ???? Report bugs and suggest improvements
• ???? Request features that would help your projects
• ???? Contribute code, tests, or documentation
• ???? Share with other Persian developers
• ☕ Sponsor the project to support continued development

???? GitHub Stats

???? Connect & Follow

Stay updated with the latest features and announcements:

• ???? Follow on GitHub
• ???? Follow on Twitter
• ???? Connect on LinkedIn
• ???? Check out my other packages

???? Related Projects

Check out other useful Laravel packages:

• ???? Laravel Persian Validation - This package
• ???? More coming soon... - Stay tuned!

Made with ❤️ for the Laravel and Persian developer community

If this package saved you time, please consider ⭐ starring the repository!

⭐ Star on GitHub • ???? View on Packagist • ???? Report Issues