مكتبة Symfony/Validator في PHP: دليل شامل مع أمثلة تطبيقية

1. ما هي هذه المكتبة ولماذا تحتاجها؟

مكتبة Symfony/Validator هي مكون قوي ومرن من نظام Symfony البيئي، مصممة للتحقق من صحة البيانات (Validation). على عكس الفحوصات البسيطة "أثناء التنفيذ"، تقدم هذه المكتبة نهجًا تصريحيًا: تصف قواعد التحقق (القيود) باستخدام التعليقات التوضيحية (Annotations)، أو خصائص PHP 8+ (Attributes)، أو YAML، أو XML، أو مصفوفات PHP، ثم تمرر البيانات إلى خدمة خاصة تسمى ValidatorInterface. هذا يفصل منطق التحقق عن منطق الأعمال في التطبيق، مما يجعل الكود أكثر نظافة وقابلية للاختبار وإعادة الاستخدام.

لماذا تحتاجها؟ في أي تطبيق ويب (وغيره)، تأتي البيانات من مصادر غير موثوقة: نماذج على الموقع، طلبات API، استيراد من ملفات CSV. بدون التحقق من الصحة، تخاطر بالتعرض لهجمات SQL Injection، XSS، حسابات غير صحيحة، أو ببساطة "بيانات غير مرغوب فيها" في قاعدة البيانات. تعالج Symfony/Validator هذه المشاكل بشكل شامل: فهي تتحقق من أنواع البيانات، أطوال النصوص، نطاقات الأرقام، تفرد البريد الإلكتروني، مطابقة التعبيرات المنتظمة، وأكثر من ذلك بكثير. علاوة على ذلك، فهي تجمع كل الأخطاء في كائن واحد ConstraintViolationList، يمكن تحويله بسهولة إلى استجابة JSON لواجهة API أو عرضه كقائمة أخطاء في النموذج.

المكون مستقل تمامًا عن إطار العمل Symfony. يمكنك استخدامه في أي مشروع PHP (Laravel، Yii، إطار عمل خاص، أو حتى PHP "خالص"). يتمتع بدعم نشط، ووثائق ممتازة، ومجتمع ضخم. إنه "المعيار الذهبي" للتحقق من صحة البيانات في عالم PHP.

2. التثبيت

يتم التثبيت عبر Composer. نفّذ الأمر التالي في الطرفية (Terminal) في جذر مشروعك:

composer require symfony/validator

يوصى أيضًا بتثبيت المكون symfony/property-access للعمل بشكل صحيح مع الكائنات والمصفوفات المتداخلة:

composer require symfony/property-access

إذا كنت تخطط لاستخدام التعليقات التوضيحية/الخصائص (Annotations/Attributes)، تأكد من تثبيت doctrine/annotations (لـ PHP 7.x) أو استخدام PHP 8+ مع الخصائص الأصلية (Native Attributes).

3. بداية سريعة — مثال عملي بسيط

لننشئ كلاسًا بسيطًا User مع خصائص التحقق (Validation Attributes) ونتحقق منه.

<?php
// 1. نقوم بتضمين أداة التحميل التلقائي لـ Composer
require_once 'vendor/autoload.php';

// 2. نستورد الكلاسات المطلوبة
use Symfony\Component\Validator\Validation;
use Symfony\Component\Validator\Constraints as Assert;

// 3. ننشئ كلاسًا مع خصائص التحقق (PHP 8+)
class User {
    #[Assert\NotBlank(message: "الاسم لا يمكن أن يكون فارغًا")]
    #[Assert\Length(min: 2, max: 50, minMessage: "يجب أن يحتوي الاسم على {{ limit }} أحرف على الأقل")]
    public string $name;

    #[Assert\NotBlank]
    #[Assert\Email(message: "البريد الإلكتروني '{{ value }}' غير صالح.")]
    public string $email;

    #[Assert\PositiveOrZero]
    public int $age;
}

// 4. ننشئ المدقق (Validator)
$validator = Validation::createValidatorBuilder()
    ->enableAttributeMapping() // تفعيل دعم الخصائص (Attributes)
    ->getValidator();

// 5. ننشئ كائنًا ببيانات غير صحيحة
$user = new User();
$user->name = 'أ'; // اسم قصير جدًا
$user->email = 'not-an-email';
$user->age = -5;

// 6. نقوم بالتحقق
$violations = $validator->validate($user);

// 7. نتعامل مع الأخطاء
if (count($violations) > 0) {
    foreach ($violations as $violation) {
        echo $violation->getPropertyPath() . ': ' . $violation->getMessage() . "\n";
    }
} else {
    echo "البيانات صالحة!";
}

هذا المثال سيطبع:

name: يجب أن يحتوي الاسم على 2 أحرف على الأقل
email: البريد الإلكتروني 'not-an-email' غير صالح.
age: يجب أن تكون هذه القيمة موجبة أو تساوي صفرًا.

4. أهم الدوال/الكلاسات

4.1. Validation::createValidatorBuilder()

التوقيع: