Documentation
Helper DataFilter
Table des matières ▼
Présentation
Helper servant à valider des données, pour vérifier qu'elle respectent un contrat. Cela peut-être utile pour vérifier que les données en entrée d'une API sont conformes à ce qui est attendu.
Exemples de contrats
Validation automatique (pass-through) :
null
Types
Types scalaires :
'null'
'false'
'true'
'bool'
'int'
'float'
'string'
'email'
'url'
Tous les types sont nullables en préfixant un point d'interrogation :
'?bool'
'?false'
'?true'
'?int'
'?float'
'?string'
'?email'
'?url'
'?enum'
'?list'
'?assoc'
Il est possible d'utiliser des types multiples. Par exemple :
'null|int|string'
'int|float'
Paramètres
En plus de la définition de type, les contrats peuvent prendre des paramètres.
Les paramètres peuvent s'écrire de deux manières différentes :
- Ils peuvent être ajouté à la chaîne de configuration du contrat, à la suite de la définition de type. Les paramètres sont alors séparés par des caractères point-virgule (;), et le nom du paramètre est séparé de sa valeur par un caractère deux-points (:).
- Il est aussi possible d'écrire les contrats sous forme de tableau associatif. Le type est les paramètres sont autant de couples clé/valeur dans le tableau. Cette écriture est obligatoire lorsqu'il faut définir des sous-contrats.
Types scalaires avec une valeur par défaut :
// booléen, faux par défaut
'bool;default:false'
[
'type' => 'bool',
'default' => false,
]
// entier, 100 par défaut
'int;default:100'
[
'type' => 'int',
'default' => 100,
]
// chaîne de caractère, "abc" par défaut
'string; default: abc'
[
'type' => 'string',
'default' => 'abc',
]
Nombre (entier ou flottant) avec une valeur minimale et/ou maximale :
// entier supérieur ou égal à 1
'int; min:1'
[
'type' => 'int',
'min' => 1,
]
// flottant valant entre -8,12 et +8,12
'float; min:-8.12; max:8.12'
[
'type' => 'float',
'min' => -8.12,
'max' => 8.12,
]
Chaîne de caractère avec une longueur minimale et/ou maximale, ou devant valider une expression régulière :
// chaîne de 1 à 12 caractères
'string; minlen: 1; maxlen: 12'
[
'type' => 'string',
'minlen' => 1,
'maxlen' => 12,
]
// chaîne validant une expression régulière
'string; mask: ^[Bb][Oo0]..[Oo0].r$'
[
'type' => 'string',
'mask' => '^[Bb][Oo0]..[Oo0].r$',
]
Adresse mail, éventuellement avec une expression régulière :
'email'
// adresse mail qui se termine par "@domain.com"
'email; mask: @domain.com$'
[
'type' => 'email',
'mask' => '@domain.com$',
]
URL, éventuellement avec une taille minimale, une taille maximale et/ou une expression régulière :
'url'
// URL de 15 à 35 caractères se terminant par "domain.com"
'url; minlen: 15; maxlen: 35; mask: domain.com$'
[
'type' => 'url',
'minlen' => 15,
'maxlen' => 35,
'mask' => 'domain.com$',
]
Énumération, avec ou sans valeur par défaut :
'enum; values: red, green, blue; default: red'
[
'type' => 'enum',
'values' => ['red', 'green', 'blue'],
'default' => 'red',
]
Liste, avec un contrat servant à valider que tous ses éléments sont des nombres entiers :
'list; contract: int'
[
'type' => 'list',
'contract' => 'int',
]
Tableau associatif, avec la définition de ses clés :
'assoc; keys: id, name'
[
'type' => 'assoc',
'keys' => [
'id',
'name',
]
]
Tableau associatif, avec la définition de ses clés, certaines ayant un type associé :
[
'type' => 'assoc',
'keys' => [
'id' => 'int',
'name' => 'string',
'dateCreation',
]
]
Liste avec un contrat qui définit que ses valeurs doivent être des tableaux associatifs dont les clés sont définies :
[
'type' => 'list',
'contract' => [
'type' => 'assoc',
'keys' => ['id', 'name'],
]
]
Tableau associatif dont les clés sont définies. Les clés sont typées, et l'une d'elles est optionnelle :
[
'type' => 'assoc',
'keys' => [
'id' => 'int',
'name' => [
'type' => 'string',
'mandatory' => false,
]
]
]
Exemple complexe :
[
'type' => 'assoc',
'keys' => [
'id' => 'int',
'isCreated' => 'bool',
'name' => 'string; default: abc',
'color' => [
'type' => 'enum',
'values' => ['red', 'green', 'blue'],
'default' => 'red',
'mandatory' => false,
],
'creator' => [
'type' => 'assoc',
'keys' => [
'id' => 'int',
'name',
'dateCreation',
],
],
'children' => [
'type' => 'list',
'mandatory' => false,
'contract' => [
'type' => 'assoc',
'keys' => [
'id' => 'int',
'name',
]
],
],
'identifiers' => [
'type' => 'list',
'contract' => 'int',
],
],
]
Utilisation
L'objet \Temma\Utils\DataFilter offre une méthode statique process(). Cette méthode prend en paramètre la donnée à filtrer et le contrat à utiliser, et elle retourne la donnée filtrée. Si la syntaxe du contrat est incorrecte, la méthode lève une exception \Temma\Exceptions\IO. Si la donnée ne respecte pas le contrat, la méthode lève une exception \Temma\Exceptions\Application.
Exemple d'utilisation :
use \Temma\Utils\Datafilter as TµDataFilter;
use \Temma\Exceptions\IO as TµIOException;
use \Temma\Exceptions\Application AS TµApplicationException;
use \Temma\Base\Log as TµLog;
$contract = 'enum; values: admin, member, guest';
/* équivalent à la ligne précédente :
$contract = [
'type' => 'enum',
'values' => ['admin', 'member', 'guest'],
];
*/
try {
$data = TµDatafilter::process($data, $contract);
} catch (TµIOException $ie) {
TµLog::log('myapp', 'WARN', "Contrat incorrect.");
throw $ie;
} catch (TµApplicationException $ae) {
TµLog::log('myapp', 'WARN', "Données incorrectes.");
throw $ae;
}
Précédent : | Helper BaseConvert |
Suivant : | Helper Email |
Table des matières
- Migration : Comment passer de Temma 1.x à la version 2
- Installation : Télécharger Temma et l'installer pour démarrer votre projet Web
- Configuration : Toutes les directives de configuration du fichier etc/temma.json et les variables d'environnement utilisables en option
- Bibliothèques externes : Comment utiliser des bibliothèques de fonctions externes
- Routage : Le système de routage par défaut de Temma, et le routage avancé
- Log : Utilisation du système de log, gestion par niveaux de criticité
- Contrôleurs : Pièces essentiels de votre application Web
- Vues : Templates Smarty ou exports JSON/CSV/RSS/iCal/INI
- Injection de dépendances : La colonne vertébrale de vos développements applicatifs
- Sessions : Extension des sessions utilisateurs gérées par PHP
- Sources de données : Pour gérer l'accès aux données de manière unifiée
- Modèle : Comment utiliser les DAO pour accéder aux bases de données
- Flux d'exécution : Comment gérer le flux d'exécution, entre les plugins et le contrôleur
- Plugins : Comment utiliser les plugins, et écrire les vôtres pour modulariser votre code
- Attributs : Comment filtrer l'accès aux contrôleurs et aux actions
- Tests : Pour écrire des tests d'intégration automatisés.
- Interface en ligne de commande : Pour créer des scripts exécutables en ligne de commande, initialisés automatiquement par Temma
-
Helpers :
Objets proposés par Temma pour vous aider dans plusieurs circonstances
- Scripts en ligne de commande
-
Contrôleur + plugin
- Auth : Contrôleur et plugin servant à gérer l'authentification des utilisateurs
- Plugins
- Attributs
-
Plugins Smarty
- urlize : Modificateur transformant un texte en URL
- filenamize : Modificateur transformant un texte en nom de fichier
- nbsp : Modificateur transformant des espaces en espaces non sécables
-
Objets utilitaires
- ANSI : Pour mettre en forme les textes écrits sur la sortie standard
- BaseConvert : Pour faire des conversions de bases numériques
- DataFilter : Pour filtrer et valider des données
- Email : Pour envoyer des emails
- HTMLCleaner : Pour nettoyer un flux HTML provenant d'un éditeur WYSIWYG
- IniExport : Pour exporter des données au format INI
- Json : Pour lire des flux JSON pouvant contenir des commentaires
- Lock : Pour verrouiller l'accès à un fichier, ou l'exécution du script PHP courant
- Registry : Pour stocker proprement des variables globales
- Smarty : Pour traiter des templates Smarty en dehors de la vue
- Term : Gestion des terminaux (TTY)
- Text : Différents traitements sur les chaînes de caractères
- Timer : Pour gérer des chronomètres