filter_var() في PHP: التحقق من البريد والأعداد والروابط

تعيد filter_var($value, FILTER_VALIDATE_EMAIL) القيمة حين تكون عنوان بريد إلكتروني صالحًا وfalse حين لا تكون. بدّل المرشح لفحص صيغ أخرى: FILTER_VALIDATE_INT وFILTER_VALIDATE_FLOAT وFILTER_VALIDATE_URL وFILTER_VALIDATE_BOOL وFILTER_VALIDATE_IP. وقارن النتيجة دائمًا بـ === false.

<?php
$emails = ['ada@example.com', 'ada.lovelace+news@example.co.uk', 'ada@', 'ada@example', 'ada..x@example.com', ' ada@example.com'];

foreach ($emails as $email) {
    $ok = filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
    printf("%-34s %s\n", "'$email'", $ok ? 'valid' : 'invalid');
}

نتيجتان تفاجئان الناس. يُرفض ada@example لأن النطاق ليس فيه نقطة، ويُرفض ' ada@example.com' بسبب المسافة البادئة، لذا طبّق trim() على المُدخلات قبل التحقق منها.

التحقق من بريد إلكتروني قادم من نموذج

الفحص نفسه خلف نموذج. شغّله، واكتب عنوانًا واضغط Check؛ تعمل الكتلة مرة أخرى مع مُدخلك في $_POST.

<?php
$email = trim((string) ($_POST['email'] ?? ''));
$result = '';

if ($email !== '') {
    $result = filter_var($email, FILTER_VALIDATE_EMAIL) !== false
        ? '<b style="color:#2e7d32">valid</b>'
        : '<b style="color:#c62828">invalid</b>';
}
?>
<form method="post">
  <input name="email" size="30" value="<?= htmlspecialchars($email) ?>" placeholder="you@example.com">
  <button>Check</button>
</form>
<?php if ($result): ?><p><?= htmlspecialchars($email) ?> is <?= $result ?></p><?php endif; ?>

لا يفحص FILTER_VALIDATE_EMAIL إلا الشكل. يمر nobody@example.com، وكذلك سيمر عنوان فيه خطأ إملائي في النطاق. وتُرفض المحارف غير ASCII: لا يمر adä@example.com إلا مع FILTER_FLAG_EMAIL_UNICODE، الذي يسمح بها قبل @، ويفشل نطاق مثل exämple.com حتى مع العلم ما لم تحوّله إلى صيغة xn-- أولًا. والطريقة الوحيدة لمعرفة أن العنوان يعمل هي إرسال رابط تأكيد إليه.

التحقق من عدد صحيح، مع min_range وmax_range

يحوّل FILTER_VALIDATE_INT النص الصالح إلى int ويرفض كل ما عداه. وتضيف مصفوفة الخيارات نطاقًا وقيمة افتراضية:

<?php
$inputs = ['42', '-7', ' 42 ', '+42', '4.2', '042', '42abc', '', '0'];

foreach ($inputs as $in) {
    echo str_pad("'$in'", 8), ' => ';
    var_dump(filter_var($in, FILTER_VALIDATE_INT));
}

$age = filter_var('150', FILTER_VALIDATE_INT, [
    'options' => ['min_range' => 0, 'max_range' => 120],
]);
var_dump($age);

$page = filter_var('abc', FILTER_VALIDATE_INT, ['options' => ['default' => 1]]);
var_dump($page);

تُقبل المسافات المحيطة وعلامة + البادئة، ولا يُقبل الصفر البادئ ('042')، والنتيجة لـ '42' هي العدد الصحيح 42 لا النص. والقيمة خارج النطاق تعطي false؛ ومع الخيار default تحصل على القيمة الافتراضية بدل false، وهذا مفيد لأشياء مثل ?page= (راجع $_GET و$_POST). أضف FILTER_FLAG_ALLOW_HEX أو FILTER_FLAG_ALLOW_OCTAL لقبول 0x1A أو 0755.

فخ 0 وfalse

تعيد '0' الصالحة العدد الصحيح 0، و0 خاطئ منطقيًا. وتعامله if البسيطة على أنه فشل:

<?php
$quantity = '0';

if (filter_var($quantity, FILTER_VALIDATE_INT)) {
    echo "if (...): valid\n";
} else {
    echo "if (...): rejected, wrongly\n";
}

if (filter_var($quantity, FILTER_VALIDATE_INT) !== false) {
    echo "!== false: valid\n";
}

// Or get null instead of false on failure, and check for null
$n = filter_var('abc', FILTER_VALIDATE_INT, FILTER_NULL_ON_FAILURE);
var_dump($n);

وينطبق الأمر نفسه على FILTER_VALIDATE_FLOAT ('0.0') وFILTER_VALIDATE_BOOL، حيث تكون false إجابة صحيحة. ولهذا وُجد FILTER_NULL_ON_FAILURE.

القيم المنطقية والأعداد العشرية والروابط وعناوين IP

<?php
// Booleans: "1", "true", "on", "yes" are true; "0", "false", "off", "no", "" are false
foreach (['yes', 'off', 'TRUE', 'maybe'] as $v) {
    echo str_pad($v, 6), ' => ', var_export(filter_var($v, FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE), true), "\n";
}

