Le filtrage et l'échappement des données en PHP 5 : documentation de la technique du Poka-Yoké

Date de publication : 5 juin 2007

III. DVP_DataFilter

Toutes les valeurs par défaut sont définies dans les constantes de la classe DVP_DataFilter.

III-A. Implémentations

ArrayAccess

• offsetExists($field) : Vérifie si un champ existe dans l'objet ;
• offsetGet($field) : Lance une exception car nous voulons obliger le développeur à utiliser les méthodes "get..." ;
• offsetSet($field, $value) : Assigne une valeur à un champ de l'objet ;
• offsetUnset($field) : Supprime un champ de l'objet.

Countable

• count() : Retourne le nombre de champs qui ont été filtrés.

IteratorAggregate

• getIterator() : Retourne un objet DVP_Iterator.

III-B. Propriétés "protected"

• data : L'Array de données ;
• filteredData : Un Array indiquant les champs filtrés.

• allowedCharsets : Un Array des jeux de caractères autorisés ;
• allowedDBMS : Un Array des SGBD autorisés ;
• allowedPCREModes : Un Array des modes de filtrage PCRE.

• defaultCharset : Le jeu de caractères par défaut ;
• defaultDBMS : Le SGBD par défaut.

III-C. Constantes

• DEFAULT_ARRAY = array()
• DEFAULT_CHARSET = DVP_DataFilter::CHARSET_LATIN_1
• DEFAULT_DBMS = DVP_DataFilter::DBMS_MYSQL
• DEFAULT_HEX = 0x0
• DEFAULT_INT = 0
• DEFAULT_NUMERIC = 0
• DEFAULT_STRING = ''

• QUOTE_STYLE = ENT_QUOTES

• FILTERED_NO_CHANGE
• FILTERED_MODIFIED

• CHARSET_LATIN_1 = 'iso-8859-1'
• CHARSET_LATIN_9 = 'iso-8859-15'
• CHARSET_UTF_8 = 'utf-8'

• DBMS_MSSQL
• DBMS_MYSQL
• DBMS_OCI
• DBMS_ODBC
• DBMS_ORA
• DBMS_POSTGRESQL
• DBMS_PDO
• DBMS_SQLITE

• ARRAY_ARRAYS
• ARRAY_NUMERICS
• ARRAY_INTS
• ARRAY_STRINGS

• PCRE_MATCH
• PCRE_REPLACE

• REGEX_DELIMITER = '/'
• REGEX_EMAIL = '#^\w+(?:[-+.]\w+)*@\w+(?:[-.]\w+)*\.\w+$#'
• REGEX_NEWLINES = '/[\n\r]/'
• REGEX_URI = '`^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$`'
• REGEX_TEXT_ISO = '/[^a-z0-9 ?!:;.,-_()[]{}\/ ¡¢£¤¥¦§¨©ª«¬­®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ"\'<>&]/i'

Lorque je ne précise pas la valeur d'une constante, cela signifie qu'elle est totalement arbitraire et à usage uniquement interne.

III-D. Méthodes "protected"

checkField()

• field : Le champ à vérifier.

• DVP_AbsentOffsetException
• DVP_TypeException

clean()

• aucun

• aucune

III-E. Méthodes "public"

III-E-1. Les testeurs

isArray()

• field : Le champ à vérifier.

• aucune

if($_POST->isArray('checkboxes'))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

isEmpty()

• field : Le champ à vérifier.

• aucune

if($_POST->isEmpty('login'))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

isInt()

• field : Le champ à vérifier.

• aucune

if($_POST->isInt('id'))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

isNumeric()

• field : Le champ à vérifier.

• aucune

if($_POST->isNumeric('mark'))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

isString()

• field : Le champ à vérifier.

• aucune

if($_POST->isString('login'))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

III-E-2. Les filtres

Ces méthodes ne peuvent être utilisées que sur des champs qui ont été filtrés au préalable.

filterArray()

• field : De type String, c'est le nom du champ à filtrer ;
• type : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_ARRAY) : De type Array, c'est la valeur retournée si le champ n'est pas de type Array.

• DVP_AbsentOffsetException
• DVP_TypeException
• DVP_ValueException

$_POST->filterArray('checkboxes', DVP_DataFilter::ARRAY_INTS);

filterEmail()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_STRING) : De type String, c'est la valeur retournée si le champ n'est pas de type String ou ne correspond pas à un e-mail.

• DVP_AbsentOffsetException
• DVP_RegexException
• DVP_TypeException
• DVP_ValueException

$_POST->filterEmail('email');
$_POST->filterEmail('email', 'admin@site.com');

filterHex()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_HEX) : De type hexadécimal, c'est la valeur retournée si le champ n'est pas de type hexadécimal.

• DVP_AbsentOffsetException
• DVP_TypeException

$_POST->filterHex('ip_address');

filterInt()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_INT) : De type Integer, c'est la valeur retournée si le champ n'est pas de type Integer.

• DVP_AbsentOffsetException
• DVP_TypeException

$_POST->filterInt('id');
$_POST->filterInt('id', 1);

filterNumeric()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_NUMERIC) : De type numérique quelconque, c'est la valeur retournée si le champ n'est pas de type numérique quelconque.

• DVP_AbsentOffsetException
• DVP_TypeException

$_POST->filterNumeric('mark');
$_POST->filterNumeric('mark', 1);

filterSingleLine()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_STRING) : De type String, c'est la valeur retournée si le champ n'est pas de type String ou s'il contient plusieurs lignes.

• DVP_AbsentOffsetException
• DVP_TypeException

$_POST->filterSingleLine('login');
$_POST->filterSingleLine('login', 'guest');

filterURI()

• field : De type String, c'est le nom du champ à filtrer ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_STRING) : De type String, c'est la valeur retournée si le champ n'est pas de type String ou s'il contient plusieurs lignes.

• DVP_AbsentOffsetException
• DVP_RegexException
• DVP_TypeException
• DVP_ValueException

$_POST->filterURI('website');
$_POST->filterURI('website', 'http://g-rossolini.developpez.com/');

filterUsingArray()

• field : De type String, c'est le nom du champ à filtrer ;
• whiteValues : De type Array, il contient les seules valeurs que le champ sera autorisé à prendre ;
• type : C'est l'une des constantes DVP_DataFilter::ARRAY_*, ce paramètre contraint le champ à un type défini.

• DVP_AbsentOffsetException
• DVP_ArrayTypeException
• DVP_TypeException
• DVP_ValueException

$_POST->filterUsingArray('id', array(1, 3, 7), DVP_DataFilter::ARRAY_INTS); // L'ID est soit 1, soit 3, soit 7
$_POST->filterUsingArray('login', array('Yogui', 'BrYs'), DVP_DataFilter::ARRAY_STRINGS); // Le login est soit "Yogui", soit "BrYs"

Vous ne devez pas fournir de tableau de valeurs blanches contenant plusieurs types. Un champ spécifique doit être d'un type bien défini. Il ne peut pas être "d'un type ou d'un autre" car cela donnerait lieu à des failles de sécurité.

filterUsingPCRE()

• field : De type String, c'est le nom du champ à filtrer ;
• regex : De type String, c'est l'expression rationnelle à utiliser ;
• replacement (par défaut = DVP_DataFilter::DEFAULT_STRING) : De type String, c'est la valeur retournée si le champ n'est pas de type String ou s'il ne vérifie pas l'expression rationnelle ;
• mode (par défaut = DVP_DataFilter::PCRE_REPLACE) : C'est l'une des constantes DVP_DataFilter::PCRE_*, ce paramètre définit le comportement de la méthode filterUsingPCRE.

• DVP_AbsentOffsetException
• DVP_RegexException
• DVP_TypeException
• DVP_ValueException

Cette méthode est pratique mais son utilisation est complexe. Pour en simplifier l'utilisation, il est possible de définir d'autres methodes comme celles qui l'utilisent déjà (cf. ci-dessus).

untaint()

• field : De type String, c'est le nom du champ à marquer.

• DVP_AbsentOffsetException
• DVP_TypeException

Cette méthode est nécessaire pour un nombre très faible de cas particuliers, comme par exemple les messages utilisateurs. Il faut y prendre garde, car cette méthode introduit des données non filtrées dans l'application.

III-E-3. Les getteurs

getArray()

• field : Le champ à retourner.

• DVP_AbsentOffsetException
• DVP_TaintedException
• DVP_TypeException

$_POST->filterArray('checkboxes', DVP_DataFilter::ARRAY_INTS);
foreach($_POST->getArray('checkboxes') as $checkbox)
{
    echo $checkbox.'<br />'; // Afficher cette valeur est sans danger car elle a déjà été filtrée comme "numérique entier"
}

getFields()

• field : Le champ à retourner.

• aucune

$_POST->filterArray('checkboxes', DVP_DataFilter::ARRAY_INTS);
$_POST->filterSingleLine('login');

foreach($_POST->getFields() as $field)
{
    echo $field.'<br />';
}

$_POST->filterArray('checkboxes', DVP_DataFilter::ARRAY_INTS);
$_POST->filterSingleLine('login');

foreach($_POST as $field)
{
    echo $field.'<br />';
}

Le retour de la méthode ne contient aucune "valeur", uniquement les noms des champs ; ou plutôt, les valeurs sont les noms des champs, ce qui rend leur index inutile :

$_POST->filterArray('checkboxes', DVP_DataFilter::ARRAY_INTS);
$_POST->filterSingleLine('login');

foreach($_POST as $index => $field)
{
    echo $index.' '.$field.'<br />';
}

getHTML()

• field : Le champ à retourner.

• DVP_AbsentOffsetException
• DVP_TypeException
• DVP_ValueException

$_POST->filterSingleLine('login');
echo $_POST->getHTML('login');

getRaw()

• field : Le champ à retourner.

• DVP_AbsentOffsetException
• DVP_ArrayAccessException
• DVP_TaintedException
• DVP_TypeException

getRegex()

• field : Le champ à retourner ;
• delimiter (par défaut = DVP_DataFilter::REGEX_DELIMITER) : Le délimiteur de la regex.

• DVP_AbsentOffsetException
• DVP_TypeException

$_POST->filterSingleLine('login');
$regex = '#<user>'.$_POST->getRegex('login', '#').'.*</user>#Ui'; // Exemple : #<user>Yog.*</user>#Ui

$users_xml = file_get_contents('users.xml');

if(preg_match($users_xml, $regex))
{
    echo 'vrai';
}
else
{
    echo 'faux';
}

<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
    <user>Yogui</user>
    <user>BrYs</user>
</users>

L'exemple ci-dessus vérifie si un nom d'utilisateur (soumis par formulaire) existe dans un document XML contenant une liste d'utilisateurs.

getShellArgument()

• field : Le champ à retourner.

• DVP_AbsentOffsetException
• DVP_TypeException

getShellCommand()

• field : Le champ à retourner.

• DVP_AbsentOffsetException
• DVP_TypeException

getSQL()

• field : Le champ à retourner ;
• dbms (par défaut = DVP_DataFilter::DEFAULT_DBMS) : Le SGBD de destination ;
• argument (par défaut = NULL) : Pour PostgreSQL, il prend comme valeur "string" ou "bytea" ; pour MySQL, il correspond à l'identifieur de ressource.

• DVP_DBMSEscapeException
• DVP_AbsentOffsetException
• DVP_PostgreSQLException
• DVP_TypeException
• DVP_ValueException