filter_var() ב-PHP: אימות אימייל, int, URL ועוד

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.

בוליאנים, floats, כתובות URL וכתובות 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'.

URL תקין אינו קישור בטוח

FILTER_VALIDATE_URL בודק שהמחרוזת בנויה כמו 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() לפני שאתם מדפיסים 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 עושה את אותו escape). 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 כי הוא לא נשלח. בשרת web, filter_input_array(INPUT_POST, $rules) עושה את אותו הדבר וקוראת ישירות מהבקשה.