// Floats: the decimal separator is "." unless you say otherwise
var_dump(filter_var('3.14', FILTER_VALIDATE_FLOAT));
var_dump(filter_var('3,14', FILTER_VALIDATE_FLOAT));
var_dump(filter_var('3,14', FILTER_VALIDATE_FLOAT, ['options' => ['decimal' => ',']]));
var_dump(filter_var('1,000.5', FILTER_VALIDATE_FLOAT, FILTER_FLAG_ALLOW_THOUSAND));

// URLs need a scheme
var_dump(filter_var('https://coddy.tech/docs?x=1', FILTER_VALIDATE_URL));
var_dump(filter_var('coddy.tech', FILTER_VALIDATE_URL));

// IP addresses, optionally excluding private ranges
var_dump(filter_var('192.168.1.10', FILTER_VALIDATE_IP));
var_dump(filter_var('192.168.1.10', FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE));

FILTER_VALIDATE_BOOL هو اسم PHP 8؛ وFILTER_VALIDATE_BOOLEAN هو المرشح نفسه. ودون FILTER_NULL_ON_FAILURE، ستعيد 'maybe' القيمة false، فلا يمكن تمييزها عن 'off'.

الرابط الصالح ليس رابطًا آمنًا

يفحص FILTER_VALIDATE_URL أن النص بشكل رابط، بأي بروتوكول. ويشمل ذلك بروتوكولات لا تريدها أبدًا في href:

<?php
function isSafeLink(string $url): bool
{
    if (filter_var($url, FILTER_VALIDATE_URL) === false) {
        return false;
    }
    $scheme = strtolower((string) parse_url($url, PHP_URL_SCHEME));
    return in_array($scheme, ['http', 'https'], true);
}

foreach (['https://example.com', 'javascript://comment%0Aalert(1)', 'ftp://files.example.com', 'example.com'] as $url) {
    printf("%-36s filter_var: %-5s  safe link: %s\n",
        $url,
        filter_var($url, FILTER_VALIDATE_URL) !== false ? 'yes' : 'no',
        isSafeLink($url) ? 'yes' : 'no');
}

يجتاز javascript://comment%0Aalert(1) المرشح FILTER_VALIDATE_URL، ويشغّله المتصفح JavaScript عند النقر على الرابط، لأن %0A ينهي //comment. افحص البروتوكول بـ parse_url() قبل أن تطبع رابط مستخدم في صفحة. ويمكنك أيضًا اشتراط أجزاء بـ FILTER_FLAG_PATH_REQUIRED وFILTER_FLAG_QUERY_REQUIRED.

مرشحات التنقية

تحذف مرشحات التنقية المحارف بدل أن تقول نعم أو لا. وهي مفيدة لتوحيد شكل المُدخلات، لا لجعلها آمنة للطباعة:

<?php
var_dump(filter_var('Order #12-345 (x2)', FILTER_SANITIZE_NUMBER_INT));
var_dump(filter_var('$1,299.99', FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION));
var_dump(filter_var('ada (at) example.com', FILTER_SANITIZE_EMAIL));
var_dump(filter_var('<b>Tom</b> & "Jerry"', FILTER_SANITIZE_FULL_SPECIAL_CHARS));

انظر إلى السطر الأول: يصبح Order #12-345 (x2) العدد 12-3452، عددًا لم يكن في المُدخل قط، والسطر الثالث عنوان لم يكتبه أحد. إذا نقّيت، فتحقق من النتيجة بعد ذلك. ولكل ما تطبعه في HTML، تكون htmlspecialchars() وقت الإخراج الأداة الصحيحة (ويقوم FILTER_SANITIZE_FULL_SPECIAL_CHARS بالتهريب نفسه). وFILTER_SANITIZE_STRING مهمل منذ PHP 8.1؛ راجع htmlspecialchars لما تستخدمه بدلًا منه.

التحقق من نموذج كامل بـ filter_var_array

تطبّق filter_var_array() مرشحًا واحدًا لكل مفتاح وتعيد مصفوفة فيها كل مفتاح طلبته: القيمة المصفّاة، أو false حين يفشل التحقق، أو null حين يكون المفتاح مفقودًا.

<?php
$input = ['age' => '31', 'email' => 'not-an-email', 'newsletter' => 'on', 'role' => 'admin'];

$clean = filter_var_array($input, [
    'age'        => ['filter' => FILTER_VALIDATE_INT, 'options' => ['min_range' => 13]],
    'email'      => FILTER_VALIDATE_EMAIL,
    'newsletter' => ['filter' => FILTER_VALIDATE_BOOL, 'flags' => FILTER_NULL_ON_FAILURE],
    'country'    => FILTER_DEFAULT,
]);

var_dump($clean);

اختفى role: تُسقط المفاتيح التي لم تذكرها، وهذا يمنع الزائر من إضافة role=admin إلى نموذج وحفظها. وcountry قيمتها null لأنها لم تُرسل. وعلى خادم ويب، تفعل filter_input_array(INPUT_POST, $rules) الشيء نفسه بالقراءة مباشرة من الطلب.