nur-sery/doc/schema.md

91 lines
2.7 KiB
Markdown
Raw Normal View History

2023-11-20 23:14:11 +04:00
# nulib\schema
objet: s'assurer que des données soit dans un type particulier, en les
convertissant si nécessaire. la source de ces données peut-être diverse:
formulaire web, résultat d'une requête SQL, flux CSV, etc. mais en définitive,
les données qui sont traitées par du code PHP sont du bon type et au bon
format, ou une erreur est levée.
## Schéma d'une valeur simple
Une valeur scalaire est modélisée de cette manière:
~~~php
const SIMPLE_SCHEMA = [
"type" => "types autorisés de la valeur",
"default" => "valeur par défaut si la valeur n'existe pas",
"title" => "libellé de la valeur, utilisable par exemple dans un formulaire",
"desc" => "description de la valeur",
"required" => "la valeur est-elle requise? si oui, elle doit exister",
"nullable" => "si la valeur existe, peut-elle être nulle?",
"checker_func" => "une fonction qui vérifie une valeur et la classifie",
"parser_func" => "une fonction qui analyse une chaine pour produire la valeur",
"messages" => "messages à afficher en cas d'erreur d'analyse",
"formatter_func" => "une fonction qui formatte la valeur pour affichage",
"format" => "format à utiliser pour l'affichage",
"" => "nature du schéma: scalar",
];
~~~
Le schéma d'une valeur simple peut avoir les formes suivantes:
- la forme normalisée contient la nature de schéma qui vaut `scalar` et toutes
les autres clés spécifiées ci-dessus
- la forme habituelle qui a au moins une valeur de type chaine et d'index 0 pour le type
par exemple, les deux schémas suivants sont équivalents:
~~~php
const NORMALIZED = [
"" => ["scalar"],
"type" => "string",
"default" => null,
"title" => "valeur chaine",
"desc" => "une description plus longue",
"required" => false,
"nullable" => true,
...
];
const SIMPLE = [
"?string", null, "valeur chaine",
"desc" => "une valeur chaine quelconque",
...
];
~~~
## Schéma d'une liste séquentielle
Une liste séquentielle est modélisée de cette manière:
~~~php
const LIST_SCHEMA = [SIMPLE_SCHEMA];
~~~
Ce schéma a un unique élément d'index 0, qui représente le schéma de chaque
élément de la liste
~~~php
const NORMALIZED = [
"" => ["list",
"title" => "liste de valeurs chaines",
"desc" => "une description plus longue",
"required" => false,
"nullable" => true,
],
ITEM_SCHEMA,
];
~~~
## Schéma d'un tableau associatif
~~~php
const NORMALIZED = [
"" => ["assoc",
"title" => "liste de valeurs chaines",
"desc" => "une description plus longue",
"required" => false,
"nullable" => true,
],
KEY => VALUE_SCHEMA,
...
];
~~~
-*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary