[edit] Last updated: Mon, 01 Nov 2010

XLI. Fonctions Filter

Introduction

Cette extension permet de valider et de filtrer les données venant habituellement de sources non sécurisées comme les entrées utilisateurs.

Avertissement

Ce module est EXPERIMENTAL. Cela signifie que le comportement de ces fonctions, leurs noms et concrètement, TOUT ce qui est documenté ici peut changer dans un futur proche, SANS PREAVIS! Soyez-en conscient, et utilisez ce module à vos risques et périls.

Les filtres suivants existent actuellement, mais vous devriez lire la section sur les constantes de filtres pour plus d'informations sur le comportement de chaque constante :

Tableau 1. Filtres existants

ID	Nom	Options	Flags	Description
`FILTER_VALIDATE_INT`	"int"	`min_range`, `max_range`	`FILTER_FLAG_ALLOW_OCTAL`, `FILTER_FLAG_ALLOW_HEX`	Valide une valeur en tant qu'entier, optionnellement avec un intervalle spécifique.
`FILTER_VALIDATE_BOOLEAN`	"boolean"			Retourne `TRUE` pour "1", "true", "on" et "yes", `FALSE` pour "0", "false", "off", "no", et "", `NULL` sinon.
`FILTER_VALIDATE_FLOAT`	"float"			Valide une valeur en tant que nombre flottant.
`FILTER_VALIDATE_REGEXP`	"validate_regexp"	`regexp`		Valide une valeur en tant qu'une `regexp`, une expression régulière compatible PERL.
`FILTER_VALIDATE_URL`	"validate_url"		`FILTER_FLAG_SCHEME_REQUIRED`, `FILTER_FLAG_HOST_REQUIRED`, `FILTER_FLAG_PATH_REQUIRED`, `FILTER_FLAG_QUERY_REQUIRED`	Valide une valeur en tant qu'URL, optionnellement avec un composant requis.
`FILTER_VALIDATE_EMAIL`	"validate_email"			Valide une valeur en tant qu'e-mail.
`FILTER_VALIDATE_IP`	"validate_ip"		`FILTER_FLAG_IPV4`, `FILTER_FLAG_IPV6`, `FILTER_FLAG_NO_PRIV_RANGE`, `FILTER_FLAG_NO_RES_RANGE`	Valide une valeur en tant qu'une adresse IP, optionnellement, uniquement IPv4 ou IPv6 ou pas, depuis un intervalle privé ou réservé.
`FILTER_SANITIZE_STRING`	"string"		`FILTER_FLAG_NO_ENCODE_QUOTES`, `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP`	Efface les balises, optionnellement, efface ou encode les caractères spéciaux.
`FILTER_SANITIZE_STRIPPED`	"stripped"			Alias du filtre "string".
`FILTER_SANITIZE_ENCODED`	"encoded"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`	Chaîne encodée pour les URL, optionnellement, efface ou encode les caractères spéciaux.
`FILTER_SANITIZE_SPECIAL_CHARS`	"special_chars"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_HIGH`	Échappement HTML des caractères `'"<>&` et des caractères dont la valeur ASCII est inférieure à 32, optionnellement, efface ou encode les autres caractères spéciaux.
`FILTER_UNSAFE_RAW`	"unsafe_raw"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP`	Ne fait rien, optionnellement, efface ou encode les caractères spéciaux.
`FILTER_SANITIZE_EMAIL`	"email"			Efface tous les caractères exceptés les lettres, les nombres ainsi que !#$%&'*+-/=?^_`{\|}~@.[].
`FILTER_SANITIZE_URL`	"url"			Efface tous les caractères exceptés les lettres, les nombres ainsi que $-_.+!*'(),{}\|\\^~[]`<>#%";/?:@&=.
`FILTER_SANITIZE_NUMBER_INT`	"number_int"			Efface tous les caractères exceptés les nombres ainsi que `+-`.
`FILTER_SANITIZE_NUMBER_FLOAT`	"number_float"		`FILTER_FLAG_ALLOW_FRACTION`, `FILTER_FLAG_ALLOW_THOUSAND`, `FILTER_FLAG_ALLOW_SCIENTIFIC`	Efface tous les caractères exceptés les nombres, `+-` et, optionnellement, `.,eE`.
`FILTER_SANITIZE_MAGIC_QUOTES`	"magic_quotes"			Applique la fonction addslashes().
`FILTER_CALLBACK`	"callback"		callback function or method	Appel une fonction utilisateur pour filtrer les données.

Pré-requis

Ces fonctions sont disponibles dans le module PHP standard, qui est toujours accessible.

Installation

Une note d'installation courte : Exécutez juste la commande suivant :

$ pear install filter

dans votre console.

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Tableau 2. Options de cnfiguration pour Filter

