nur-sery/doc/schema.md

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:

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:

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:

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

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

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