نظرة عامة على أدوات التحقق

أدوات التحقق الست#

تضم RTLY-Kit ست أدوات تحقق للبيانات التي تتعامل معها التطبيقات الإيرانية كل يوم. وكلها تتبع شكلًا واحداً، فإذا عرفت واحدة منها عرفت الباقي.

تقع جميعها في فضاء الأسماء RtlyKit\Validation، وتقبل الأرقام الفارسية والعربية كما يكتبها المستخدمون، فيمكنك تمرير مدخلات النماذج إليها مباشرة دون تنظيفها أولًا.

طريقتان للاستدعاء#

تقدّم كل أداة تحقق قيمة منطقية بسيطة ونتيجة منظّمة. استخدم isValid() حين تحتاج إلى «نعم» أو «لا» فقط، واستخدم validate() حين تريد إخبار المستخدم بسبب رفض القيمة.

<?php
require 'vendor/autoload.php';

use RtlyKit\Validation\NationalCode;
use function RtlyKit\is_national_code;

var_dump(NationalCode::isValid('۰۴۹۹۳۷۰۸۹۹'));   // bool(true)
var_dump(is_national_code('0499370899'));        // bool(true)

$result = NationalCode::validate('0499370898');
var_dump($result->isValid());                    // bool(false)
print_r($result->errors());                      // Array ( [0] => invalid_checksum )

الدوال المساعدة (is_national_code() وvalidate_sheba() وغيرها) تقع ضمن فضاء أسماء؛ استورِدها بـ use function RtlyKit\is_national_code;. أما الأسماء العامة القصيرة فهي اختيارية؛ راجع الدوال المساعدة والأسماء العامة.

عقد Validator#

تنفّذ كل أداة تحقق الواجهة RtlyKit\Contracts\Validator، وفيها دالتان ساكنتان (static) فقط:

• validate(mixed $value): Result
• isValid(mixed $value): bool، وهي اختصار لـ validate($value)->isValid()

أدوات التحقق عديمة الحالة، ولذلك كانت الدوال ساكنة. وهذا يسهّل اختيار أداة التحقق وقت التشغيل عبر اسم الصنف كسلسلة نصية (class-string)، مثلًا من مصفوفة إعدادات:

use RtlyKit\Contracts\Validator;
use RtlyKit\Validation\Mobile;
use RtlyKit\Validation\NationalCode;
use RtlyKit\Validation\PostalCode;

/** @var array<string, class-string<Validator>> $rules */
$rules = [
    'national_code' => NationalCode::class,
    'mobile'        => Mobile::class,
    'postal'        => PostalCode::class,
];
$input = ['national_code' => '0499370899', 'mobile' => '0912', 'postal' => '1234567890'];

foreach ($rules as $field => $class) {
    $result = $class::validate($input[$field]);
    echo $field, ': ', $result->isValid() ? 'ok' : implode(',', $result->errors()), "\n";
}
// national_code: ok
// mobile: invalid_format
// postal: ok

كائن Result#

الصنف RtlyKit\Validation\Result كائن قيمة غير قابل للتغيير، وله ثلاث دوال قراءة:

التفاصيل موجودة في النتائج الصالحة وغير الصالحة (بقدر ما وصلت إليه أداة التحقق قبل أن تتوقف)، فيمكنك عرض القيمة المطبَّعة أو اسم المصرف حتى بجوار خطأ:

use RtlyKit\Validation\BankCard;

$result = BankCard::validate('6037991234567890');
var_dump($result->isValid());   // bool(false)
print_r($result->errors());     // Array ( [0] => invalid_checksum )
echo json_encode($result->details(), JSON_UNESCAPED_UNICODE);
// {"normalized":"6037991234567890","bin":"603799","bank_name":"بانک ملی ایران"}

مفاتيح التفاصيل لكل أداة تحقق#

قيم البحث (location وbank_name وoperator) تكون null إذا لم يكن في الجدول مدخل مطابق. وغياب المدخل يعني «غير معروف» ولا يعني «غير صالح» أبدًا.

مفاتيح الأخطاء#

الأخطاء مفاتيح ثابتة مقروءة آليًا. لا تتغير بين الإصدارات، فيمكنك ربطها برسائلك أو ترجماتك الخاصة. وهذا ما يفعله تكامل Laravel بالضبط؛ راجع قواعد التحقق والتحويل في Laravel.

تحمل النتيجة اليوم خطأً واحدًا على الأكثر (أول فحص فشل)، لكن errors() تُرجع قائمة كي تتمكن فحوصات مستقبلية من الإبلاغ عن عدة أخطاء.

معالجة المدخلات#

قبل تشغيل أي قاعدة، تمرّ القيمة عبر بوابة مشتركة واحدة:

• السلاسل النصية حتى 4096 بايت تمرّ. يشغل الرقم الفارسي أو العربي بايتين، فالحد الأقصى نحو 2000 رقم من هذا النوع. والسلسلة الأطول تُنتج input_too_long.
• int يُحوَّل بـ (string).
• float يجب أن يكون منتهيًا وصحيحًا (بلا كسر) وقيمته المطلقة أقل من 10¹⁵؛ ويُحوَّل دون أُسّ. القيم NaN وINF و1.5 والأعداد العشرية الضخمة تُنتج invalid_type.
• كل ما عدا ذلك، أي null وbool والمصفوفات والكائنات، يُنتج invalid_type.

use RtlyKit\Validation\NationalCode;
use RtlyKit\Validation\PostalCode;

print_r(NationalCode::validate(null)->errors());                  // [invalid_type]
print_r(NationalCode::validate(1.5)->errors());                   // [invalid_type]
print_r(NationalCode::validate(str_repeat('1', 4097))->errors()); // [input_too_long]
print_r(NationalCode::validate("\xff\xfe")->errors());            // [invalid_format]
var_dump(PostalCode::validate(1234567890)->isValid());            // bool(true)

التطبيع#

بعد البوابة، تطبّع كل أداة تحقق السلسلة بدالتها العامة normalize(). وتشترك في هذه القواعد:

• الأرقام الفارسية (۰-۹) والعربية الهندية (٠-٩) تتحول إلى أرقام إنجليزية باستخدام Digits::toEnglish().
• تُحذف الفواصل التي يكتبها المستخدمون: المسافات والواصلات والنصف مسافة (ZWNJ). أما Mobile وBankCard وPostalCode فتذهب أبعد وتُبقي الأرقام فقط.
• تحوّل Sheba النص أيضًا إلى أحرف كبيرة وتضيف البادئة IR إلى سلسلة مجردة من 24 رقمًا.

تُرجَع القيمة المطبَّعة دائمًا في details()['normalized']. خزّنها هي لا المدخل الخام، كي لا يُحفظ الرقم نفسه بصيغتين.

جداول البحث ومصادرها#

تُرفق أربع أدوات تحقق معلومة بحث: المصرف من BIN البطاقة، والمصرف من رمز شبا، ومكان الإصدار من بادئة الرقم الوطني، والمشغّل من بادئة الجوال. هذه البيانات مجرد إضافة مريحة فوق التحقق؛ أما الصلاحية نفسها فلا تعتمد عليها أبدًا.

• BIN البطاقات المصرفية: 39 مدخلًا. رموز المصارف في شبا: 38 مدخلًا. بادئات الرقم الوطني: 547 مدخلًا.
• رموز المصارف الـ 19 الواردة في مواصفة IBAN المنشورة لدى البنك المركزي الإيراني تطابق جدول المكتبة. أما بقية الجداول فتتفق مع عدة صفحات عامة، لأن قائمة رسمية لم تتوفر.
• المدخل غير الموجود في الجدول يعني «غير معروف»، ولا يعني «غير صالح».

إلى أين تذهب بعد ذلك#

• الرقم الوطني: الخوارزمية والتطبيع وتلميح مكان الإصدار.
• شبا والبطاقة المصرفية: mod-97 وLuhn والبحث عن المصارف.
• الجوال والرمز البريدي ولوحة المركبة.
• الحدود: كل حدود الحجم في مكان واحد.