Nom	Défaut	Modifiable	Changelog
filter.default	unsafe_raw	PHP_INI_PERDIR
filter.default_flags		PHP_INI_PERDIR

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à Annexe G.

Voici un éclaircissement sur l'utilisation des directives de configuration.

filter.default string: Filtre toutes les données transmises via $_GET, $_POST, $_COOKIE and $_REQUEST avec ce filtre. Les données originales peut être accédées via la fonction input_get().
filter.default_flags integer: Drapeau par défaut pour la fonction filter_data().

Types de ressources

Cette extension ne définit aucune ressource.

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

INPUT_POST (entier): variables POST.
INPUT_GET (entier): variables GET.
INPUT_COOKIE (entier): variables COOKIE.
INPUT_ENV (entier): variables ENV.
INPUT_SERVER (entier): variables SERVER.
INPUT_SESSION (entier): variables SESSION.
INPUT_DATA (entier): Variables définies par l'utilisateur.
FILTER_FLAG_NONE (entier): Aucun drappeau.
FILTER_VALIDATE_INT (entier): ID du filtre "int".
FILTER_VALIDATE_BOOLEAN (entier): ID du filtre "boolean".
FILTER_VALIDATE_FLOAT (entier): ID du filtre "float".
FILTER_VALIDATE_REGEXP (entier): ID du filtre "validate_regexp".
FILTER_VALIDATE_URL (entier): ID du filtre "validate_url".
FILTER_VALIDATE_EMAIL (entier): ID du filtre "validate_email".
FILTER_VALIDATE_IP (entier): ID du filtre "validate_ip".
FILTER_DEFAULT (entier): ID du filtre par défaut ("string").
FILTER_UNSAFE_RAW (entier): ID du filtre "unsafe_raw".
FILTER_SANITIZE_STRING (entier): ID du filtre "string".
FILTER_SANITIZE_STRIPPED (entier): ID du filtre "stripped".
FILTER_SANITIZE_ENCODED (entier): ID du filtre "encoded".
FILTER_SANITIZE_SPECIAL_CHARS (entier): ID du filtre "special_chars".
FILTER_SANITIZE_EMAIL (entier): ID du filtre "email".
FILTER_SANITIZE_URL (entier): ID du filtre "url".
FILTER_SANITIZE_NUMBER_INT (entier): ID du filtre "number_int".
FILTER_SANITIZE_NUMBER_FLOAT (entier): ID du filtre "number_float".
FILTER_SANITIZE_MAGIC_QUOTES (entier): ID du filtre "magic_quotes".
FILTER_CALLBACK (entier): ID du filtre "callback".
FILTER_FLAG_SCALAR (entier): Autorise des types scalaires (pas tableau) seulement dans le filtre. Utilisé présentement par input_get_args().
FILTER_FLAG_ARRAY (entier): Autorise seulement les types tableaux dans le filtre. Utilisé présentement par input_get_args().
FILTER_FLAG_ALLOW_OCTAL (entier): Alloue une notation octale (0[0-7]+) dans le filtre "int".
FILTER_FLAG_ALLOW_HEX (entier): Aloue une notation hexadécimale (0x[0-9a-fA-F]+) dans le filtre "int".
FILTER_FLAG_STRIP_LOW (entier): Supprime les caractères dont les valeurs ASCII sont inférieures à 32.
FILTER_FLAG_STRIP_HIGH (entier): Supprime les caractères dont les valeurs ASCII sont supérieures à 127.
FILTER_FLAG_ENCODE_LOW (entier): Encode les caractères dont les valeurs ASCII sont inférieures à 32.
FILTER_FLAG_ENCODE_HIGH (entier): Encode les caractères dont les valeurs ASCII sont supérieures à 127.
FILTER_FLAG_ENCODE_AMP (entier): Encode &.
FILTER_FLAG_NO_ENCODE_QUOTES (entier): N'encode pas ', ni ".
FILTER_FLAG_EMPTY_STRING_NULL (entier): (Non utilisé actuellement.)
FILTER_FLAG_ALLOW_FRACTION (entier): Alloue une partie fractionnelle dans le filtre "number_float".
FILTER_FLAG_ALLOW_THOUSAND (entier): Alloue le séparateur des milliers (,) dans le filtre "number_float".
FILTER_FLAG_ALLOW_SCIENTIFIC (entier): Alloue une notation scientifique (e, E) dans le filtre "number_float".
FILTER_FLAG_SCHEME_REQUIRED (entier): Schéma requis dans le filtre "validate_url".
FILTER_FLAG_HOST_REQUIRED (entier): Hôte requis dans le filtre "validate_url".
FILTER_FLAG_PATH_REQUIRED (entier): Chemin requis dans le filtre "validate_url".
FILTER_FLAG_QUERY_REQUIRED (entier): Requête requise dans le filtre "validate_url".
FILTER_FLAG_IPV4 (entier): N'autorise que les adresses IPv4 dans le filtre "validate_ip".
FILTER_FLAG_IPV6 (entier): N'autorise que les adresses IPv6 dans le filtre "validate_ip".
FILTER_FLAG_NO_RES_RANGE (entier): N'autorise pas les adresses réservées dans le filtre "validate_ip".
FILTER_FLAG_NO_PRIV_RANGE (entier): N'autorise pas les adresses privées dans le filtre "validate_ip".

Table des matières
filter_data -- Filtre les données avec un filtre spécifique
input_filters_list -- Retourne une liste de tous les filtres supportés
input_get_args -- Récupère plusieurs variables depuis l'extérieur de PHP et, optionnellement, les filtres
input_get -- Récupère une variable d'en dehors de PHP et optionnellement, la filtre
input_has_variable -- Vérifie si une variable d'un type spécifique existe
input_name_to_filter -- Retourne l'identifiant du filtre par rapport à son nom

filter_data

unlink

[edit] Last updated: Mon, 01 Nov 2010

add a note User Contributed Notes Fonctions Filter

Anonymous 24-Dec-2008 09:08


--quoted from filter.txt in the source code



* As the input filter acts on input data before the magic quotes function

  mangles data, all access through the filter() function will not have any

  quotes or slashes added - it will be the pure data as send by the browser.

Jovan Suervo 26-Nov-2007 01:35


It seems that all FILTER_VALIDATE_URL is doing is calling parse_url(), which makes it effectively useless since parse_url() only fails on really malformed urls.



<?php

$url = 'http://...';



var_dump(filter_var($url, FILTER_VALIDATE_URL));

?>



Will display: string(10) "http://..."



None of the flags help either, so you're better off with regular expressions to validate a url.

fumble1 at web dot de 12-Aug-2007 10:54


I recommend you to use the FILTER_REQUIRE_SCALAR (or FILTER_REQUIRE_ARRAY) flags, since you can use array-brackets both to access string offsets and array-element -- however, not only this can lead to unexpected behaviour. Look at this example:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_FLAG_STRIP_LOW));

// further checks

?>



/script.php?src[0]=foobar will cause a warning. :-(

Hence my recommendation:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_REQUIRE_SCALAR | FILTER_FLAG_STRIP_LOW));

// further checks

?>

Richard Davey rich at corephp dot co dot uk 13-Jun-2007 11:15


There is an undocumented filter flag for FILTER_VALIDATE_BOOLEAN. The documentation implies that it will return NULL if the value doesn't match the allowed true/false values. However this doesn't happen unless you give it the FILTER_NULL_ON_FAILURE flag like this:



<?php

$value = 'car';

$result = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);

?>



In the above $result will equal NULL. Without the extra flag it would equal FALSE, which isn't usually a desired result for this specific filter.

ckroll at rightmedia dot com 08-May-2007 08:02


Beware, the FILTER_SANITIZE_STRING flag functions much like strip_tags, so < will get filtered from input regardless of it's actually part of a tag.  We were getting unexepected results with a graphic library we wrote when trying to print < on a dynamic button.  The url came in something like ?string=%3C (<) but after filter ran it was empty.  To get around this, you could use FILTER_UNSAFE_RAW on that one param.

user 02-Feb-2007 12:15


Below is some code using filter API to restrict access to LAN by IPv4 private address range.



These notes may save someone else a little time:



filter_input_array() is useless for running multiple filters on the same key.

No way to chain or negate filters.



<?php



/* Merciful comment! */

function FILTER_NEGATE_HACK($_){ return (bool)!$_; }



function client_is_private_ipv4(){

  return (filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) && 

            FILTER_NEGATE_HACK(filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE));

}



if (! client_is_private_ipv4()) 

  exit('This application is restricted to local network users');



?>

vojtech at x dot cz 21-Dec-2006 06:38


Also notice that filter functions are using only the original variable values passed to the script even if you change the value in super global variable ($_GET, $_POST, ...) later in the script.



<?php

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'something'

$_GET['var'] = 'changed';

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'changed'

?>



In fact, external data are duplicated in SAPI before the script is processed and filter functions don't use super globals anymore (as explained in Filter tutorial bellow, section 'How does it work?').

vojtech at x dot cz 21-Dec-2006 05:13


Just to note that "server and env support may not work in all sapi, for filter 0.11.0 or php 5.2.0" as mentioned in Filter tutorial bellow.



The workaround is obvious:

Instead of 

<?php

$var = filter_input(INPUT_SERVER, 'SERVER_NAME', FILTER_DEFAULT);

?>

use

<?php

$var = filter_var(isset($_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : NULL, FILTER_DEFAULT);

?>

add a note